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

feat(nix): the matrix server_name follows the swarm domain too

Browse source 
A swarm runs one homeserver, so its identity belongs to the swarm and
not to whichever hive happens to host it -- otherwise relocating the
container between hives reads as a different homeserver rather than a
move. `gatewayHost` moved for that reason a commit ago; `serverName`
was left behind, which made the identity hive-shaped and the routing
swarm-shaped.

⚠️ This is the one value on the page that a rebuild cannot undo.
`gatewayHost` is a routing detail clients rediscover through
`.well-known`; `server_name` is embedded in every user and room id, so
adopting a new one strands the existing accounts and rooms rather than
renaming them -- their ids still name a homeserver that stops
answering. Moving the DEFAULT is safe; moving a RUNNING deployment is
not, and existing hives must pin the value they already minted ids
under before rebuilding.

The fallback stays total on a null swarm domain for the same reason as
its neighbours: the required-domain assertion in hive-network.nix is
what should fire, not a coercion error from an unrelated option
interpolating null.

The legacy-pin eval probe now covers `serverName` as well. It existed
to answer "what do I set so old deployments don't change", and was
proving that only for the two values that are cheap to change -- the
irreversible one was the one it did not assert.
This commit is contained in:
atlas 2026-08-09 17:09:54 +02:00 • committed by mara
commit a5210311bf
2 changed files with 81 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

46
docs/matrix.md
View file

@ -33,29 +33,39 @@ 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`; 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.swarm.domain`; clients auto-discover the
actual API endpoint via the `.well-known/matrix/{client,server}`
routes the gateway serves at that domain.
- **`gatewayHost`** — the API listener hostname, where the gateway's
matrix vhost proxies `/_matrix/*` to tuwunel. Defaults to
`chat.<services.hyperhive.swarm.domain>` — the **swarm's** domain,
because a swarm runs one homeserver. Set to `null` to skip the
`chat.<services.hyperhive.swarm.domain>`. Set to `null` to skip the
gateway vhost (tuwunel stays direct on `httpPort`).
⚠️ Only this one moved. `serverName` still defaults to the bare hive
domain, and the two are independent by design: `gatewayHost` is a
routing detail clients rediscover through `.well-known`, while
`serverName` is baked into every user and room id. A deployment that
wants its old API hostname pins
`gatewayHost = "matrix.<hive-domain>"` — exactly what the previous
default rendered.
Both now default under the **swarm** domain, because a swarm runs one
homeserver: tying its identity to a single hive's domain would make
relocating the container between hives look like a different
homeserver.
**Breaking change**: `serverName` used to default to
`matrix.${services.hyperhive.domain}`. Existing homeservers must set
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.
⚠️ **They are still not interchangeable, and the difference is the
cost of changing one.** `gatewayHost` is a routing detail clients
rediscover through `.well-known`, so it is safe to move on a running
deployment. `serverName` is baked into every user and room id, so
adopting a new one does **not** rename the existing users and rooms —
it strands them, because their ids still name a homeserver that no
longer answers.
**Breaking change — pin `serverName` before rebuilding.** Its default
has now moved twice: from `matrix.${services.hyperhive.domain}`, to
the bare hive domain, and now to the swarm domain. Any homeserver that
has already minted ids must name the value it minted them under:
```nix
services.hyperhive.swarm.matrix = {
# whichever this deployment already uses
serverName = config.services.hyperhive.domain;
gatewayHost = "matrix.${config.services.hyperhive.domain}";
};
```
## Default-closed firewall