//! Per-agent power *intent* (`wanted: Up | Offline`) this hive holds in //! memory — what the operator last asked of an agent through `hivectl` or a //! queued power op, until hive-c0re restarts. `container_view` remains the //! observed *status*; the job queue's `Reconcile` nodes are the mechanism that //! converges the two. //! //! Nothing here is durable, on purpose: the swarm owns lasting power intent. //! It declares each agent's state in the hive's wanted bucket (see //! `crate::workers::wanted`), and that declaration outranks whatever this map //! holds. After a restart the map is empty, an agent with no entry is seeded //! from what its container is doing (so nothing starts or stops by itself), //! and the declaration brings the declared agents to their state. //! //! Setting `wanted` is never a queued node's job to *read back*: operator //! actions update the map synchronously at request time, then submit the DAG //! whose terminal `Reconcile` reads the fresh value — rapid toggles are //! last-writer-wins and the reconciles converge. use std::collections::HashMap; use std::sync::Mutex; /// Per-agent power intent. #[derive(Debug, Clone, Copy, PartialEq, Eq, strum::IntoStaticStr, strum::EnumString)] #[strum(serialize_all = "snake_case")] pub enum Wanted { Up, Offline, } impl Wanted { /// Seed value from an observed running state (an agent no operator or /// declaration has said anything about since this process started). pub fn from_running(running: bool) -> Self { if running { Wanted::Up } else { Wanted::Offline } } } /// What a `Reconcile` should do given intent + observation. Pure so /// the `{Up,Offline} × {up,down}` matrix is unit-testable. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ReconcileAction { Start, Stop, Noop, } #[must_use] pub fn reconcile_action(wanted: Wanted, running: bool) -> ReconcileAction { match (wanted, running) { (Wanted::Up, false) => ReconcileAction::Start, (Wanted::Offline, true) => ReconcileAction::Stop, (Wanted::Up, true) | (Wanted::Offline, false) => ReconcileAction::Noop, } } /// The in-memory intent map. `Arc`-friendly: all methods take `&self`, the /// internal `Mutex` serializes access. #[derive(Default)] pub struct PowerStore { intents: Mutex>, } impl PowerStore { /// Read an agent's intent. `None` when nothing has set or seeded one since /// this process started (callers seed from observed state via /// [`Self::get_or_seed`]). pub fn get(&self, agent: &str) -> Option { self.intents .lock() .expect("power intents mutex poisoned") .get(agent) .copied() } /// Write an agent's intent (last-writer-wins, synchronous at /// request time). pub fn set(&self, agent: &str, wanted: Wanted) { self.intents .lock() .expect("power intents mutex poisoned") .insert(agent.to_owned(), wanted); } /// Read an agent's intent, seeding it from the observed running state when /// absent (running ⇒ `Up`, stopped ⇒ `Offline`), after which the map is /// authoritative until the process restarts. pub fn get_or_seed(&self, agent: &str, running: bool) -> Wanted { *self .intents .lock() .expect("power intents mutex poisoned") .entry(agent.to_owned()) .or_insert_with(|| { let seeded = Wanted::from_running(running); tracing::info!(%agent, wanted = <&str>::from(seeded), "power intent: seeded from observed state"); seeded }) } /// Drop an agent's intent (container destroyed). pub fn remove(&self, agent: &str) { self.intents .lock() .expect("power intents mutex poisoned") .remove(agent); } } #[cfg(test)] mod tests { use super::*; /// The full `{Up,Offline} × {up,down}` reconcile matrix: /// start / stop / noop / noop. #[test] fn reconcile_matrix() { assert_eq!(reconcile_action(Wanted::Up, false), ReconcileAction::Start); assert_eq!( reconcile_action(Wanted::Offline, true), ReconcileAction::Stop ); assert_eq!(reconcile_action(Wanted::Up, true), ReconcileAction::Noop); assert_eq!( reconcile_action(Wanted::Offline, false), ReconcileAction::Noop ); } #[test] fn get_set_roundtrip_and_seed() { let store = PowerStore::default(); assert_eq!(store.get("alice"), None); // Seed from observed running state, once. assert_eq!(store.get_or_seed("alice", true), Wanted::Up); // Thereafter the map is authoritative — observed state no longer // overrides. assert_eq!(store.get_or_seed("alice", false), Wanted::Up); store.set("alice", Wanted::Offline); assert_eq!(store.get("alice"), Some(Wanted::Offline)); store.remove("alice"); assert_eq!(store.get("alice"), None); } }