vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refactor(#3255): a constant, not a module with an essay

Browse source 
Review call: 46 lines of documentation around a single constant, part of
it already stale. The worst paragraph explained why the earlier per-hive
shape had been justified wrongly — history of a design that never
shipped, written into the file within an hour of that design being
dropped. A file is not a changelog; why it was wrong belongs in the PR.

The constant moves to lib.rs beside the status bucket name, keeping only
the rationale that stays true: three crates must agree on the string, and
the one that agrees hardest speaks neither jetstream nor kv, which is why
it cannot sit behind a feature gate.

status earns a module of its own because it holds a bucket name AND the
functions that open it. This held a constant.
This commit is contained in:
atlas 2026-08-19 20:09:08 +02:00 • committed by mara
commit 33958d78ae
5 changed files with 12 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

46
swarm-queue-client/src/knowledge.rs
View file

@ -1,46 +0,0 @@
//! The subject carrying *the knowledge repository changed*.
//!
//! One writer, many readers: the swarm controller publishes, every hive
//! subscribes. The controller does not need to know who the hives are to tell
//! them the repository moved — core NATS fans one publish out to whoever is
//! listening.
//!
//! # Why one subject rather than one per hive
//!
//! The payload is empty and means the same thing to every hive, so per-hive
//! addressing delivers exactly what one subject does, having first made the
//! publisher enumerate the roster and the grant carry a wildcard. Delivery is
//! at-most-once either way, and a hive that was down reconciles on its next
//! periodic pull — a missed event costs latency, not correctness.
//!
//! ⚠️ The per-hive shape was justified by the callout policy's rule that an
//! extra subject must contain `{hive}`. That rule governs what a *hive* may
//! publish; this subject lives in the controller's reader grant, which it does
//! not constrain. The argument came from the wrong half of the permission model.
//!
//! # Why the constant lives here
//!
//! Three consumers name it: the controller publishing, the callout responder
//! granting, and hive-c0re subscribing. A copied literal in the third gives the
//! worst failure of the set — a grant that looks right, a publish that is
//! refused, and, because a NATS denial reaches the client as a timeout, nothing
//! saying so. Unconditional and NATS-type-free for the same reason
//! [`crate::status`]'s bucket name is: the responder speaks neither `jetstream`
//! nor `kv`.
/// The subject the swarm controller publishes on when the hive-wide knowledge
/// repository has changed.
///
/// `$SWARM` rather than a bare name: the `$` prefix is NATS' convention for
/// system-ish subjects, keeping it clear of anything an application might
/// choose for itself.
///
/// Semantic, not transport-shaped — it says what happened, not that a forge
/// webhook arrived. The controller interprets a delivery and decides this is
/// what it meant; a hive receiving it does not need to know a forge exists.
///
/// No unit test here: a single constant has no structure to assert, and a test
/// comparing it to a second spelling is the failure this module exists to
/// prevent. The property worth testing is *who may publish it*, which lives
/// with the policy that decides — see `swarm-nats-auth`.
pub const SUBJECT: &str = "$SWARM.knowledge";

18
swarm-queue-client/src/lib.rs
View file

@ -156,18 +156,14 @@ pub fn chain(error: &dyn std::error::Error) -> String {
/// which is the disagreement this module exists to prevent.
pub mod status;
/// The *knowledge repository changed* subject — one writer (the controller),
/// many readers (the hives).
/// The subject the swarm controller publishes on when the hive-wide knowledge
/// repository has changed. One writer, many readers — every hive subscribes.
///
/// Its own category rather than a leaf under a general event namespace: a
/// namespace built for events that do not exist yet is a shape decided before
/// there is anything to decide it from.
///
/// Unconditional and NATS-type-free for the same reason the bucket name above
/// is: three crates must agree on this string, and the one that agrees hardest
/// — the auth-callout responder, which decides whether a publish is even
/// permitted — speaks neither `jetstream` nor `kv`.
pub mod knowledge;
/// Here rather than in a module of its own for the same reason as the bucket
/// name above: three crates must agree on the string, and the one that agrees
/// hardest — the auth-callout responder, which decides whether a publish is
/// permitted at all — speaks neither `jetstream` nor `kv`.
pub const KNOWLEDGE_SUBJECT: &str = "$SWARM.knowledge";
/// Only the fields this needs; authelia returns several.
#[derive(serde::Deserialize)]