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
|
|
@ -34,34 +34,33 @@ Two distinct hostnames:
|
|||
*irrevocably* in every `@user:<server_name>` and `!room:<server_name>`
|
||||
identifier minted on this homeserver. Cannot be changed later
|
||||
without abandoning every account and chat history. Defaults to the
|
||||
bare `services.hyperhive.domain` per mara on #660; clients
|
||||
auto-discover the actual API endpoint via the
|
||||
`.well-known/matrix/{client,server}` routes the hive-gateway serves
|
||||
at that domain.
|
||||
bare `services.hyperhive.domain`; clients auto-discover the actual
|
||||
API endpoint via the `.well-known/matrix/{client,server}` routes
|
||||
the hive-gateway serves at that domain.
|
||||
- **`gatewayHost`** — the API listener hostname, where the gateway's
|
||||
matrix vhost proxies `/_matrix/*` to tuwunel. Defaults to
|
||||
`matrix.<services.hyperhive.domain>` (sub-domain shape per mara on
|
||||
#749:9609). Set to `null` to skip the gateway vhost (tuwunel stays
|
||||
direct on `httpPort`).
|
||||
`matrix.<services.hyperhive.domain>` (sub-domain shape). Set to
|
||||
`null` to skip the gateway vhost (tuwunel stays direct on
|
||||
`httpPort`).
|
||||
|
||||
**Breaking change** (#660): `serverName` used to default to
|
||||
**Breaking change**: `serverName` used to default to
|
||||
`matrix.${services.hyperhive.domain}`. Existing homeservers must set
|
||||
the option explicitly to preserve their pre-#660 user / room IDs
|
||||
the option explicitly to preserve their existing user / room IDs
|
||||
before rebuilding. The default flipped because the bare hive-domain
|
||||
makes for cleaner matrix IDs and `.well-known` delegation hides the
|
||||
sub-domain from the user-facing identifier.
|
||||
|
||||
## Default-closed firewall
|
||||
|
||||
`openFirewall` defaults to `false` (#651, secure-by-default): the
|
||||
`openFirewall` defaults to `false` (secure-by-default): the
|
||||
homeserver is reachable from the host + every agent container via
|
||||
loopback either way (shared netns), so the firewall hole only
|
||||
matters for access from *outside* the host. Flip to `true` when
|
||||
announcing the homeserver to other hives or when an external matrix
|
||||
client needs to reach the client-server API directly.
|
||||
|
||||
**Breaking change** (#651): used to default to `true`. Operators
|
||||
relying on external reach must add
|
||||
**Breaking change**: used to default to `true`. Operators relying on
|
||||
external reach must add
|
||||
`services.hyperhive.matrix.openFirewall = true;` before rebuilding.
|
||||
|
||||
Federation port 8448 is intentionally not opened here — tuwunel
|
||||
|
|
@ -82,10 +81,10 @@ see it. The agent only receives the resulting `access_token`.
|
|||
writes when the file is missing or empty; always re-applies 0600
|
||||
(normalises any 0640 / world-readable carry-over from
|
||||
pre-LoadCredential deployments). This runs at activation time
|
||||
(not first container start) to dodge the argus #565 race where
|
||||
nspawn creates an empty file when the bind-mount target is
|
||||
missing and tuwunel reads `registration_token_file=""` rejecting
|
||||
every registration until next restart.
|
||||
(not first container start) to dodge a race where nspawn creates
|
||||
an empty file when the bind-mount target is missing and tuwunel
|
||||
reads `registration_token_file=""`, rejecting every registration
|
||||
until next restart.
|
||||
2. **Read-only bind-mount** maps the host file into the tuwunel
|
||||
container at the same path.
|
||||
3. **systemd `LoadCredential=`** inside the container copies the
|
||||
|
|
@ -93,8 +92,7 @@ see it. The agent only receives the resulting `access_token`.
|
|||
`/run/credentials/tuwunel.service/registration_token`, owned by
|
||||
tuwunel's dynamic user with mode `0400`, at service start. The
|
||||
host file stays `root:root 0600` — no `chown :tuwunel` /
|
||||
`chmod 0640` / GID-pin gymnastics required (per iris on #644
|
||||
8043, dropping the shape #649 originally shipped with). Keeps
|
||||
`chmod 0640` / GID-pin gymnastics required. Keeps
|
||||
`DynamicUser = true` + `PrivateUsers = true` intact.
|
||||
4. tuwunel's `registration_token_file` points at the credentials
|
||||
path, not the original bind-mount path.
|
||||
|
|
@ -104,7 +102,7 @@ see it. The agent only receives the resulting `access_token`.
|
|||
matrix MCP client authenticates with that access_token and
|
||||
never touches the shared registration token.
|
||||
|
||||
Initial rollout settings (#548):
|
||||
Initial rollout settings:
|
||||
|
||||
- `allow_federation = true` at the protocol level so swarms can be
|
||||
wired up later by extending `trustedServers` without a homeserver
|
||||
|
|
@ -114,25 +112,25 @@ Initial rollout settings (#548):
|
|||
engage). The absent
|
||||
`yes_i_am_very_very_sure_…_open_registration_…` flag keeps the
|
||||
server closed to anyone without the token.
|
||||
- `allow_encryption = false` per operator call (#548). E2EE
|
||||
re-enabling tracked at #551.
|
||||
- `allow_encryption = false` per operator call; E2EE re-enabling is
|
||||
deferred to a follow-up.
|
||||
|
||||
## Assertion rationale
|
||||
|
||||
Two `config.assertions` entries fail eval early rather than ship
|
||||
surprising behaviour:
|
||||
|
||||
- **`hyperhiveDomain != null || cfg.serverName != null`** (mara on
|
||||
#548) — `server_name` is embedded into every user / room ID
|
||||
irrevocably; we refuse to spawn the homeserver with a bogus
|
||||
server_name we can never change later.
|
||||
- **`cfg.gatewayHost != ""`** (argus 🟡 on #764) — same footgun as
|
||||
`forge.domain` (#754). Empty string renders `.<hive>`-shaped
|
||||
garbage in both nginx `server_name` (treated as wildcard
|
||||
catch-all, surprising) and `/etc/hosts` (invalid entry). `null`
|
||||
is the right opt-out shape; empty string is rejected explicitly.
|
||||
- **`hyperhiveDomain != null || cfg.serverName != null`** —
|
||||
`server_name` is embedded into every user / room ID irrevocably;
|
||||
we refuse to spawn the homeserver with a bogus `server_name` we
|
||||
can never change later.
|
||||
- **`cfg.gatewayHost != ""`** — same footgun as `forge.domain`:
|
||||
empty string renders `.<hive>`-shaped garbage in both nginx
|
||||
`server_name` (treated as wildcard catch-all, surprising) and
|
||||
`/etc/hosts` (invalid entry). `null` is the right opt-out shape;
|
||||
empty string is rejected explicitly.
|
||||
|
||||
## fluffychat-web build fixes (#685)
|
||||
## fluffychat-web build fixes
|
||||
|
||||
`pkgs.fluffychat-web` ships from `flutter341.buildFlutterApplication`,
|
||||
which has two upstream gaps for fluffychat's web target:
|
||||
|
|
@ -163,37 +161,18 @@ Both fixed in `nix/modules/hive-matrix.nix` via two derivations:
|
|||
|
||||
Two non-obvious fixes from review history:
|
||||
|
||||
- **`make -C js`** instead of `cd js; make` (argus 🟡 on #697 v2)
|
||||
— keeps the build-phase pwd at the source root so `installPhase`
|
||||
doesn't have to know about the cd. Robust against future
|
||||
reorders / `dontBuild`.
|
||||
- **`make -C js`** instead of `cd js; make` — keeps the build-phase
|
||||
pwd at the source root so `installPhase` doesn't have to know
|
||||
about the cd. Robust against future reorders / `dontBuild`.
|
||||
- **`web/native_executor.dart`** as a build-CWD-relative path,
|
||||
*not* `$src/web/...` (#685 / #733 fixup) — `dart`'s
|
||||
`package_config.json` walk-up needs to hit
|
||||
`buildFlutterApplication`'s pub-get output (`.dart_tool/` in the
|
||||
build CWD). Walking up from a read-only `$src/` store path finds
|
||||
no `.dart_tool/` and errors with "Couldn't resolve the package
|
||||
'matrix'". Confused two PRs.
|
||||
*not* `$src/web/...` — `dart`'s `package_config.json` walk-up
|
||||
needs to hit `buildFlutterApplication`'s pub-get output
|
||||
(`.dart_tool/` in the build CWD). Walking up from a read-only
|
||||
`$src/` store path finds no `.dart_tool/` and errors with
|
||||
"Couldn't resolve the package 'matrix'".
|
||||
|
||||
Drop both derivations when nixpkgs's flutter builder grows worker
|
||||
+ emcc support upstream.
|
||||
|
||||
Mount point is `matrix.<hive>/` (#772); upstream `--base-href "/"`
|
||||
is correct at sub-domain root, no override.
|
||||
|
||||
## Sequencing history
|
||||
|
||||
- #548 — initial rollout (federation enabled, registration enabled,
|
||||
E2EE disabled)
|
||||
- #565 — first-boot empty-token race fix → activation-time token
|
||||
generation
|
||||
- #644 / iris 8043 / #649 — registration token ownership shape
|
||||
(dropped chown/GID-pin; LoadCredential delivers as 0400 dynamic-user)
|
||||
- #651 — `openFirewall` default flipped to `false`
|
||||
- #660 — `serverName` default flipped to bare hive-domain (was
|
||||
`matrix.<hive>`)
|
||||
- #685 / #697 / #733 — fluffychat-web build fixes (Imaging emscripten,
|
||||
native_executor dart worker, build-CWD path)
|
||||
- #736 — fluffychat config.json inline JSON at sub-domain root
|
||||
- #749 / #764 — gateway sub-domain shape verdict
|
||||
- #772 / #775 — fluffychat hops from `<hive>/matrix/` to `matrix.<hive>/`
|
||||
Mount point is `matrix.<hive>/`; upstream `--base-href "/"` is
|
||||
correct at sub-domain root, no override.
|
||||
|
|
|
|||
Loading…
Reference in a new issue