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

[jarvis9443]

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)

Resource	Field	Reason
Route	hosts	Not in API7 EE route model (service-level)
Route	remote_addrs	Not in API7 EE route typing
Route	filter_func	Not in API7 EE route typing
StreamRoute	sni	Not in API7 EE stream_route typing

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.

[coderabbitai]

🔗 Related PRs

#425 - fix: make upstream optional in backend-api7 typing [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!