DifferV3 does not account for non-round-trippable backend fields, causing unnecessary sync events #427

Problem

When ADC is used with backends that do not support all SDK-level fields (e.g., backend-api7), DifferV3 produces false diffs every sync cycle because some fields sent in the local state cannot round-trip through the backend.

For example, with backend-api7:

• route.hosts — API7 EE route model does not have hosts (it is a service-level field)
• route.remote_addrs — not in API7 EE route typing
• route.filter_func — not in API7 EE route typing
• stream_route.sni — not in API7 EE stream_route typing

These fields exist in the ADC SDK schema and are correctly supported by backend-apisix, but backend-api7 transformers (ToADC/FromADC) do not map them. As a result, DifferV3 always detects a diff and triggers PUT requests even when no actual change occurred.

Impact

In Ingress Controller deployments, this causes every route and service to be PUT on every sync cycle (default: every 5 minutes), leading to massive audit log growth (customer case: 8 GB / 4.2M records).

Root Cause

DifferV3 is completely backend-agnostic — it only receives defaultValue from the backend and has no mechanism to know which fields a backend cannot round-trip. The diff comparison includes all fields present in either local or remote state, including fields the backend silently drops.

Proposed Solution

Add an optional normalizeForDiff method to the Backend interface:

interface Backend {
  // ... existing methods ...

  /**
   * Normalize a resource before diff comparison.
   * Called on deep copies of both local and remote resources.
   * Backend should strip fields it cannot round-trip.
   */
  normalizeForDiff?: (
    resourceType: ResourceType,
    resource: object,
  ) => object;
}

DifferV3 would call this normalizer on deep copies of both local and remote items before comparison. BackendAPI7 would implement it to strip non-round-trippable fields. BackendAPISIX would not implement it (all fields are supported).

Non-Round-Trippable Fields Audit (backend-api7)

Notes on Type-Driven Normalization

backend-api7/src/typing.ts already defines typed interfaces that reflect the supported fields (e.g., typing.Route has no hosts), but these are pure TypeScript interfaces erased at compile time. Future evolution could convert them to Zod schemas for runtime field enumeration.