vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: name options by the path an operator can set, not by cfg.*

Browse source 
`cfg` is whatever the reading module bound it to. It does not exist in a
NixOS configuration, so a sentence naming an option as `cfg.<name>` is
correct about behaviour and unusable as an instruction — the reader has
to go find the real path.

The four sites in docs/networking/gateway.md this was filed for:

  cfg.sshPort       -> services.hyperhive.swarm.forge.sshPort
  cfg.dashboardPort -> services.hyperhive.c0re.dashboardPort
  cfg.frontend (x2) -> services.hyperhive.c0re.frontend

Sweeping docs/ for the pattern rather than the ticket's line numbers
found five more, in four other files:

  approvals.md    cfg.hyperhiveFlake        -> services.hyperhive.c0re.hyperhiveFlake
  matrix.md       cfg.registrationTokenFile -> services.hyperhive.deploy.matrix.registrationTokenFile
  matrix.md       cfg.gatewayHost           -> services.hyperhive.swarm.matrix.gatewayHost
  conventions.md  cfg.dashboardPort         -> services.hyperhive.c0re.dashboardPort
  gotchas.md      cfg.dashboardPort         -> services.hyperhive.c0re.dashboardPort

matrix.md is the clearest case for doing this at all: its two `cfg.`
references resolve to *different* option trees — `deploy.matrix` and
`swarm.matrix` — so the shorthand is ambiguous even within one file.

Each path is read off the `mkOption` that declares it plus the
`options.services.hyperhive.*` root it sits under, with the indentation
checked so a nested block cannot have been missed. `cfg.frontend` is
declared in hive-c0re, not the gateway: the gateway module binds
`cfg = config.services.hyperhive.gateway`, which has no `frontend`.

Deliberately unchanged: docs/networking/snapshot-store.md:136, where
`cfg.port` sits inside a ```nix block quoting module source. `cfg` is
correct there, and rewriting it would make the snippet wrong.

Closes #4193.
This commit is contained in:
atlas 2026-09-11 12:20:33 +02:00 • committed by mara
commit 3f878408f0
5 changed files with 10 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/integrations/matrix.md
View file

@ -96,7 +96,7 @@ Token-gated registration: hive-c0re holds the token, agents never
see it. The agent only receives the resulting `access_token`.
1. **System activation** writes a 32-byte random hex token (64
chars) to `cfg.registrationTokenFile`
chars) to `services.hyperhive.deploy.matrix.registrationTokenFile`
(`/var/lib/hyperhive/matrix-register-token` by default), mode
`0600 root:root`, before any container start. Idempotent — only
writes when the file is missing or empty; always re-applies 0600
@ -215,7 +215,7 @@ resource-constrained hosts where a 20 MB request is unexpectedly large.
`config.assertions` in this module fail eval early rather than ship
surprising behaviour:
- **`cfg.gatewayHost != ""`** — same footgun as `forge.domain`:
- **`services.hyperhive.swarm.matrix.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;