logs and metrics permissions, tolerant record decode, hive capabilities

swarm-wire/src/hive_status.rs

@@ -0,0 +1,73 @@
+//! What a hive's status snapshot (`swarm_queue_client::status`) says about
+//! what the hive can do, next to its readiness.
+//!
+//! The snapshot is opaque to the controller except for this field. A snapshot
+//! from a hive that predates it has none, which reads as an empty list.
+
+/// The hive decodes a permission list that names a permission it does not
+/// know by skipping that name, and runs agents on a harness that does too.
+/// swarm-controller writes `logs` or `metrics` into an agent's record only
+/// when the agent's hive advertises this.
+pub const TOLERANT_PERMISSIONS: &str = "tolerant-permissions";
+
+/// The part of a hive's status snapshot this module describes.
+#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct Capabilities {
+    /// Capability names; unknown names are ignored by every reader.
+    #[serde(default)]
+    pub capabilities: Vec<String>,
+}
+
+impl Capabilities {
+    /// Whether the hive advertises `name`.
+    #[must_use]
+    pub fn has(&self, name: &str) -> bool {
+        self.capabilities.iter().any(|c| c == name)
+    }
+
+    /// The capabilities in a stored snapshot; none when it has no such field
+    /// or is not an object.
+    #[must_use]
+    pub fn of_snapshot(snapshot: &serde_json::Value) -> Self {
+        serde_json::from_value(snapshot.clone()).unwrap_or_default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A snapshot from before the field existed: it parses, with nothing
+    /// advertised.
+    #[test]
+    fn a_snapshot_without_the_field_advertises_nothing() {
+        let old = serde_json::json!({"status": "ok", "warnings": []});
+        let caps = Capabilities::of_snapshot(&old);
+        assert!(!caps.has(TOLERANT_PERMISSIONS));
+        assert_eq!(caps, Capabilities::default());
+    }
+
+    #[test]
+    fn an_advertised_capability_is_found_among_unknown_ones() {
+        let new = serde_json::json!({
+            "status": "ok",
+            "warnings": [],
+            "capabilities": ["from-the-future", TOLERANT_PERMISSIONS],
+        });
+        assert!(Capabilities::of_snapshot(&new).has(TOLERANT_PERMISSIONS));
+        assert!(!Capabilities::of_snapshot(&new).has("other"));
+    }
+
+    /// A snapshot that is not an object, or whose field is mistyped, grants
+    /// nothing rather than failing the read.
+    #[test]
+    fn a_malformed_snapshot_advertises_nothing() {
+        for bad in [
+            serde_json::json!(null),
+            serde_json::json!("ok"),
+            serde_json::json!({"capabilities": "tolerant-permissions"}),
+        ] {
+            assert!(!Capabilities::of_snapshot(&bad).has(TOLERANT_PERMISSIONS));
+        }
+    }
+}