harmony/harmony-reconciler-contracts/src/kv.rs

//! NATS JetStream KV bucket names and key formats used by the
//! harmony reconciler pattern.
//!
//! Hard-coded literals previously lived in five places (agent and
//! operator main.rs, operator deploy YAML, two smoke scripts).
//! Changing any of them meant hunting for the others. They now live
//! here; agent + operator consume the constants directly, and smoke
//! scripts grep for the literal values locked in the tests below.

use crate::fleet::DeploymentName;

/// Operator-written bucket. One entry per `(device, deployment)` pair.
/// Values are the JSON-serialized Score envelope — today
/// `harmony::modules::podman::ReconcileScore`, tomorrow any variant of
/// a polymorphic `Score` enum the framework ships.
pub const BUCKET_DESIRED_STATE: &str = "desired-state";

/// Static-ish per-device facts: routing labels, inventory, agent
/// version. Agent rewrites the entry on startup and whenever its
/// labels change. Key format: `info.<device_id>`.
pub const BUCKET_DEVICE_INFO: &str = "device-info";

/// Current reconcile phase for each `(device, deployment)` pair.
/// Agent writes on phase transition; operator watches this bucket
/// to drive CR `.status.aggregate`. Authoritative source of truth
/// for "what's running where." Key format:
/// `state.<device_id>.<deployment>`.
pub const BUCKET_DEVICE_STATE: &str = "device-state";

/// Tiny liveness ping from each device every N seconds. Separate
/// from [`BUCKET_DEVICE_STATE`] so routine heartbeats don't churn
/// the state bucket. Key format: `heartbeat.<device_id>`.
pub const BUCKET_DEVICE_HEARTBEAT: &str = "device-heartbeat";

/// KV key for a `(device, deployment)` pair in [`BUCKET_DESIRED_STATE`].
/// Format: `<device>.<deployment>`.
pub fn desired_state_key(device_id: &str, deployment_name: &DeploymentName) -> String {
    format!("{device_id}.{}", deployment_name.as_str())
}

/// KV key for a device's `DeviceInfo` entry in [`BUCKET_DEVICE_INFO`].
/// Format: `info.<device_id>`.
pub fn device_info_key(device_id: &str) -> String {
    format!("info.{device_id}")
}

/// KV key for a `(device, deployment)` state entry in
/// [`BUCKET_DEVICE_STATE`]. Format: `state.<device_id>.<deployment>`.
pub fn device_state_key(device_id: &str, deployment_name: &DeploymentName) -> String {
    format!("state.{device_id}.{}", deployment_name.as_str())
}

/// KV key for a device's liveness entry in
/// [`BUCKET_DEVICE_HEARTBEAT`]. Format: `heartbeat.<device_id>`.
pub fn device_heartbeat_key(device_id: &str) -> String {
    format!("heartbeat.{device_id}")
}

#[cfg(test)]
mod tests {
    use super::*;

    fn dn(s: &str) -> crate::DeploymentName {
        crate::DeploymentName::try_new(s).expect("valid")
    }

    #[test]
    fn desired_state_key_format() {
        assert_eq!(
            desired_state_key("pi-01", &dn("hello-web")),
            "pi-01.hello-web"
        );
    }

    #[test]
    fn bucket_names_stable() {
        // Flipping these is a cross-component break — operator,
        // agent, and smoke scripts all grep for the literal values.
        assert_eq!(BUCKET_DESIRED_STATE, "desired-state");
        assert_eq!(BUCKET_DEVICE_INFO, "device-info");
        assert_eq!(BUCKET_DEVICE_STATE, "device-state");
        assert_eq!(BUCKET_DEVICE_HEARTBEAT, "device-heartbeat");
    }

    #[test]
    fn key_formats() {
        assert_eq!(device_info_key("pi-01"), "info.pi-01");
        assert_eq!(
            device_state_key("pi-01", &dn("hello-web")),
            "state.pi-01.hello-web"
        );
        assert_eq!(device_heartbeat_key("pi-01"), "heartbeat.pi-01");
    }
}