63 lines
2.8 KiB
Rust
63 lines
2.8 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.
|
|
//!
|
|
//! **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");
|
|
}
|
|
}
|