//! 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. //! //! **The swarm controller is the only writer.** It writes the key from the //! builder's reply when it builds the agent for a deploy: the builder reads the //! icon from the agent's config, so the write needs no running agent. An icon //! that is not set deletes the key. No agent credential may write here, and the //! controller creates the bucket (`swarm_queue_client::agent_icon::open_or_create`). //! [`subject`] is the subject a KV put to a key goes to. /// 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..`, where the /// key is the agent name and nothing else. /// /// A KV put is a `JetStream` publish to this subject, and the bucket's `get` /// reads the same one. #[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: no hive in the key, so /// a hive-scoped subject (`$KV...*`, two tokens) cannot match. #[test] fn the_published_subject_carries_the_agent_and_no_placement() { assert_eq!(subject("iris"), "$KV.agent-icons.iris"); } }