feat(config): lenient etcd parsing with tri-state compatibility reporting

CONTRIBUTING.md

@@ -46,6 +46,44 @@ still build and pass its structural checks
    implementation details.
 4. Make sure the checks above pass locally before pushing.
 
+### Changing resource models: unknown fields vs. new enum values
+
+The gateway reads its resources leniently from etcd and strictly on write
+(issue #871). That split makes two kinds of schema change behave very
+differently on a data plane that has not been upgraded yet, and each needs a
+different discipline:
+
+- **Adding a field** is the safe, expected change. An older gateway loads the
+  document with the new field ignored and reports it as partially compatible
+  (`GET /status/config` `partially_compatible[]`, the heartbeat, and the
+  `aisix_config_partially_compatible_resources` metric). Never assume a new
+  field is enforced fleet-wide until every data plane runs a version that
+  knows it — this matters most for restriction-type fields (an old gateway
+  keeps allowing what the new field would forbid). Two kinds are exempt from
+  this tolerance: `guardrail` and `observability_exporter` documents flatten
+  their fields into closed tagged shapes, so ANY new field there still
+  whole-row rejects on older gateways — treat additions to those two like
+  enum values below.
+- **Adding an enum value** (a routing strategy, an adapter, a guardrail
+  `kind`, …) is NOT forward compatible, by design: a value the gateway cannot
+  interpret has no old behavior to fall back to, so the whole document stays
+  rejected on older versions. Do not "fix" that by opening the enum. Every
+  new enum value needs an explicit rollout decision, made in the PR that adds
+  it:
+  1. **Version-gate at the control plane** (preferred for values that change
+     serving behavior): the control plane only offers the value once the
+     environment's data planes are on a version that knows it, using the
+     version the heartbeat already reports.
+  2. **Ship a degradable fallback** via `#[serde(other)]` — only when a
+     fallback is semantically safe (e.g. an advisory label where "unknown"
+     is a reasonable interpretation). Never for values that select serving
+     behavior: silently running a different routing strategy than configured
+     is worse than rejecting the document.
+  3. **Accept the rejection** for values that are new capabilities: an old
+     gateway that cannot serve the capability rejecting the row loudly (the
+     rejection reaches `rejected[]` and the heartbeat) can be the correct
+     outcome — state which of the three you chose and why in the PR.
+
 ### Commit and PR style
 
 Commit subjects follow Conventional Commits, matching the existing history:

Cargo.toml

@@ -81,6 +81,10 @@ webpki-roots = "0.26"
 # Serialization / validation
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+# Collects the paths of fields serde ignored during deserialization —
+# how the etcd loader reports unknown fields from a newer control plane
+# as "partially compatible" instead of dropping them silently (#871).
+serde_ignored = "0.1"
 jsonschema = "0.28"
 schemars = "0.8"
 

crates/aisix-admin/src/lib.rs

@@ -800,6 +800,8 @@ mod tests {
                 resource_counts: Default::default(),
             }),
             rejected: vec![],
+            partially_compatible: Vec::new(),
+            partially_compatible_rows_by_kind: Default::default(),
             is_reload: true,
             wholly_rejected: false,
         });
@@ -836,6 +838,12 @@ mod tests {
                 last_error: "schema validation failed at `/display_name`".into(),
                 seen_at: chrono::Utc::now(),
             }],
+            partially_compatible: vec![aisix_core::config_status::PartialCompatResource {
+                resource_kind: "api_keys".into(),
+                field: "quota_profile".into(),
+                count: 2,
+            }],
+            partially_compatible_rows_by_kind: [("api_keys".to_string(), 2)].into_iter().collect(),
             is_reload: true,
             wholly_rejected: false,
         });
@@ -866,6 +874,12 @@ mod tests {
         assert_eq!(v["applied"]["resource_counts"]["models"], 1);
         assert_eq!(v["rejected"][0]["resource_kind"], "models");
         assert_eq!(v["rejected"][0]["last_error_kind"], "schema_failed");
+        // The partially-compatible companion list (#871) rides next to
+        // rejected[] so a matching config_hash can't hide that some
+        // served rows carry fields this DP does not enforce.
+        assert_eq!(v["partially_compatible"][0]["resource_kind"], "api_keys");
+        assert_eq!(v["partially_compatible"][0]["field"], "quota_profile");
+        assert_eq!(v["partially_compatible"][0]["count"], 2);
     }
 
     #[tokio::test]
@@ -883,6 +897,8 @@ mod tests {
                 resource_counts: [("models".to_string(), 2)].into_iter().collect(),
             }),
             rejected: vec![],
+            partially_compatible: Vec::new(),
+            partially_compatible_rows_by_kind: Default::default(),
             is_reload: true,
             wholly_rejected: false,
         });

crates/aisix-core/src/bin/dump-schema.rs

