Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/swarm-wire/src/agent_icon.rs

60 lines
2.6 KiB
Rust

//! 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.<bucket>.<key>`, 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.<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");
}
}