143 lines
5 KiB
Rust
143 lines
5 KiB
Rust
//! 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<HashMap<String, Wanted>>,
|
||
}
|
||
|
||
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<Wanted> {
|
||
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);
|
||
}
|
||
}
|