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: let the crate README own the technical detail, point at it

Browse source 
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.
This commit is contained in:
atlas 2026-08-05 12:31:51 +02:00 • committed by mara
commit dde0e1a8c1
2 changed files with 12 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

33
docs/swarm.md
View file

@ -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