hecks 3.14.0 → 5.0.0

data/rust/host/src/ir.rs

@@ -17,7 +17,10 @@ pub fn ir() -> Option<&'static Value> {
 /// Aggregates bound to a lineage-capable adapter, as `(qualified_name,
 /// storage_name)` — read from `ir.json`'s own `lineage` key.
 pub fn lineage_capable_aggregates(domain_ir: &Value) -> Vec<(String, String)> {
-    let domain_name = domain_ir.get("name").and_then(|v| v.as_str()).unwrap_or_default();
+    let domain_name = domain_ir
+        .get("name")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default();
     domain_ir
         .get("lineage")
         .and_then(|l| l.get("capable_aggregates"))
@@ -56,12 +59,66 @@ pub fn persistence_adapters(domain_ir: &Value) -> Vec<(String, String)> {
 }
 
 /// The only persistence adapters `rust/host` has a real backend for — see
-/// `refuse_unsupported_persistence_adapters` below.
+/// `refuse_unsupported_persistence_adapters` below. Must list the same names
+/// as [`BACKENDS`] (a test holds them together).
 pub const SUPPORTED_PERSISTENCE_ADAPTERS: &[&str] = &["Postgres", "PostgresEra"];
 
+/// What serves a bound adapter inside this host.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Backend {
+    /// The one `tokio_postgres` engine (journal tables, era heads).
+    TokioPostgres,
+}
+
+/// The host's implemented backends, adapter name -> backend. A future backend
+/// is one more row here (and one in [`SUPPORTED_PERSISTENCE_ADAPTERS`]).
+pub const BACKENDS: &[(&str, Backend)] = &[
+    ("Postgres", Backend::TokioPostgres),
+    ("PostgresEra", Backend::TokioPostgres),
+];
+
+/// The backend that serves `adapter`, if the host has one.
+pub fn backend_for(adapter: &str) -> Option<Backend> {
+    BACKENDS
+        .iter()
+        .find(|(name, _)| *name == adapter)
+        .map(|(_, backend)| *backend)
+}
+
+/// The port every persistence binding must be declared against.
+const PERSISTENCE_PORT: &str = "persistence";
+
+/// `ir.json`'s own `adapters` key, as `name -> declaration`. `None` when the
+/// key is absent (an older IR); `Some(Err(..))` when present but malformed
+/// (not an array, or an entry without a string `name`).
+pub fn adapter_declarations(
+    domain_ir: &Value,
+) -> Option<Result<std::collections::BTreeMap<String, &Value>, String>> {
+    let raw = domain_ir.get("adapters")?;
+    let Some(entries) = raw.as_array() else {
+        return Some(Err(
+            "the IR's \"adapters\" key is not an array of adapter declarations".to_string(),
+        ));
+    };
+    let mut declared = std::collections::BTreeMap::new();
+    for (index, entry) in entries.iter().enumerate() {
+        match entry.get("name").and_then(|n| n.as_str()) {
+            Some(name) => {
+                declared.insert(name.to_string(), entry);
+            }
+            None => {
+                return Some(Err(format!(
+                    "the IR's \"adapters\" entry {index} has no string \"name\""
+                )))
+            }
+        }
+    }
+    Some(Ok(declared))
+}
+
 /// The chapter this domain's role checks resolve against, read from
 /// `ir.json`'s own `authorization` key. `None` when nothing provides it.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuthorizationProvider {
     /// Qualified grant command, e.g. `Governance::RoleAssignment.Assign`.
     pub grant: String,
@@ -80,7 +137,7 @@ pub fn authorization_provider(domain_ir: &Value) -> Option<AuthorizationProvider
 
 /// The chapter that answers "who may sign in", read from `ir.json`'s own
 /// `membership` key. `None` when nothing provides `"membership"`.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct MembershipProvider {
     /// Chapter name, e.g. `Membership`.
     pub provider: String,
