From 32e4c687b8a83dd2ff5a69012d5cfe121d07881f Mon Sep 17 00:00:00 2001 From: atlas Date: Sat, 4 Jul 2026 22:16:06 +0200 Subject: [PATCH] docs(gateway): remove stale TCP loopback fallback section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The TCP fallback was removed from gateway_nginx.rs in the previous commit. Update docs/gateway.md to match: - Step 4: remove 'TCP loopback for agents not yet rebuilt' — always UDS now - Remove the 'TCP loopback fallback' subsection entirely --- docs/gateway.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/docs/gateway.md b/docs/gateway.md index 952c6cce..29b3cd09 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -103,10 +103,10 @@ now set unconditionally for every agent. The mechanism: (Legacy name `.bound` also accepted during the transition window.) 4. **Gateway side**. `gateway_nginx::write` generates `/var/lib/hyperhive/gateway/agents.conf` — a plain nginx include - file with one `location /agent//` block per agent. UDS - upstream (`http://unix:/run/hive-agent//web.sock:/`) when - `hyperhive-socket-bound` marker present; TCP loopback for agents - that haven't yet been rebuilt under the new config. + file with one `location /agent//` block per agent. Always + a UDS upstream (`http://unix:/run/hive-agent//web.sock:/`); + if the socket is not yet bound, nginx returns 502 caught by the + `error_page 502 503 504 = /__hive_agent_unreachable` directive. The gateway container bind-mounts `/var/lib/hyperhive/gateway/` at `/run/hive-state/`; nginx includes `/run/hive-state/agents.conf`. After each write, c0re triggers the appropriate nginx action inside @@ -127,17 +127,6 @@ idempotent — skips the rename when content is unchanged. Failed reloads are retried automatically on subsequent poll ticks via `gateway_nginx::reload_if_pending`. -## TCP loopback fallback - -While an agent's unix-socket marker is absent, the gateway routes its -`/agent//` traffic to a TCP loopback upstream in `agents.conf`. The -port is derived on the fly from `lifecycle::agent_web_port(name)` — a pure -FNV-1a hash of the name, reproducible from the name alone, no name -special-cased (so no on-disk port map is needed). Once the agent binds its -unix socket — every agent does, via `HIVE_WEB_SOCKET` — the gateway -switches to the socket upstream from `agent-sockets.json`. The root agent's -UI is routed at `/agent/root/`. - `agents.conf` uses atomic `.tmp` + `rename()` writes so a crashing c0re process never leaves a partial or unparseable file behind.