docs: scrub #NNN self-references (closes #719)
Last pass of the docs-from-code → docs/ epic (#708). Drops every attribution cookie from docs/ + README.md + CLAUDE.md so the source-tree files no longer reference the issue tracker. Issue threads + commit history retain the references — those are the canonical record. - README.md: drop #701 / #660×2 / #551 from matrix + display-name sections, rephrase to convey the semantics directly - CLAUDE.md: scrub 18 cookies from the file map (#655, #15, #784, #832, #444, #425, #361, #548, #598, #539, #544, #589, #701, #658, #280, #660, #551, #764, #772, #793, #14, #805) - docs/agent-hierarchy.md: drop #658 ×3 (per-agent user is the current shape, not a transition) - docs/conventions.md: drop #571 (replaced with a docs xref to persistence.md::matrix-avatar-sync) - docs/gateway.md: scrub vhost-map table cookies + Sub-domain rationale + Per-agent unix-socket upstream + Self-signed TLS + Firewall posture + HIVE_FORGE_URL + Per-agent error pages sections; drop the trailing 'Sequencing history' issue list + the 'Next-up' issue-link footnote - docs/matrix.md: scrub serverName/gatewayHost + Default-closed firewall + Provisioning flow + Initial rollout + Assertion rationale + fluffychat-web build fixes; drop the trailing 'Sequencing history' issue list - docs/network.md: drop 'Why ship before #14' #805 quote + Container shape #805 attribution + trailing 'Sequencing history' + Cross-references issue links; rename v2 column to 'after netns isolation' - docs/web-ui.md: drop #784 from Container row, replace with a docs xref to docs/gateway.md::Per-agent unix-socket upstream Only remaining #NNN in docs/ is the literal markdown-heading example in docs/forge.md (`#tag`, `#123`, `#!/bin/bash`) which demonstrates the renderer's behaviour — not an attribution cookie.
This commit is contained in:
parent
2a2d76d733
commit
6bdfe52386
8 changed files with 142 additions and 187 deletions
|
|
@ -1,23 +1,21 @@
|
|||
# hive-network
|
||||
|
||||
Host-side bridge + per-agent DNS resolver — the foundation that
|
||||
makes [`#14` container netns isolation](http://localhost:3000/hyperhive/hyperhive/issues/14)
|
||||
safe to land. Configured via `services.hyperhive.network.*`; off by
|
||||
default during rollout.
|
||||
makes container netns isolation safe to land. Configured via
|
||||
`services.hyperhive.network.*`; off by default during rollout.
|
||||
|
||||
## Why ship before #14
|
||||
## Why ship before netns isolation
|
||||
|
||||
Mara on #805#issuecomment-11541: "we need it before #14 so nothing
|
||||
breaks when we switch over". If netns isolation lands first, agent
|
||||
containers lose `/etc/resolv.conf` propagation from the host and DNS
|
||||
breaks until a separate resolver is up. Inverting the sequence —
|
||||
bridge + dnsmasq first, netns flip second — makes the flag day
|
||||
boring: the resolver endpoint is already live, agents just discover
|
||||
it via veth instead of shared netns.
|
||||
If netns isolation lands first, agent containers lose
|
||||
`/etc/resolv.conf` propagation from the host and DNS breaks until a
|
||||
separate resolver is up. Inverting the sequence — bridge + dnsmasq
|
||||
first, netns flip second — makes the flag day boring: the resolver
|
||||
endpoint is already live, agents just discover it via veth instead
|
||||
of shared netns.
|
||||
|
||||
## v1 vs v2
|
||||
|
||||
| feature | v1 (this PR) | v2 (after #14) |
|
||||
| feature | v1 (this PR) | v2 (after netns isolation) |
|
||||
|---|---|---|
|
||||
| bridge interface | created on host, no slave NICs | per-agent veth pairs attach |
|
||||
| dnsmasq binding | bridge IP (reachable via host loopback in shared netns) | bridge IP (reachable via veth in private netns) |
|
||||
|
|
@ -27,18 +25,17 @@ it via veth instead of shared netns.
|
|||
|
||||
The `address` rules ship pointing at the bridge IP from v1 so the
|
||||
DNS contract is fixed before any container actually depends on it
|
||||
— minimises the things that flip on #14 day.
|
||||
— minimises the things that flip on netns day.
|
||||
|
||||
## Container shape (where dnsmasq lives)
|
||||
|
||||
Co-located in the existing `hive-gateway` container per mara on
|
||||
#805:10957 — single front-door for both DNS and HTTP, saves a
|
||||
sibling container, single systemd-unit / state surface to monitor.
|
||||
The gateway shares host netns (`privateNetwork = false`) so
|
||||
dnsmasq's `bind-interfaces` listener on `bridgeIp` works without
|
||||
any veth gymnastics today; when #14 flips agent containers to
|
||||
private netns the binding doesn't change (it's still on the host's
|
||||
bridge interface).
|
||||
Co-located in the existing `hive-gateway` container — single
|
||||
front-door for both DNS and HTTP, saves a sibling container, single
|
||||
systemd-unit / state surface to monitor. The gateway shares host
|
||||
netns (`privateNetwork = false`) so dnsmasq's `bind-interfaces`
|
||||
listener on `bridgeIp` works without any veth gymnastics today; when
|
||||
agent containers flip to private netns the binding doesn't change
|
||||
(it's still on the host's bridge interface).
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
@ -98,16 +95,6 @@ agent containers.
|
|||
interface only. Other interfaces stay closed. The hive resolver
|
||||
isn't an external-facing service.
|
||||
|
||||
## Sequencing history
|
||||
|
||||
- mara on #805 (`comment-10957`): "can we put the resolver into the
|
||||
gateway container?" — yes, this v1 does that.
|
||||
- mara on #805 (`comment-11541`): "we need it before #14 so nothing
|
||||
breaks when we switch over" — flipped the dependency direction;
|
||||
v1 ships now, #14 flips containers later.
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Issue [#805](http://localhost:3000/hyperhive/hyperhive/issues/805) — DNS resolver tracking
|
||||
- Issue [#14](http://localhost:3000/hyperhive/hyperhive/issues/14) — netns isolation (downstream consumer)
|
||||
- `docs/gateway.md` — vhost map + the gateway container's other duties
|
||||
|
|
|
|||
Loading…
Reference in a new issue