679 lines
28 KiB
Rust
679 lines
28 KiB
Rust
//! Host admin socket wire types (`/run/hyperhive/host.sock`).
|
|
//!
|
|
//! The host-control protocol spoken between `hivectl` and the `hive-c0re`
|
|
//! daemon. Re-homed out of `hive-sh4re` so a standalone `hivectl` can depend
|
|
//! on just this protocol crate instead of the whole daemon crate. The shared
|
|
//! payload types it references (`Approval`, `AgentStatusRow`, `jobs::DagView`)
|
|
//! stay in `hive-sh4re`.
|
|
|
|
use std::path::PathBuf;
|
|
|
|
use hive_sh4re::{AgentStatusRow, Approval, jobs};
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
// ── Shared hive layout facts ──────────────────────────────────────────────
|
|
// Paths + names both the `hive-c0re` daemon and the host-side `hivectl` CLI
|
|
// must agree on. Homed here (the protocol crate both sides already depend on)
|
|
// so a standalone `hivectl` can reach them without linking the whole daemon
|
|
// crate. `hive-c0re`'s `paths` / `lifecycle` modules re-export these, staying
|
|
// the daemon's single-source facade for its own callsites.
|
|
|
|
/// Default host admin socket (`/run/hyperhive/host.sock`). Used as the
|
|
/// `--socket` / `--host-socket` clap `default_value` in the daemon and
|
|
/// `hivectl`.
|
|
pub const HOST_SOCKET: &str = "/run/hyperhive/host.sock";
|
|
|
|
/// `agents/` — per-agent persistent state root (one subdir per agent,
|
|
/// bind-mounted into each container as `/agents/<name>`).
|
|
// nix: agent container bind-mount source (harness modules / agent.nix template) — must match.
|
|
// priv-sock: `hive_priv_sock::AGENT_STATE_ROOT` is the same value and must stay in sync;
|
|
// the privsep boundary prevents importing across the crate.
|
|
pub const AGENTS_ROOT: &str = "/var/lib/hyperhive/agents";
|
|
|
|
/// `agents/<name>` — one agent's persistent state root.
|
|
///
|
|
/// Takes a validated [`Ident`] (not a raw `&str`) so a per-agent state path
|
|
/// can never be built from an unvalidated name — the `../` traversal guard is
|
|
/// the type, enforced at the one place every agent path is rooted.
|
|
#[must_use]
|
|
pub fn agent_state_dir(name: &Ident) -> PathBuf {
|
|
PathBuf::from(AGENTS_ROOT).join(name.as_str())
|
|
}
|
|
|
|
/// `gateway/gateway.htpasswd` — nginx basic-auth credential store for the
|
|
/// operator dashboard vhost. `hivectl`'s `--htpasswd-file` clap default.
|
|
// nix: read by the gateway container's nginx (hive-gateway.nix) — must match.
|
|
pub const GATEWAY_HTPASSWD: &str = "/var/lib/hyperhive/gateway/gateway.htpasswd";
|
|
|
|
/// nspawn machine-name prefix for agent containers (`h-<name>`). A single
|
|
/// `starts_with(AGENT_PREFIX)` filter enumerates managed containers.
|
|
pub const AGENT_PREFIX: &str = "h-";
|
|
|
|
/// Map an agent's logical name to its nspawn machine name (`h-<name>`).
|
|
#[must_use]
|
|
pub fn container_name(name: &str) -> String {
|
|
format!("{AGENT_PREFIX}{name}")
|
|
}
|
|
|
|
/// A validated hive identifier: 1-63 chars of `[a-z0-9-]`.
|
|
///
|
|
/// The single ident type for agent names, forge labels, and matrix / github
|
|
/// account names — every value that becomes a filesystem path segment or an
|
|
/// nspawn machine-name component. Constructed only through the validating
|
|
/// [`Ident::parse`], so "this string passed the naming whitelist" is a fact
|
|
/// the type carries instead of a convention every call site re-checks against
|
|
/// a raw `String`. The charset is deliberately conservative — lowercase
|
|
/// ascii, digits, and hyphen only (no underscore, dot, slash, or non-ASCII) —
|
|
/// and length-capped, tracking `nixos-container` basename rules and keeping
|
|
/// `../` traversal, unicode homoglyphs, and unbounded path segments out of
|
|
/// any path built from it. Deserialization runs the same parse, so a value
|
|
/// arriving over the wire is validated on the way in.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
|
|
pub struct Ident(String);
|
|
|
|
impl Ident {
|
|
/// Maximum length in bytes. A cap stops an unbounded operator-supplied
|
|
/// name from becoming an over-long path segment (a filesystem / `DoS`
|
|
/// footgun).
|
|
pub const MAX_LEN: usize = 63;
|
|
|
|
/// Parse + validate an identifier.
|
|
///
|
|
/// # Errors
|
|
/// Returns `Err(reason)` — a caller-ready message — when `s` is empty,
|
|
/// longer than [`Ident::MAX_LEN`], or contains any byte outside
|
|
/// `[a-z0-9-]`.
|
|
pub fn parse(s: &str) -> Result<Self, &'static str> {
|
|
if s.is_empty() {
|
|
return Err("identifier must not be empty");
|
|
}
|
|
if s.len() > Self::MAX_LEN {
|
|
return Err("identifier must be 63 characters or fewer");
|
|
}
|
|
if !s
|
|
.bytes()
|
|
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
|
|
{
|
|
return Err("identifier must contain only [a-z0-9-]");
|
|
}
|
|
Ok(Self(s.to_owned()))
|
|
}
|
|
|
|
/// The validated identifier as a string slice.
|
|
#[must_use]
|
|
pub fn as_str(&self) -> &str {
|
|
&self.0
|
|
}
|
|
|
|
/// Consume into the inner `String`.
|
|
#[must_use]
|
|
pub fn into_string(self) -> String {
|
|
self.0
|
|
}
|
|
}
|
|
|
|
impl std::fmt::Display for Ident {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
f.write_str(&self.0)
|
|
}
|
|
}
|
|
|
|
impl AsRef<str> for Ident {
|
|
fn as_ref(&self) -> &str {
|
|
&self.0
|
|
}
|
|
}
|
|
|
|
/// Lets an `Ident` key a `HashMap`/`BTreeMap` be looked up with a `&str`.
|
|
impl std::borrow::Borrow<str> for Ident {
|
|
fn borrow(&self) -> &str {
|
|
&self.0
|
|
}
|
|
}
|
|
|
|
impl serde::Serialize for Ident {
|
|
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
|
|
serializer.serialize_str(&self.0)
|
|
}
|
|
}
|
|
|
|
impl<'de> serde::Deserialize<'de> for Ident {
|
|
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
|
|
use serde::de::Error as _;
|
|
let s = String::deserialize(deserializer)?;
|
|
Ident::parse(&s).map_err(D::Error::custom)
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod ident_tests {
|
|
use super::Ident;
|
|
|
|
#[test]
|
|
fn accepts_canonical_shapes() {
|
|
for ok in [
|
|
"damocles",
|
|
"hm1nd",
|
|
"agent-with-dashes",
|
|
"codeberg",
|
|
"acct-1",
|
|
] {
|
|
assert!(Ident::parse(ok).is_ok(), "should accept {ok:?}");
|
|
}
|
|
assert!(
|
|
Ident::parse(&"a".repeat(Ident::MAX_LEN)).is_ok(),
|
|
"63 chars is the boundary"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn rejects_bad_input() {
|
|
let too_long = "a".repeat(Ident::MAX_LEN + 1);
|
|
for bad in [
|
|
"",
|
|
&too_long,
|
|
"Alice", // uppercase
|
|
"snake_case", // underscore (tightened out)
|
|
"alice.bob", // dot
|
|
"alice/bob", // slash
|
|
"../etc/passwd", // traversal
|
|
"damóclès", // non-ASCII
|
|
"alice\u{2013}b", // en-dash homoglyph
|
|
] {
|
|
assert!(Ident::parse(bad).is_err(), "should reject {bad:?}");
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn round_trips_and_serde_validates() {
|
|
let id = Ident::parse("damocles").unwrap();
|
|
assert_eq!(id.as_str(), "damocles");
|
|
// Serialize is transparent (just the inner string).
|
|
let json = serde_json::to_string(&id).unwrap();
|
|
assert_eq!(json, "\"damocles\"");
|
|
// Deserialize runs the same parse.
|
|
let back: Ident = serde_json::from_str(&json).unwrap();
|
|
assert_eq!(back, id);
|
|
assert!(
|
|
serde_json::from_str::<Ident>("\"BAD_NAME\"").is_err(),
|
|
"deserialize must reject an invalid ident"
|
|
);
|
|
}
|
|
}
|
|
|
|
/// Which way to reconcile an agent's config branches
|
|
/// ([`HostRequest::ReconcileConfigApply`]).
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "snake_case")]
|
|
pub enum ReconcileDirection {
|
|
/// Reset the local applied checkout to forge `main`.
|
|
Forge,
|
|
/// Advance forge `main` from local — not supported yet.
|
|
Local,
|
|
}
|
|
|
|
/// Requests on the host admin socket.
|
|
///
|
|
/// Wire format: one JSON object per line.
|
|
#[derive(Debug, Clone, Serialize, Deserialize)]
|
|
#[serde(tag = "cmd", rename_all = "snake_case")]
|
|
pub enum HostRequest {
|
|
/// Create and start a sub-agent container directly, bypassing the
|
|
/// approval queue. Privileged-context only. See
|
|
/// `docs/approvals.md::Approval kinds (wire shapes)`.
|
|
Spawn { name: String },
|
|
/// Submit a spawn request for the operator to approve. See
|
|
/// `docs/approvals.md::Approval kinds (wire shapes)` (`Spawn`).
|
|
RequestSpawn { name: String },
|
|
/// Stop a managed container (graceful).
|
|
Kill { name: String },
|
|
/// Tear down a sub-agent container, optionally purging state.
|
|
/// See `docs/approvals.md::Destroy semantics`.
|
|
Destroy {
|
|
name: String,
|
|
#[serde(default)]
|
|
purge: bool,
|
|
},
|
|
/// Stop and start a managed container without rebuilding config.
|
|
/// For "kick the container" operations that don't touch the flake or
|
|
/// nspawn flags. Mirrors `lifecycle::restart` (kill + start).
|
|
Restart { name: String },
|
|
/// Stop and restart all managed containers in sequence. Convenience
|
|
/// wrapper for `hivectl agents restart-all`; iterates the live
|
|
/// container list and restarts each one.
|
|
RestartAll,
|
|
/// Restart containers hive-wide (`hivectl restart`), scoped like
|
|
/// `Stop`/`Start`. Each targeted agent rides exactly one DAG
|
|
/// server-side — the `Restart` template (mechanical stop + reconcile),
|
|
/// or, when `graceful` is set, the `GracefulRestart` template (signal →
|
|
/// drain → mechanical stop → reconcile) — rather than the old
|
|
/// client-side stop-then-start composition (and, briefly, a server-side
|
|
/// "submit stop DAG, await it, submit start DAG" composition): a
|
|
/// dropped `hivectl` connection mid-way, or a crash between the two
|
|
/// submits, used to leave the agent stopped with no automatic
|
|
/// follow-up, since nothing durable remembered "finish the restart"
|
|
/// once the calling process/turn was gone. `GracefulRestart` closes
|
|
/// that gap the same way `Restart` already does — one DAG, queued up
|
|
/// front, that owns the whole sequence. Infra containers have no
|
|
/// lease/DAG and restart synchronously (stop then start), same as
|
|
/// before. Scope semantics match `Stop`/`Start` (all-false =
|
|
/// everything).
|
|
RestartScoped {
|
|
#[serde(default)]
|
|
scope: LifecycleScope,
|
|
#[serde(default)]
|
|
graceful: bool,
|
|
},
|
|
/// Apply pending config to a managed container.
|
|
Rebuild { name: String },
|
|
/// List managed containers.
|
|
List,
|
|
/// List managed agents with their full status + technical state
|
|
/// (running / needs-login / needs-update / deployed sha / parent /
|
|
/// pending reminders) — the `hivectl agents list` roster view.
|
|
/// Reuses the dashboard's per-agent `ContainerView` aggregation.
|
|
AgentStatus,
|
|
/// Report this hive's canonical DNS domain
|
|
/// (`services.hyperhive.domain`) plus the browser-facing home /
|
|
/// forge / matrix URLs, daemon-sourced so custom forge/matrix
|
|
/// domains resolve correctly. Each URL is `None` when its subsystem
|
|
/// is unreachable from a browser (e.g. forge not behind the gateway,
|
|
/// matrix GUI disabled). Backs `hivectl open` + the federation
|
|
/// peer-config block (which reads the bare `domain`).
|
|
Urls,
|
|
/// Fetch one job-queue DAG by id — the polling surface behind
|
|
/// `hivectl`'s wait/progress loop. A multi-step op is a single DAG
|
|
/// (its whole graph in `nodes`). Result: [`HostResponse::dags`].
|
|
QueueDag { id: u64 },
|
|
/// List pending approval requests.
|
|
Pending,
|
|
/// Approve a pending request by id; the action runs immediately.
|
|
Approve { id: i64 },
|
|
/// Deny a pending request by id.
|
|
Deny { id: i64 },
|
|
/// Move an agent in the topology tree. `new_parent = None`
|
|
/// promotes the agent to root, `Some(name)` sets a new parent.
|
|
/// Validation rules + bind-mount caveat documented in
|
|
/// `docs/agent-hierarchy.md::Current state`.
|
|
SetParent {
|
|
child: String,
|
|
new_parent: Option<String>,
|
|
},
|
|
/// Stop managed containers hive-wide in one operator action
|
|
/// (`hivectl stop`): agents plus the selected infra containers. `scope`
|
|
/// selects which classes; an all-false scope means **everything** (the
|
|
/// bare `hivectl stop`). `graceful` runs the per-agent quiesce (graceful
|
|
/// agent stop, issue tracker `graceful agent stop`) instead of a hard
|
|
/// stop. Agents stop via the lifecycle path; infra containers via the
|
|
/// host `container@<name>` units.
|
|
Stop {
|
|
#[serde(default)]
|
|
scope: LifecycleScope,
|
|
#[serde(default)]
|
|
graceful: bool,
|
|
},
|
|
/// Start managed containers hive-wide — the inverse of `Stop`
|
|
/// (`hivectl start`). Same `scope` semantics (all-false = everything);
|
|
/// no graceful flag (start is unconditional).
|
|
Start {
|
|
#[serde(default)]
|
|
scope: LifecycleScope,
|
|
},
|
|
/// Create or refresh a matrix account + access token for `name`.
|
|
/// The daemon runs the provisioning (it holds the register + admin
|
|
/// tokens and the matrix creds dir) and returns the operator-facing
|
|
/// results (persisted-token path for agents, or the freshly-minted
|
|
/// token + password for non-agent accounts) in
|
|
/// [`HostResponse::messages`]. `password` is resolved by the client
|
|
/// (inline flag or stdin) and `None` requests a random throwaway.
|
|
MatrixCreateUser {
|
|
name: String,
|
|
#[serde(default)]
|
|
password: Option<String>,
|
|
},
|
|
/// Provision (or re-provision) the hive system admin matrix account.
|
|
/// Daemon-side equivalent of `hivectl matrix sync-admin`.
|
|
MatrixSyncAdmin,
|
|
/// Promote a matrix user to homeserver admin via the admin API.
|
|
/// Uses the daemon's system admin token; `server_name` is discovered
|
|
/// from the running homeserver.
|
|
MatrixPromoteUser { name: String },
|
|
/// Reset a matrix user's password via the admin API and persist the
|
|
/// new password to the matrix creds dir so a later token mint can
|
|
/// re-login. Returns the outcome in [`HostResponse::messages`].
|
|
MatrixResetPassword { name: String },
|
|
/// Invite a matrix user to the hive Space (default) or a specific
|
|
/// `room`. Uses the daemon's admin token; idempotent
|
|
/// (already-member / already-invited is a no-op).
|
|
MatrixInvite {
|
|
user: String,
|
|
#[serde(default)]
|
|
room: Option<String>,
|
|
},
|
|
/// Create or refresh a forge account + API token for `name`. Daemon-side
|
|
/// equivalent of `hivectl forge create-user`: for an existing agent it
|
|
/// provisions the account and persists the token to `<notes>/forge-token`;
|
|
/// for a non-agent (operator/human) it mints a user and returns the token
|
|
/// in [`HostResponse::messages`]. `password` is resolved client-side
|
|
/// (inline flag or stdin) and only meaningful for non-agent accounts.
|
|
ForgeCreateUser {
|
|
name: String,
|
|
#[serde(default)]
|
|
password: Option<String>,
|
|
},
|
|
/// Report the divergence between agent `agent`'s local applied config
|
|
/// checkout and its forge `agent-configs/<agent>` `main`. The daemon
|
|
/// fetches forge `main` read-only and returns a human-readable report
|
|
/// (ahead/behind counts, commit-range summary, `git diff --stat`, and
|
|
/// the full diff when `verbose`) in [`HostResponse::messages`]. Read-only
|
|
/// — never mutates either side. Backs `hivectl forge reconcile-config`
|
|
/// (the diff it always shows first).
|
|
ReconcileConfigStatus {
|
|
agent: String,
|
|
#[serde(default)]
|
|
verbose: bool,
|
|
},
|
|
/// Reconcile agent `agent`'s config branches in `direction`.
|
|
/// `Forge` resets the local applied checkout to forge `main` (takes
|
|
/// effect on the next deploy); `Local` is not supported yet and returns
|
|
/// an [`HostResponse::error`] (advancing the protected forge `main` from
|
|
/// local needs lifting branch protection — resolve via a config PR).
|
|
/// Backs `hivectl forge reconcile-config --from <forge|local>`.
|
|
ReconcileConfigApply {
|
|
agent: String,
|
|
direction: ReconcileDirection,
|
|
},
|
|
/// Add or update a gateway HTTP-Basic user in the daemon's htpasswd file
|
|
/// (`paths::GATEWAY_HTPASSWD`). Daemon-side equivalent of `hivectl gateway
|
|
/// create-user`: the daemon bcrypt-hashes `password` (cost 12, remapped to
|
|
/// the `$2y$` prefix nginx accepts) and writes the entry, so hivectl never
|
|
/// touches the file. `password` is read client-side (inline flag or stdin).
|
|
/// Returns a confirmation line in [`HostResponse::messages`].
|
|
GatewayCreateUser { username: String, password: String },
|
|
/// Remove a gateway HTTP-Basic user from the daemon's htpasswd file.
|
|
/// Daemon-side equivalent of `hivectl gateway delete-user`. Errors if the
|
|
/// user isn't present so a no-op is detectable.
|
|
GatewayDeleteUser { username: String },
|
|
/// List the gateway HTTP-Basic usernames in the daemon's htpasswd file.
|
|
/// Daemon-side equivalent of `hivectl gateway list-users`; the usernames
|
|
/// come back in [`HostResponse::messages`], one per line.
|
|
GatewayListUsers,
|
|
/// Write (or overwrite) an agent's GitHub PAT under its state dir, via
|
|
/// the privileged helper. Daemon-side equivalent of `hivectl github
|
|
/// set-token`. `token` is resolved + non-empty-validated client-side
|
|
/// (inline flag or stdin); the daemon just persists it. Read live by
|
|
/// the agent's `gh` wrapper / git credential helper — no rebuild needed.
|
|
SetAgentGithubToken { agent: String, token: String },
|
|
/// Turn on btrfs qgroup accounting on the agent-state filesystem, via
|
|
/// the privileged helper. Daemon-side equivalent of `hivectl quota
|
|
/// enable`. Returns advisory lines in [`HostResponse::messages`].
|
|
QuotaEnable,
|
|
/// Set (or, with `limit = None`, clear) an agent's btrfs disk quota via
|
|
/// the privileged helper. Daemon-side equivalent of `hivectl quota
|
|
/// limit`; the size string is parsed to bytes client-side. Returns a
|
|
/// bare success — the client prints the confirmation from the value it
|
|
/// sent.
|
|
QuotaLimit {
|
|
name: String,
|
|
#[serde(default)]
|
|
limit: Option<u64>,
|
|
},
|
|
/// Report per-agent btrfs qgroup usage (`hivectl quota show [name]`).
|
|
/// The daemon resolves the agent set (all kept state dirs when `name`
|
|
/// is absent) and reads each subvolume's referenced/exclusive usage via
|
|
/// the privileged helper. Result rows land in [`HostResponse::quota`];
|
|
/// a "btrfs quota not enabled" error short-circuits the whole sweep as a
|
|
/// plain [`HostResponse::error`] so the client can print the enable hint.
|
|
QuotaShow {
|
|
#[serde(default)]
|
|
name: Option<String>,
|
|
},
|
|
/// Migrate an agent's plain state dir to a btrfs subvolume via the
|
|
/// privileged helper (`hivectl subvol upgrade`). The agent MUST already
|
|
/// be stopped — the client orchestrates stop → this → start. Returns a
|
|
/// bare success; the client prints its own progress lines.
|
|
UpgradeSubvolume { name: String },
|
|
/// Create a read-only btrfs snapshot of an agent's state subvolume
|
|
/// (`hivectl subvol snapshot create`). `label` is validated client-side
|
|
/// AND by hive-priv. Returns the snapshot's host path in
|
|
/// [`HostResponse::messages`].
|
|
SnapshotSubvolume { name: String, label: String },
|
|
/// Delete a snapshot created by `SnapshotSubvolume` (`hivectl subvol
|
|
/// snapshot delete`). Bare success; the client prints the confirmation.
|
|
DeleteSnapshot { name: String, label: String },
|
|
/// Export a snapshot to a local file via `btrfs send` (`hivectl subvol
|
|
/// snapshot send`). `dest` is a bare filename (hive-priv rejects paths);
|
|
/// `parent` names an optional parent snapshot for an incremental send.
|
|
/// Returns the written file's host path in [`HostResponse::messages`].
|
|
SendSnapshot {
|
|
name: String,
|
|
label: String,
|
|
#[serde(default)]
|
|
parent: Option<String>,
|
|
dest: String,
|
|
},
|
|
}
|
|
|
|
/// One agent's btrfs qgroup usage row — the [`HostRequest::QuotaShow`]
|
|
/// result unit. `referenced` / `exclusive` are byte counts when the agent
|
|
/// has a live qgroup; both are `None` (with an explanatory `note`) for a
|
|
/// plain-dir agent that has no subvolume to account. The client formats the
|
|
/// byte counts into human-readable columns.
|
|
#[derive(Debug, Clone, Serialize, Deserialize)]
|
|
pub struct QuotaRow {
|
|
pub agent: String,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub referenced: Option<u64>,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub exclusive: Option<u64>,
|
|
/// Set instead of the byte counts when the agent has no qgroup data
|
|
/// (plain dir, or a non-"quota not enabled" read error), so the client
|
|
/// can print an inline explanation and keep going.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub note: Option<String>,
|
|
}
|
|
|
|
/// Selects which container classes a hive-wide [`HostRequest::Stop`] /
|
|
/// [`HostRequest::Start`] touches. An all-false scope means **everything**
|
|
/// (the bare `hivectl stop` / `start`); set individual fields to restrict
|
|
/// (e.g. only `agents` → just the sub-agent containers). `agents` covers
|
|
/// every managed sub-agent container; the rest are the named infra
|
|
/// containers (`hive-ci`, `hive-forge`, `hive-gateway`, `hive-matrix`).
|
|
//
|
|
// A flat bag of independent flag toggles — one bool per selectable
|
|
// container class — is exactly the right shape here: each maps 1:1 to a
|
|
// `hivectl` `--ci` / `--forge` / `--gateway` / `--matrix` flag, and they're
|
|
// orthogonal (any subset is valid), so a state machine or two-variant enums
|
|
// would only obscure the mapping. Hence the `struct_excessive_bools` allow.
|
|
#[allow(clippy::struct_excessive_bools)]
|
|
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
|
|
pub struct LifecycleScope {
|
|
/// All sub-agent containers (`--agents`).
|
|
#[serde(default)]
|
|
pub agents: bool,
|
|
/// Specific sub-agents by logical name (`--agent <name>`, repeatable).
|
|
/// Additive with the rest of the scope; redundant when `agents` is set
|
|
/// (which already covers every sub-agent).
|
|
#[serde(default)]
|
|
pub agent_names: Vec<String>,
|
|
#[serde(default)]
|
|
pub ci: bool,
|
|
#[serde(default)]
|
|
pub forge: bool,
|
|
#[serde(default)]
|
|
pub gateway: bool,
|
|
#[serde(default)]
|
|
pub matrix: bool,
|
|
}
|
|
|
|
impl LifecycleScope {
|
|
/// True when nothing is explicitly selected — interpreted as "all
|
|
/// classes" (the bare `hivectl stop` / `start` with no scope flags).
|
|
pub fn is_everything(&self) -> bool {
|
|
!(self.agents || self.ci || self.forge || self.gateway || self.matrix)
|
|
&& self.agent_names.is_empty()
|
|
}
|
|
}
|
|
|
|
/// This hive's canonical domain plus the browser-facing URLs for its
|
|
/// web surfaces — the `Urls` request result. Every field is `None` when
|
|
/// the corresponding surface can't be reached from a browser (domain
|
|
/// unset, forge not behind the gateway, matrix GUI disabled), so the CLI
|
|
/// can give a precise hint instead of opening a dead link.
|
|
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
|
|
pub struct HiveUrls {
|
|
/// Canonical hive domain (`services.hyperhive.domain`).
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub domain: Option<String>,
|
|
/// Operator dashboard root (`https://<domain>/`).
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub home: Option<String>,
|
|
/// Forge browser URL (`HIVE_FORGE_PUBLIC_URL`) — only the
|
|
/// behind-gateway public URL; `None` on direct-port forge deploys.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub forge: Option<String>,
|
|
/// Matrix GUI (fluffychat) browser URL — `None` when the matrix GUI
|
|
/// is disabled.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub matrix: Option<String>,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
|
|
pub struct HostResponse {
|
|
pub ok: bool,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub error: Option<String>,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub agents: Option<Vec<String>>,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub approvals: Option<Vec<Approval>>,
|
|
/// `Urls` result — this hive's domain plus the browser-facing
|
|
/// home / forge / matrix URLs. `None` for every other request kind.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub urls: Option<HiveUrls>,
|
|
/// `AgentStatus` result — one row per managed agent with its
|
|
/// running/health flags + technical state. `None` for every other
|
|
/// request kind.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub agent_statuses: Option<Vec<AgentStatusRow>>,
|
|
/// Ids of the job-queue DAGs this request submitted (rebuild /
|
|
/// restart / power ops). Clients poll them via
|
|
/// [`HostRequest::QueueDag`]; `None` for non-submitting requests.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub queued_dags: Option<Vec<u64>>,
|
|
/// `QueueDag` result — the requested DAG followed by its live
|
|
/// fan-out children ([`jobs::DagView`]). Empty when the DAG has
|
|
/// been evicted from the queue's history tail.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub dags: Option<Vec<jobs::DagView>>,
|
|
/// Free-form operator-facing output lines the client prints verbatim
|
|
/// (one per line). Carries results a request produced daemon-side that
|
|
/// have no structured home — e.g. a freshly-minted matrix token, a
|
|
/// reset password, or an invited room id from the `Matrix*` requests.
|
|
/// Empty for requests that produce no such output.
|
|
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
|
pub messages: Vec<String>,
|
|
/// `QuotaShow` result — one row per agent with its btrfs qgroup usage.
|
|
/// `None` for every other request kind.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub quota: Option<Vec<QuotaRow>>,
|
|
}
|
|
|
|
impl HostResponse {
|
|
#[must_use]
|
|
pub fn success() -> Self {
|
|
Self {
|
|
ok: true,
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
#[must_use]
|
|
pub fn error(message: impl Into<String>) -> Self {
|
|
Self {
|
|
ok: false,
|
|
error: Some(message.into()),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
#[must_use]
|
|
pub fn list(agents: Vec<String>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
agents: Some(agents),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
#[must_use]
|
|
pub fn pending(approvals: Vec<Approval>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
approvals: Some(approvals),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// `Urls` result — this hive's domain + browser-facing web URLs.
|
|
#[must_use]
|
|
pub fn urls(urls: HiveUrls) -> Self {
|
|
Self {
|
|
ok: true,
|
|
urls: Some(urls),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// `AgentStatus` result — one row per managed agent.
|
|
#[must_use]
|
|
pub fn agent_statuses(rows: Vec<AgentStatusRow>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
agent_statuses: Some(rows),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// A request that submitted job-queue DAGs — carries their ids for
|
|
/// the client's wait/progress loop.
|
|
#[must_use]
|
|
pub fn queued(ids: Vec<u64>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
queued_dags: Some(ids),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// `QueueDag` result — the polled DAG + its live children.
|
|
#[must_use]
|
|
pub fn dags(dags: Vec<jobs::DagView>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
dags: Some(dags),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// A success carrying operator-facing output lines the client prints
|
|
/// verbatim — the result shape for the `Matrix*` provisioning requests.
|
|
#[must_use]
|
|
pub fn messages(messages: Vec<String>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
messages,
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// `QuotaShow` result — one usage row per agent.
|
|
#[must_use]
|
|
pub fn quota(rows: Vec<QuotaRow>) -> Self {
|
|
Self {
|
|
ok: true,
|
|
quota: Some(rows),
|
|
..Self::default()
|
|
}
|
|
}
|
|
}
|