60 lines
2.6 KiB
Rust
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");
|
|
}
|
|
}
|