types: let nix own the reserved-name blacklist
One list, in nix/reserved-names.nix, handed to everything that needs it as HIVE_RESERVED_NAMES. Keeping it current becomes a config change rather than a rebuild, and hive names and agent names -- one namespace going forward -- are checked against the same file: swarm-otel.nix's hand-written reservedOwners is gone. Whitespace-separated rather than JSON, deliberately, unlike the structured env vars beside it. Every entry is an Ident ([a-z0-9-]), so whitespace cannot occur inside a name and the encoding is provably lossless; JSON would mean either a parser dependency in a crate whose purpose is to have none, or a copy of the parse in every consumer. An UNSET variable is not "nothing is reserved". Both creation sites log an error and return a warning saying the check did not run, so a misconfigured deployment says so instead of silently accepting every name. A blank value folds into unset: nix always renders a non-empty list, so present-but-empty is a rendering fault, not a declaration. Two guards whose subject moved out of their own file now assert their own case is still in it, because a guard that can be retired by an edit elsewhere is not a guard: - swarm-otel.nix asserts reserved-names.nix still contains its swarmTierName. - hive-sh4re's sentinel drift test PANICS when the variable is missing rather than skipping -- a drift test that quietly does nothing still reports green. checks.nix and devshell.nix both export it so CI and a local cargo test agree. Verified as a pair: with the variable set, 8 tests pass; with it unset, exactly the 4 drift tests fail and the unrelated ones still pass.
This commit is contained in:
atlas
mara
parent
7bb68fe819
commit
27932ec631
10 changed files with 326 additions and 87 deletions
|
|
@ -6,14 +6,14 @@
|
|||
//! and get serde-validated parsing at the socket boundary for free — with
|
||||
//! no cross-crate coupling and without growing `hive-sh4re`.
|
||||
|
||||
/// Names that already mean something to the message layer, and so are not
|
||||
/// available as an agent name.
|
||||
/// The environment variable nix uses to hand this process the blacklist of
|
||||
/// names that already mean something to the message layer.
|
||||
///
|
||||
/// Every entry is a value some component *produces* as a message `from` or
|
||||
/// `to`, not a word that merely looked risky. An agent holding one of these
|
||||
/// is indistinguishable, at the broker, from the thing that normally sends
|
||||
/// it: a wake from `forge` and a wake from an agent named `forge` are the
|
||||
/// same row.
|
||||
/// **Nix owns the list**, not this crate: `nix/reserved-names.nix` is the one
|
||||
/// copy, and it reaches `hive-c0re`, `swarm-controller`, the swarm collector's
|
||||
/// own assertion and the test suite from that single file. Keeping the
|
||||
/// blacklist current is therefore a config change, not a rebuild of a binary
|
||||
/// — and there is no second list to drift.
|
||||
///
|
||||
/// Deliberately **not** enforced inside [`Ident::parse`]. Parsing runs on
|
||||
/// every read of an already-created name, so rejecting there would make
|
||||
|
|
@ -21,45 +21,47 @@
|
|||
/// refusal — which is a stronger action than the warning this list is
|
||||
/// currently used for. Creation sites call [`is_reserved_name`]; readers do
|
||||
/// not.
|
||||
pub const RESERVED_NAMES: &[&str] = &[
|
||||
// The human at the dashboard. Both a broker recipient (the T4LK box
|
||||
// sends `{from: "operator", to, body}`) and the fallback attribution
|
||||
// for an answered question.
|
||||
"operator",
|
||||
// Helper events (`approval_resolved`, `container_crash`, …) — the
|
||||
// sender an agent is told to treat as hyperhive itself rather than as
|
||||
// a peer. Named in `hive_sh4re::manager::SYSTEM_SENDER`.
|
||||
"system",
|
||||
// A due self-scheduled reminder arrives as its own sender, so that a
|
||||
// wake I asked for last week is distinguishable from a peer message.
|
||||
"reminder",
|
||||
// Forge notification wakes, delivered by the notify daemon.
|
||||
"forge",
|
||||
// A scheduled prompt firing, pushed as a trusted sender.
|
||||
"scheduled",
|
||||
// Three synthetic wakes the harness itself produces: an in-container
|
||||
// todo, the follow-up turn after a self-requested compaction, and the
|
||||
// single flush turn before a graceful stop.
|
||||
"todo",
|
||||
"compact",
|
||||
"graceful-stop",
|
||||
];
|
||||
///
|
||||
/// ⚠️ An **unset** variable means *this process was not told*, which is not
|
||||
/// the same as *nothing is reserved*. Callers must say so out loud rather
|
||||
/// than silently treating every name as available.
|
||||
pub const RESERVED_NAMES_ENV: &str = "HIVE_RESERVED_NAMES";
|
||||
|
||||
// Two sentinels are deliberately absent. `<parent>` and `<children>` are
|
||||
// routing recipients that `Ident::parse` already rejects on charset, so no
|
||||
// name can ever equal them — listing them would imply a guard that never
|
||||
// fires. And `ruth` (the manager) is a real agent, not a literal: a second
|
||||
// agent wanting that name is a name that is *taken*, which is the roster
|
||||
// check's job, not this list's. `hive-sh4re` pins both claims in a test.
|
||||
/// Split the value of [`RESERVED_NAMES_ENV`] into names.
|
||||
///
|
||||
/// Whitespace-separated, not JSON, and that is a deliberate departure from
|
||||
/// the structured env vars elsewhere in the tree. Every entry is an [`Ident`],
|
||||
/// whose charset is `[a-z0-9-]` — so whitespace cannot occur *inside* a name
|
||||
/// and the encoding is provably lossless. Paying for a JSON parser here would
|
||||
/// mean either a dependency in a crate whose entire purpose is to have none,
|
||||
/// or a separate copy of the parse in every consumer.
|
||||
#[must_use]
|
||||
pub fn parse_reserved_names(raw: &str) -> Vec<&str> {
|
||||
raw.split_whitespace().collect()
|
||||
}
|
||||
|
||||
/// Whether `name` is already a protocol literal — see [`RESERVED_NAMES`].
|
||||
/// The raw value of [`RESERVED_NAMES_ENV`], or `None` when this process was
|
||||
/// never told what the blacklist is.
|
||||
///
|
||||
/// A **blank** value folds into `None` on purpose. Nix always renders a
|
||||
/// non-empty list, so a variable that is present but empty is a rendering
|
||||
/// fault, not an operator declaring that nothing is reserved — and the two
|
||||
/// must not look the same to a caller whose next move is to warn about it.
|
||||
#[must_use]
|
||||
pub fn reserved_names_raw() -> Option<String> {
|
||||
std::env::var(RESERVED_NAMES_ENV)
|
||||
.ok()
|
||||
.filter(|raw| !raw.trim().is_empty())
|
||||
}
|
||||
|
||||
/// Whether `name` is one of the protocol literals in `reserved`.
|
||||
///
|
||||
/// Call at **creation** sites only. A caller that is reading or routing an
|
||||
/// existing name must not consult this: the name is already in use, and the
|
||||
/// question there is where it goes, not whether it should exist.
|
||||
#[must_use]
|
||||
pub fn is_reserved_name(name: &str) -> bool {
|
||||
RESERVED_NAMES.contains(&name)
|
||||
pub fn is_reserved_name(name: &str, reserved: &[&str]) -> bool {
|
||||
reserved.contains(&name)
|
||||
}
|
||||
|
||||
/// A validated hive identifier: 1-63 chars of `[a-z0-9-]`.
|
||||
|
|
@ -154,7 +156,7 @@ impl<'de> serde::Deserialize<'de> for Ident {
|
|||
|
||||
#[cfg(test)]
|
||||
mod ident_tests {
|
||||
use super::{Ident, RESERVED_NAMES, is_reserved_name};
|
||||
use super::{Ident, is_reserved_name, parse_reserved_names};
|
||||
|
||||
#[test]
|
||||
fn accepts_canonical_shapes() {
|
||||
|
|
@ -193,29 +195,48 @@ mod ident_tests {
|
|||
|
||||
#[test]
|
||||
fn reserved_names_are_flagged_and_ordinary_names_are_not() {
|
||||
// A sample, not the real list: the real one lives in nix now, and
|
||||
// what this crate still owns is the *predicate*. The content of the
|
||||
// blacklist is asserted where the env var is readable — see
|
||||
// `hive-sh4re`'s drift test.
|
||||
let reserved = ["operator", "system", "graceful-stop"];
|
||||
// Presence arm: every entry must actually be reported.
|
||||
for name in RESERVED_NAMES {
|
||||
assert!(is_reserved_name(name), "{name:?} should be reserved");
|
||||
for name in reserved {
|
||||
assert!(is_reserved_name(name, &reserved), "{name:?} not reported");
|
||||
}
|
||||
// Absence arm, and the reason this test can fail: without it a
|
||||
// predicate that always returns `true` passes the loop above.
|
||||
for ok in ["atlas", "damocles", "iris", "operator-2", "sys", "forged"] {
|
||||
assert!(!is_reserved_name(ok), "{ok:?} must NOT be reserved");
|
||||
assert!(!is_reserved_name(ok, &reserved), "{ok:?} must NOT be");
|
||||
}
|
||||
// An empty list reserves nothing — the shape a caller gets when the
|
||||
// env var is unset, and the reason a caller must not treat that
|
||||
// case as "nothing is reserved" without saying so.
|
||||
assert!(!is_reserved_name("operator", &[]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn every_reserved_name_is_a_valid_ident() {
|
||||
// A reserved name that `Ident::parse` already rejects is dead
|
||||
// weight — nothing could ever have been created with it, so
|
||||
// listing it implies a guard that is doing nothing. `graceful-stop`
|
||||
// is the one that makes this worth asserting: it is hyphenated, and
|
||||
// a charset tightening would silently retire it.
|
||||
for name in RESERVED_NAMES {
|
||||
assert!(
|
||||
Ident::parse(name).is_ok(),
|
||||
"{name:?} is reserved but not a parseable ident — one of the two is wrong"
|
||||
);
|
||||
fn parses_the_env_encoding() {
|
||||
assert_eq!(
|
||||
parse_reserved_names("operator system graceful-stop"),
|
||||
["operator", "system", "graceful-stop"]
|
||||
);
|
||||
// Newlines and runs of spaces are what a nix-rendered list looks
|
||||
// like when someone reformats the file; both must fold away.
|
||||
assert_eq!(
|
||||
parse_reserved_names(" operator\n system \n"),
|
||||
["operator", "system"]
|
||||
);
|
||||
// Absence and emptiness collapse to the same empty list, which is
|
||||
// why the CALLER, not this function, has to distinguish them.
|
||||
assert!(parse_reserved_names("").is_empty());
|
||||
// Every name the encoding can carry must survive a round trip
|
||||
// through `Ident::parse`: a blacklist entry that is not a legal
|
||||
// ident is dead weight, since nothing could ever be created with
|
||||
// it. `graceful-stop` is the one that makes this worth asserting —
|
||||
// it is hyphenated, and a charset tightening would retire it.
|
||||
for name in parse_reserved_names("operator system todo graceful-stop") {
|
||||
assert!(Ident::parse(name).is_ok(), "{name:?} is not an ident");
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue