swarm-wire: take agent_icon's wire types

swarm-wire/src/agent_icon.rs

@@ -0,0 +1,63 @@
+//! The per-agent icon KV bucket: one key per agent, holding the icon the
+//! swarm shows for it.
+//!
+//! **Keyed by the agent alone — no hive token**, which is the one way this
+//! bucket deliberately differs from its otherwise-identical sibling
+//! `swarm_wire::agent_status` (`{hive}.{agent}`). An agent is not fixed to a
+//! hive and can move between them; an icon keyed by where the agent
+//! currently runs would be stranded under the old key by a migration, and
+//! a reader would have to know the placement to ask the question at all.
+//! Operator ruling: *"the bucket is per agent, not per hive. agents can
+//! move hives."*
+//!
+//! That is also what makes the icon answerable for an agent whose
+//! container is stopped: the value's lifetime is the agent's, not its
+//! placement's.
+//!
+//! **Each agent writes its own key** with its own queue credential. The auth
+//! callout grants that credential `$KV.agent-icons.<agent>` and no other key.
+//!
+//! The writer publishes to [`subject`] directly instead of opening the
+//! bucket, so that one subject is its whole grant. Creating the bucket is left
+//! to the reader (`swarm_queue_client::agent_icon::open_or_create`). A write
+//! that arrives before the bucket exists is refused with "no stream", and the
+//! writer retries.
+
+/// The KV bucket agent icons are published into, keyed by agent name.
+///
+/// A constant and not an option, for the reason
+/// [`crate::agent_status::BUCKET`] gives: writer and reader must name the
+/// same bucket, and an option is a way for the two to disagree.
+pub const BUCKET: &str = "agent-icons";
+
+/// The media type of every value in this bucket.
+///
+/// The value is the icon's bytes **verbatim, not a JSON envelope**: an SVG
+/// carries no metadata this bucket would have to describe, and the one
+/// consumer serves the bytes straight back out. So the type is fixed here
+/// rather than stored per entry — a publisher that has something other
+/// than an SVG does not have an agent icon.
+pub const MEDIA_TYPE: &str = "image/svg+xml";
+
+/// The subject `agent`'s entry is written on: `$KV.<bucket>.<key>`, where the
+/// key is the agent name and nothing else.
+///
+/// A KV put is a `JetStream` publish to this subject, so a writer that
+/// publishes directly has to use the same subject the bucket's `get` reads.
+#[must_use]
+pub fn subject(agent: &str) -> String {
+    format!("$KV.{BUCKET}.{agent}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::subject;
+
+    /// One token after the bucket, the agent name alone. That is what the
+    /// per-agent grant `$KV.agent-icons.{agent}` expands to, and what a
+    /// hive-scoped grant (`$KV.<bucket>.<hive>.*`, two tokens) cannot match.
+    #[test]
+    fn the_published_subject_carries_the_agent_and_no_placement() {
+        assert_eq!(subject("iris"), "$KV.agent-icons.iris");
+    }
+}

swarm-wire/src/lib.rs

@@ -5,6 +5,7 @@
 //! names a contract (the sender, the answerer, the auth-callout responder that
 //! grants the subject) depends on this one without linking either.
 
+pub mod agent_icon;
 pub mod agent_inference;
 pub mod agent_login;
 pub mod agent_status;