From 84125b08061631c1324682eee0caa3348ffc56db Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 19 Aug 2026 19:26:21 +0200 Subject: [PATCH] docs(#3255): correct the reaper invariant the swarm webhook test guards MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The test's doc named knowledge::ensure_webhook as one of two hive-side reapers. That function is gone; its replacement matches the full URL and cannot touch another hive's hook. The assertion arm stays. The hazard is not what this repository's source says, it is what is deployed — a hive still running the previous version reaps by suffix until it is upgraded, so the arm guards the transition rather than a current code path. Recorded when to drop it. --- hive-c0re/src/forge/mod.rs | 8 +++---- swarm-controller/src/webhook.rs | 40 +++++++++++++++++++-------------- 2 files changed, 27 insertions(+), 21 deletions(-) diff --git a/hive-c0re/src/forge/mod.rs b/hive-c0re/src/forge/mod.rs index 5d5bb182..4da942b1 100644 --- a/hive-c0re/src/forge/mod.rs +++ b/hive-c0re/src/forge/mod.rs @@ -483,8 +483,7 @@ pub async fn ensure_all() { /// existing hooks first and skips creation when one is already targeting the /// correct URL. /// -/// `hive_domain` is the public domain name of the hive (e.g. -/// `pr1ma.darkest.space`); the webhook URL is +/// `hive_domain` is the public domain name of the hive; the webhook URL is /// `https:///webhook/config-pr` (routed through the gateway, /// avoiding the Forgejo SSRF guard that blocks loopback delivery). /// @@ -495,8 +494,9 @@ pub async fn ensure_all() { /// An org-level hook covers every repo in `agent-configs` automatically, /// so no per-repo setup is needed as new agents are provisioned. /// -/// Called at startup alongside `knowledge::ensure_webhook`. No-op when the -/// core token is absent (forge not yet provisioned). +/// Called at startup beside `knowledge::remove_webhook`, its opposite: that +/// repo's one hook is the controller's now, this one has not moved yet. No-op +/// when the core token is absent (forge not yet provisioned). /// /// # Errors /// diff --git a/swarm-controller/src/webhook.rs b/swarm-controller/src/webhook.rs index 5ad47f73..6a2435b6 100644 --- a/swarm-controller/src/webhook.rs +++ b/swarm-controller/src/webhook.rs @@ -170,13 +170,14 @@ pub(super) enum DeliveryKind { /// The route prefix a registered `target_url` must point at. /// /// ⚠️ Deliberately **not** `/webhook/knowledge` or `/webhook/config-pr`, the -/// paths the per-hive receivers use. Both hive-side registrars delete any -/// hook whose URL ends with *their* path but has a different base — see -/// `hive-c0re`'s `forge::ensure_config_pr_webhook` and -/// `workers::knowledge::ensure_webhook`. A swarm-level hook under those -/// paths would therefore be deleted by every hive on every boot, and the -/// symptom is a hook that silently stops existing. `webhook_urls_survive_the_hive_side_reapers` -/// pins that. +/// paths the per-hive receivers use. A hive-side registrar deletes any hook +/// whose URL ends with *its* path but has a different base — see +/// `hive-c0re`'s `forge::ensure_config_pr_webhook`. A swarm-level hook under +/// such a path would therefore be deleted by every hive on every boot, and +/// the symptom is a hook that silently stops existing. +/// `webhook_urls_survive_the_hive_side_reapers` pins that, and its own doc +/// records why `/webhook/knowledge` stays in the check even though the +/// knowledge registrar no longer reaps. const ROUTE_PREFIX: &str = "/webhook/forge/"; impl DeliveryKind { @@ -632,17 +633,22 @@ mod tests { } } - /// A cross-daemon invariant with nothing else to enforce it: both - /// per-hive registrars in `hive-c0re` **delete** hooks whose URL ends - /// with their own path but carries a different base — see - /// `forge::ensure_config_pr_webhook` and `knowledge::ensure_webhook`. + /// A cross-daemon invariant with nothing else to enforce it: a per-hive + /// registrar in `hive-c0re` **deletes** hooks whose URL ends with its + /// own path but carries a different base. A controller URL matching such + /// a suffix would be deleted by every hive on every boot — the swarm hook + /// would simply cease to exist, with the cause in a different daemon's + /// startup sweep. Serving these under `/webhook/forge/` is what avoids + /// it, and this is the only place that says so in a form that fails. /// - /// While the swarm-level hooks live alongside the per-hive ones, a - /// controller URL matching either suffix would be deleted by every hive - /// on every boot: the swarm hook would simply cease to exist, with the - /// cause in a different daemon's startup sweep. Serving these under - /// `/webhook/forge/` is what avoids it, and this is the only place that - /// says so in a form that fails. + /// `forge::ensure_config_pr_webhook` still reaps that way. The knowledge + /// registrar no longer does — it was replaced by a removal that matches + /// the full URL, so it cannot touch another hive's hook. **The + /// `/webhook/knowledge` arm is kept anyway**, because the hazard is not + /// this repository's current code: it is whatever is *deployed*, and a + /// hive still running the previous version reaps by suffix until it is + /// upgraded. Drop that arm once no such hive can exist, not when the + /// source stops mentioning it. #[test] fn webhook_urls_survive_the_hive_side_reapers() { for suffix in ["/webhook/knowledge", "/webhook/config-pr"] {