@@ -91,8 +148,10 @@ pub struct MembershipProvider {
 /// Aggregates whose mutations mirror into their era head: the lineage-capable
 /// ones plus the membership aggregate, which is not itself lineage-capable.
 pub fn mirrored_aggregates(domain_ir: &Value) -> std::collections::BTreeSet<String> {
-    let mut mirrored: std::collections::BTreeSet<String> =
-        lineage_capable_aggregates(domain_ir).into_iter().map(|(qualified, _)| qualified).collect();
+    let mut mirrored: std::collections::BTreeSet<String> = lineage_capable_aggregates(domain_ir)
+        .into_iter()
+        .map(|(qualified, _)| qualified)
+        .collect();
     if let Some(membership) = membership_provider(domain_ir) {
         mirrored.insert(membership.aggregate);
     }
@@ -110,7 +169,7 @@ pub fn membership_provider(domain_ir: &Value) -> Option<MembershipProvider> {
 /// The chapter that answers "who is this authenticated pair", read from
 /// `ir.json`'s own `identity` key. `None` when nothing provides `"identity"`.
 /// Link's reference field must stay `identity` — never `identity_id`, never `to:`.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct IdentityProvider {
     /// Chapter name, e.g. `Identity`.
     pub provider: String,
@@ -132,12 +191,117 @@ pub fn identity_provider(domain_ir: &Value) -> Option<IdentityProvider> {
     })
 }
 
+/// Settings a world binding carries that are not adapter fields.
+const WORLD_EXEMPT_SETTINGS: &[&str] = &["adapter", "role"];
+
+fn world_error(what: &str) -> String {
+    format!("the IR's \"world\" {what}")
+}
+
+fn declared_names(declaration: &Value) -> std::collections::BTreeSet<&str> {
+    ["fields", "secrets"]
+        .iter()
+        .filter_map(|key| declaration.get(key)?.as_array())
+        .flatten()
+        .filter_map(|name| name.as_str())
+        .collect()
+}
+
+fn check_world_binding(
+    binding: &Value,
+    declared: &std::collections::BTreeMap<String, &Value>,
+) -> Result<(), String> {
+    let adapter = binding
+        .get("adapter")
+        .and_then(|a| a.as_str())
+        .ok_or_else(|| world_error("persistence entry has no string \"adapter\""))?;
+    let settings = binding
+        .get("settings")
+        .and_then(|s| s.as_array())
+        .ok_or_else(|| world_error("persistence entry's \"settings\" is not an array"))?;
+    let Some(declaration) = declared.get(adapter) else {
+        return Ok(());
+    };
+    let known = declared_names(declaration);
+    for setting in settings {
+        let name = setting
+            .as_str()
+            .ok_or_else(|| world_error("persistence entry has a setting that is not a string"))?;
+        if !WORLD_EXEMPT_SETTINGS.contains(&name) && !known.contains(name) {
+            return Err(format!(
+                "{adapter} does not declare {name:?} — the world sets it, but the adapter declares \
+                 {known:?}. Add the field to the adapter, or remove it from the world."
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Refuses a world that sets, on a declared persistence adapter, a setting the adapter does not
+/// declare as a field or secret (`adapter` and `role` are exempt). Entries for adapters the IR's
+/// `adapters` key does not declare are skipped, and an IR without a `world` key is not checked.
+pub fn refuse_undeclared_world_settings(domain_ir: &Value) -> Result<(), String> {
+    let Some(world) = domain_ir.get("world") else {
+        return Ok(());
+    };
+    if !world.is_object() {
+        return Err(world_error("key is not an object"));
+    }
+    let entries = world
+        .get("persistence")
+        .and_then(|p| p.as_array())
+        .ok_or_else(|| world_error("\"persistence\" is not an array"))?;
+    let declared = match adapter_declarations(domain_ir) {
+        Some(declared) => declared?,
+        None => return Ok(()),
+    };
+    entries
+        .iter()
+        .try_for_each(|binding| check_world_binding(binding, &declared))
+}
+
 /// Refuses at boot rather than silently building a second, disjoint history
 /// nothing but this runtime reads while the real state lives elsewhere.
+///
+/// Each aggregate's bound adapter is looked up in the IR, then in the host's
+/// [`BACKENDS`] table. Rules, in order:
+/// 1. When the IR carries an `adapters` key (even empty), the bound adapter
+///    must be declared there.
+/// 2. That declaration's `port`, when non-null, must be `"persistence"`.
+/// 3. The adapter must have a host backend (the long-standing refusal).
+///
+/// Compatibility: deployed IR files predate the `adapters` key. When it is
+/// absent, rules 1 and 2 are skipped and only rule 3 applies, exactly as
+/// before. A present-but-malformed `adapters` value is refused with a
+/// message naming the problem (it never panics).
 pub fn refuse_unsupported_persistence_adapters(domain_ir: &Value) -> Result<(), String> {
-    let unsupported: Vec<String> = persistence_adapters(domain_ir)
+    refuse_undeclared_world_settings(domain_ir)?;
+    let bindings = persistence_adapters(domain_ir);
+    if let Some(declared) = adapter_declarations(domain_ir) {
+        let declared = declared?;
+        for (aggregate, adapter) in &bindings {
+            let Some(declaration) = declared.get(adapter) else {
+                return Err(format!(
+                    "{aggregate} binds {adapter}, which the domain's IR does not declare (no \
+                     .adapter file declares it) — refusing instead of guessing what it means"
+                ));
+            };
+            match declaration.get("port") {
+                None | Some(Value::Null) => {}
+                Some(Value::String(port)) if port == PERSISTENCE_PORT => {}
+                Some(port) => {
+                    return Err(format!(
+                        "{aggregate} binds {adapter}, which the domain's IR declares for port \
+                         {port} rather than {PERSISTENCE_PORT:?} — refusing a persistence \
+                         binding to a non-persistence adapter"
+                    ))
+                }
+            }
+        }
+    }
+    let unsupported: Vec<String> = bindings
         .into_iter()
-        .filter(|(_, adapter)| !SUPPORTED_PERSISTENCE_ADAPTERS.contains(&adapter.as_str()))
+        .filter(|(_, adapter)| backend_for(adapter).is_none())
         .map(|(name, adapter)| format!("{name} (persisted_by {adapter:?})"))
         .collect();
     if unsupported.is_empty() {
@@ -175,8 +339,10 @@ mod tests {
             "lineage": { "capable_aggregates": [{ "name": "Order", "storage_name": "order" }] },
             "membership": { "provider": "Membership", "aggregate": "Membership::Person" }
         });
-        let expected: std::collections::BTreeSet<String> =
-            ["Shop::Order", "Membership::Person"].into_iter().map(String::from).collect();
+        let expected: std::collections::BTreeSet<String> = ["Shop::Order", "Membership::Person"]
+            .into_iter()
+            .map(String::from)
+            .collect();
         assert_eq!(mirrored_aggregates(&ir), expected);
     }
 
@@ -186,7 +352,8 @@ mod tests {
             "name": "Shop",
             "lineage": { "capable_aggregates": [{ "name": "Order", "storage_name": "order" }] }
         });
-        let expected: std::collections::BTreeSet<String> = ["Shop::Order"].into_iter().map(String::from).collect();
+        let expected: std::collections::BTreeSet<String> =
+            std::iter::once("Shop::Order").map(String::from).collect();
         assert_eq!(mirrored_aggregates(&ir), expected);
         assert!(mirrored_aggregates(&serde_json::json!({ "name": "Banking" })).is_empty());
     }
@@ -194,7 +361,10 @@ mod tests {
     #[test]
     fn lineage_capable_aggregates_is_empty_for_a_domain_with_no_lineage_key() {
         let ir = serde_json::json!({ "name": "Banking" });
-        assert_eq!(lineage_capable_aggregates(&ir), Vec::<(String, String)>::new());
+        assert_eq!(
+            lineage_capable_aggregates(&ir),
+            Vec::<(String, String)>::new()
+        );
     }
 
     #[test]
@@ -241,8 +411,63 @@ mod tests {
             ] }
         });
         let err = refuse_unsupported_persistence_adapters(&ir).unwrap_err();
-        assert!(err.contains("Account"), "error should name the offending aggregate: {err}");
-        assert!(err.contains("Heki"), "error should name the unsupported adapter: {err}");
+        assert!(
+            err.contains("Account"),
+            "error should name the offending aggregate: {err}"
+        );
+        assert!(
+            err.contains("Heki"),
+            "error should name the unsupported adapter: {err}"
+        );
+    }
+
+    fn world_ir(settings: &Value) -> Value {
+        serde_json::json!({
+            "adapters": [{"name": "PostgresEra", "port": "persistence",
+                          "fields": ["url"], "secrets": ["password"], "defaults": {}}],
+            "world": {"default_adapter": null, "default_database": false,
+                      "persistence": [{"adapter": "PostgresEra", "settings": settings}]}
+        })
+    }
+
+    #[test]
+    fn a_world_setting_the_adapter_does_not_declare_is_refused() {
+        let err =
+            refuse_undeclared_world_settings(&world_ir(&serde_json::json!(["bogus"]))).unwrap_err();
+        assert!(
+            err.contains("PostgresEra") && err.contains("bogus"),
+            "{err}"
+        );
+    }
+
+    #[test]
+    fn declared_fields_secrets_role_and_adapter_pass() {
+        let ir = world_ir(&serde_json::json!(["url", "password", "role", "adapter"]));
+        assert!(refuse_undeclared_world_settings(&ir).is_ok());
+    }
+
+    #[test]
+    fn an_undeclared_adapter_in_the_world_is_skipped() {
+        let mut ir = world_ir(&serde_json::json!(["bogus"]));
+        ir["adapters"] = serde_json::json!([]);
+        assert!(refuse_undeclared_world_settings(&ir).is_ok());
+    }
+
+    #[test]
+    fn an_ir_without_a_world_key_is_not_checked() {
+        assert!(refuse_undeclared_world_settings(&serde_json::json!({"name": "X"})).is_ok());
+    }
+
+    #[test]
+    fn a_malformed_world_is_refused() {
+        let mut not_object = world_ir(&serde_json::json!([]));
+        not_object["world"] = serde_json::json!("x");
+        let mut not_array = world_ir(&serde_json::json!([]));
+        not_array["world"]["persistence"] = serde_json::json!({});
+        let bad_setting = world_ir(&serde_json::json!([3]));
+        for ir in [not_object, not_array, bad_setting] {
+            assert!(refuse_undeclared_world_settings(&ir).is_err());
+        }
     }
 
     #[test]
@@ -276,12 +501,97 @@ mod tests {
         assert!(identity_provider(&serde_json::json!({ "name": "Pizzas" })).is_none());
     }
 
-
     #[test]
     fn refuse_unsupported_persistence_adapters_passes_a_domain_with_no_persistence_key() {
         let ir = serde_json::json!({ "name": "Pizzas" });
         assert!(refuse_unsupported_persistence_adapters(&ir).is_ok());
     }
+
+    fn bound(adapters: &[(&str, &str)]) -> Value {
+        let aggregates: Vec<Value> = adapters
+            .iter()
+            .map(|(n, a)| serde_json::json!({"name": n, "adapter": a}))
+            .collect();
+        serde_json::json!({"persistence": {"aggregates": aggregates}})
+    }
+
+    fn with_adapters(mut ir: Value, adapters: Value) -> Value {
+        ir["adapters"] = adapters;
+        ir
+    }
+
+    #[test]
+    fn backend_table_matches_the_supported_names() {
+        let names: Vec<&str> = BACKENDS.iter().map(|(n, _)| *n).collect();
+        assert_eq!(names, SUPPORTED_PERSISTENCE_ADAPTERS);
+    }
+
+    #[test]
+    fn absent_adapters_key_keeps_the_old_behaviour() {
+        assert!(refuse_unsupported_persistence_adapters(&bound(&[("A", "Postgres")])).is_ok());
+        let err = refuse_unsupported_persistence_adapters(&bound(&[("A", "Heki")])).unwrap_err();
+        assert!(err.starts_with("rust/host only has a backend"), "{err}");
+    }
+
+    #[test]
+    fn declared_and_supported_boots_with_null_or_persistence_port() {
+        let ir = with_adapters(
+            bound(&[("A", "Postgres"), ("B", "PostgresEra")]),
+            serde_json::json!([
+                {"name": "Postgres", "port": "persistence"},
+                {"name": "PostgresEra", "port": null}
+            ]),
+        );
+        assert!(refuse_unsupported_persistence_adapters(&ir).is_ok());
+    }
+
+    #[test]
+    fn empty_adapters_key_refuses_every_binding_as_undeclared() {
+        let ir = with_adapters(bound(&[("A", "Postgres")]), serde_json::json!([]));
+        let err = refuse_unsupported_persistence_adapters(&ir).unwrap_err();
+        assert!(
+            err.contains("A binds Postgres, which the domain's IR does not declare"),
+            "{err}"
+        );
+    }
+
+    #[test]
+    fn declared_but_unsupported_hits_the_backend_rule() {
+        let ir = with_adapters(
+            bound(&[("A", "Heki")]),
+            serde_json::json!([{"name": "Heki", "port": "persistence"}]),
+        );
+        let err = refuse_unsupported_persistence_adapters(&ir).unwrap_err();
+        assert!(err.starts_with("rust/host only has a backend"), "{err}");
+        assert!(err.contains("A (persisted_by \"Heki\")"), "{err}");
+    }
+
+    #[test]
+    fn wrong_port_is_refused_before_the_backend_rule() {
+        let ir = with_adapters(
+            bound(&[("A", "Postgres")]),
+            serde_json::json!([{"name": "Postgres", "port": "mail"}]),
+        );
+        let err = refuse_unsupported_persistence_adapters(&ir).unwrap_err();
+        assert!(
+            err.contains("A binds Postgres") && err.contains("\"mail\""),
+            "{err}"
+        );
+    }
+
+    #[test]
+    fn malformed_adapters_are_refused_not_panicked() {
+        for bad in [
+            serde_json::json!("x"),
+            serde_json::json!({"name": "Postgres"}),
+            serde_json::json!([{"port": "persistence"}]),
+            serde_json::json!([null, 3]),
+        ] {
+            let ir = with_adapters(bound(&[("A", "Postgres")]), bad);
+            let err = refuse_unsupported_persistence_adapters(&ir).unwrap_err();
+            assert!(err.contains("\"adapters\""), "{err}");
+        }
+    }
 }
 
 #[cfg(test)]