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

docs(#3255): the controller is to interpret deliveries, not relay them

Browse source 
mara's ruling: the controller should not forward received events, it
should create specific messages from them ("knowledge repo changed",
"deploy agent foo to rev abc123") and send those to whoever needs them.
The module doc said the opposite as settled design.

The argument it made was wrong in a specific way worth keeping: it
counted this daemon as a *second* place deciding what a delivery means,
while assuming the hives stay interpreters. They do not -- the parsing
moves rather than duplicating, so the end state has one interpreter, not
two.

Doc-only. The behaviour is unchanged and still receipt-only; what changes
is that the next reader is not told the wrong direction.
This commit is contained in:
atlas 2026-08-18 12:30:27 +02:00
commit 0ce6e8410a
1 changed files with 17 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

30
swarm-controller/src/webhook.rs
View file

@ -6,22 +6,26 @@
//! deliveries. One owner is the only non-racing shape, and the only
//! swarm-wide thing in the deployment is this daemon.
//!
//! **This relays; it does not interpret.** The payload stays opaque bytes,
//! keyed by a [`DeliveryKind`] from the URL path. The hives already know
//! what a delivery *means* — which repo is the knowledge repo, which config
//! PR action queues an approval — so parsing it here would be a second place
//! deciding that, and the two would drift.
//! **Receipt only, for now — the interpretation lands here next.** The
//! payload is currently opaque bytes keyed by a [`DeliveryKind`] from the URL
//! path, because nothing consumes it yet.
//!
//! **The HMAC code is not shared with `hive-c0re` because c0re's copy is
//! leaving, not staying.** Once registration moves here, hives stop
//! registering *and* receiving, and c0re's routes and secret go with it. A
//! shared crate is right when a second consumer *arrives*; here it is
//! departing. The two verifiers meanwhile check different hooks with
//! different secrets and never need to agree.
//! ⚠️ This used to say *"this relays; it does not interpret"*, and that is no
//! longer the direction: this daemon is to **parse a delivery and emit a
//! semantic message** — *knowledge repo changed*, *deploy agent X at rev Y* —
//! addressed to whoever needs it, rather than forwarding forge bytes for each
//! hive to re-derive. The earlier reasoning ("parsing here would be a second
//! place deciding what a delivery means") counted this daemon as a *second*
//! interpreter while assuming the hives stay interpreters. They do not: the
//! parsing **moves** rather than duplicating, so one place decides.
//!
//! The HMAC code is deliberately **not** shared with `hive-c0re`: that copy
//! is leaving, not staying, and a shared crate is right only when a second
//! consumer *arrives*. Same arriving-or-leaving question as the paragraph
//! above, asked about code instead of about meaning.
//!
//! **These hooks are registered ALONGSIDE the per-hive ones** — see
//! [`crate::forge::Client::ensure_swarm_webhooks`], which carries why, and
//! why moving them cannot come before fan-out.
//! [`crate::forge::Client::ensure_swarm_webhooks`].
use anyhow::{Context as _, Result};
use axum::{