@@ -38,38 +38,35 @@ fn main() {
     fs::create_dir_all(&out_dir).expect("create schemas/resources dir");
 
     // Every resource with a runtime validator goes through the SAME
-    // `*_root_schema()` producer the validator uses, so the published schema ==
-    // the enforced schema by construction. `ensemble`/`rate_limit`/`routing`
-    // have no standalone validator (they are nested struct types) so they dump
-    // straight from the struct via `schema_for!`.
-    dump_value(&out_dir, "api_key", schema::apikey_root_schema());
-    dump_value(&out_dir, "cache_policy", schema::cache_policy_root_schema());
-    dump_value(&out_dir, "model", schema::model_root_schema());
-    dump_value(
-        &out_dir,
+    // `resource_root_schema(name, strict: true)` producer the write-path
+    // validators compile, so the published schema == the enforced write
+    // contract by construction. The published files deliberately carry the
+    // STRICT shape: they document the Admin API write contract (unknown
+    // fields are a 400) and the etcd loader's lenient read tolerance is a
+    // runtime behavior, not a contract callers may write against.
+    // `ensemble`/`rate_limit`/`routing` have no standalone validator (they
+    // are nested struct types) so they dump straight from the struct via
+    // `schema_for!`, closed the same way.
+    for resource in [
+        "api_key",
+        "cache_policy",
+        "model",
         "rate_limit_policy",
-        schema::rate_limit_policy_root_schema(),
-    );
-    dump_value(&out_dir, "provider_key", schema::provider_key_root_schema());
-    dump_value(
-        &out_dir,
+        "provider_key",
         "observability_exporter",
-        schema::observability_exporter_root_schema(),
-    );
-    dump_value(&out_dir, "guardrail", schema::guardrail_root_schema());
-    dump_value(
-        &out_dir,
+        "guardrail",
         "guardrail_attachment",
-        schema::guardrail_attachment_root_schema(),
-    );
-    dump_value(&out_dir, "mcp_server", schema::mcp_server_root_schema());
-    dump_value(&out_dir, "mcp_policy", schema::mcp_policy_root_schema());
-    dump_value(&out_dir, "a2a_agent", schema::a2a_agent_root_schema());
-    dump_value(
-        &out_dir,
+        "mcp_server",
+        "mcp_policy",
+        "a2a_agent",
         "oidc_provider",
-        schema::oidc_provider_root_schema(),
-    );
+    ] {
+        dump_value(
+            &out_dir,
+            resource,
+            schema::resource_root_schema(resource, true),
+        );
+    }
 
     dump::<EnsembleConfig>(&out_dir, "ensemble");
     dump::<RateLimit>(&out_dir, "rate_limit");
@@ -81,14 +78,48 @@ fn main() {
 fn dump<T: JsonSchema>(out_dir: &Path, name: &str) {
     // Serialize the `RootSchema` directly to preserve schemars' native key
     // ordering. (Routing through `serde_json::Value` would re-sort keys.)
-    let mut json =
-        serde_json::to_string_pretty(&schemars::schema_for!(T)).expect("serialize schema");
+    // These nested types belong to closed resources, so re-close the root
+    // and every struct-shaped definition on the typed schema — the same
+    // strictness `schema::close_unknown_fields` applies to the resource
+    // documents, kept typed here so the key order stays schemars-native.
+    let mut root = schemars::schema_for!(T);
+    close_object_schema(&mut root.schema);
+    for def in root.definitions.values_mut() {
+        if let schemars::schema::Schema::Object(obj) = def {
+            close_object_schema(obj);
+        }
+    }
+    let mut json = serde_json::to_string_pretty(&root).expect("serialize schema");
     json.push('\n');
     let path = out_dir.join(format!("{name}.schema.json"));
     fs::write(&path, json).unwrap_or_else(|e| panic!("write {}: {e}", path.display()));
     println!("wrote {}", path.display());
 }
 
+/// Insert `additionalProperties: false` on a struct-shaped schema object
+/// (one that lists `properties`), unless it already pins a value. Recurses
+/// into `anyOf` branches so an untagged enum's object variant closes too —
+/// serde silently swallows unknown fields inside untagged content, so the
+/// schema closure is the only non-silent guard there (the resource
+/// producers apply the same rule, e.g. `OnEmbeddingFailure` in `model`).
+fn close_object_schema(schema: &mut schemars::schema::SchemaObject) {
+    if let Some(sub) = schema.subschemas.as_deref_mut() {
+        if let Some(any_of) = sub.any_of.as_mut() {
+            for branch in any_of.iter_mut() {
+                if let schemars::schema::Schema::Object(b) = branch {
+                    close_object_schema(b);
+                }
+            }
+        }
+    }
+    let Some(object) = schema.object.as_deref_mut() else {
+        return;
+    };
+    if !object.properties.is_empty() && object.additional_properties.is_none() {
+        object.additional_properties = Some(Box::new(schemars::schema::Schema::Bool(false)));
+    }
+}
+
 /// Write a pre-assembled schema `Value`. Used for resources whose canonical
 /// schema is built by a dedicated producer rather than a bare `schema_for!`
 /// (e.g. `model`, which injects the cross-field `oneOf`).