From dde0e1a8c103832aa388c3f972090dd7a723a740 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 5 Aug 2026 12:31:51 +0200 Subject: [PATCH] docs: let the crate README own the technical detail, point at it Per review: crate READMEs will be served on the docs page, so the same technical content in docs/swarm.md and the repo map is redundancy, not thoroughness. docs/swarm.md keeps only what is operator-facing and specific to it -- the option, and why enable is not derived from services.hyperhive.enable -- and points at the README for the socket-directory constraint. The repo map keeps the one-line warning and the pointer, not the argument. This is the same correction as the AgentWindow comments: I had written the socket rationale into five places and called it coverage. Correcting every copy is what preserves the cause. --- CLAUDE.md | 10 +++------- docs/swarm.md | 33 ++++++++------------------------- 2 files changed, 11 insertions(+), 32 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 873c107c..659d1e0d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -145,13 +145,9 @@ hand-maintained per-file tree drifts out of sync with the code. (`services.hyperhive.swarm.controller.enable`). Where `hive-c0re` owns the agents on **one** host, this owns what is true **across** hives; a swarm runs one of them, so most hives leave it off. Serves HTTP over a - unix socket (never a TCP port) that the gateway's nginx proxies to. - ⚠️ The socket lives in its **own** `RuntimeDirectory`: it is `0666` - (nginx is a different user and `connect(2)` needs write), so the - containing directory — bind-mounted wholesale into the gateway - container — is the only access control there is. Never move it under a - directory shared with anything else, `/run/hyperhive` (host admin - socket) above all. A unit test pins the path. + unix socket the gateway's nginx proxies to — ⚠️ **the socket's + directory is its access control**; the constraint that governs it is in + the crate's README, and a unit test pins the path. ### External dependencies with no directory here diff --git a/docs/swarm.md b/docs/swarm.md index b0f166b0..c255d44a 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -238,32 +238,15 @@ migrating agent keeps one unbroken incremental chain. See ## Swarm controller `services.hyperhive.swarm.controller.enable` runs the `swarm-controller` -daemon on this host. It is **off by default and deliberately not derived -from `services.hyperhive.enable`**: a swarm has one controller, so -enabling it is a statement about swarm topology, not about whether -hyperhive is installed. Every hive runs `hive-c0re` (which owns the -agents on that host); one hive additionally runs this (which owns what is -true across hives). +daemon on this host. **Off by default and deliberately not derived from +`services.hyperhive.enable`**: a swarm has one controller, so enabling it +is a statement about swarm topology, not about whether hyperhive is +installed. Every hive runs `hive-c0re` (the agents on that host); one +hive additionally runs this (what is true across hives). -It serves HTTP over a unix socket — `socketPath`, default -`/run/swarm-controller/controller.sock` — rather than a TCP port. The -gateway's nginx is the only intended client and reaches the socket -through a bind-mount, and a listener that is never bound to an address -cannot be reached from off-host by mistake. - -⚠️ **The socket's directory is its access control.** The socket itself is -`0666`, because nginx runs as a different user and `connect(2)` needs -write — the same arrangement hive-c0re uses for the per-agent sockets. -What keeps that safe is that the directory holds one socket and is -bind-mounted into exactly one container. Pointing `socketPath` at a -directory that carries anything else — `/run/hyperhive`, which holds the -host **admin** socket, above all — exposes everything in it to every -consumer that mounts it. Changing `socketPath` therefore means -re-checking the gateway bind-mount, not just the daemon. - -Today the daemon serves a single `/health` endpoint and holds no state: -the unit exists so the swarm-level surfaces that follow have somewhere to -land. +What it serves, why it is a unix socket rather than a port, and the +socket-directory constraint that governs where `socketPath` may point: +[`swarm-controller/README.md`](../swarm-controller/README.md). ## Cross-references