diff --git a/nix/modules/hive-matrix.nix b/nix/modules/hive-matrix.nix index 1e8024b4..d4964534 100644 --- a/nix/modules/hive-matrix.nix +++ b/nix/modules/hive-matrix.nix @@ -205,49 +205,17 @@ in ''; example = "matrix.example.com"; description = '' - Public hostname for the matrix homeserver behind the - hive-gateway nginx (#747, mara verdict on #749:9609 — sub-domain - over sub-path for matrix, but **not user-visible** because the - `.well-known/matrix/{client,server}` redirect routes clients - through automatically). + Public hostname for the matrix homeserver behind the gateway. + 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`). See + `docs/gateway.md` for the vhost map + matrix discovery flow, + and the federation port-8448 caveat at the bottom of that doc. - When set + gateway is on, the gateway adds a `server { server_name - = gatewayHost; }` block that proxies `/_matrix/...` → - `http://127.0.0.1:''${httpPort}/_matrix/...`. The - `.well-known/matrix/{client,server}` endpoints (served by the - gateway at the bare hive-domain) then point at - `http(s)://''${gatewayHost}/` — matrix clients automatically - discover + follow that delegation. - - Defaults to `matrix.''${services.hyperhive.domain}` when the - hive-domain is set (idiomatic matrix-spec shape — `matrix` - labelled under the hive's bare server_name domain). Defaults to - `null` when the hive-domain is unset (gateway vhost not added; - clients reach tuwunel directly on `httpPort`). - - Set to a full hostname (`matrix.example.com`, - `homeserver.internal.lan`) for a bespoke vhost shape. Set to - `null` to disable the gateway vhost entirely (tuwunel stays - direct on `httpPort`). - - **server_name vs gatewayHost**: `serverName` is the matrix - identifier domain embedded in user/room IDs irrevocably (per - #660 default = bare hive-domain). `gatewayHost` is just where - the API listens behind nginx. The two are different — see the - matrix-spec server-discovery flow. - - **Federation port caveat**: the `.well-known/matrix/server` - delegation advertises `''${gatewayHost}` with no port suffix - when the gateway listens on 80. Per the matrix federation - spec, peers fall back to port 8448 when no explicit port is - present — but the gateway only listens on the configured - `services.hyperhive.gateway.port`. Cross-hive federation - therefore needs either: - - a DNS SRV record (`_matrix._tcp.''${gatewayHost}` → port 80), - - or `services.hyperhive.matrix.openFirewall = true` so peers - can reach tuwunel's federation port directly. - Hyperhive is mostly closed/internal, so this rarely bites in - practice — but flagging for the federation-curious operator. + Note: `gatewayHost` is the API listener hostname (where nginx + proxies `/_matrix/*`); `serverName` is the matrix-identifier + domain embedded irrevocably in user/room IDs (per #660 + default = bare hive-domain). The two are distinct. ''; }; @@ -326,23 +294,12 @@ in default = cfg.enable; defaultText = lib.literalExpression "config.services.hyperhive.matrix.enable"; description = '' - Serve a matrix web client (default `pkgs.fluffychat-web`) as - a static dist at the root of the matrix sub-domain vhost - (`matrix.''${services.hyperhive.domain}/`, via the hive-gateway - nginx — #607 / #634 / #772). Defaults to whatever - `services.hyperhive.matrix.enable` is — turning on the - homeserver gives you the web client by default; set to - `false` explicitly to opt out of the GUI while keeping the - homeserver running for agents. Requires - `services.hyperhive.gateway.enable` (default on) + - `services.hyperhive.matrix.gatewayHost != null` (default - `matrix.`); when either is off no one hosts the GUI - and the `M4TR1X →` dashboard tab is hidden. - - The `.well-known/matrix/{client,server}` delegation (served - on the bare hive-domain) advertises this sub-domain, so - clients opened at `http:///` auto-discover the - fluffychat root automatically. + Serve a matrix web client at `matrix.''${services.hyperhive.domain}/`. + Requires `gateway.enable` + `matrix.gatewayHost != null` + (default true / `matrix.` when hive-domain set). When + off, the dashboard's `M4TR1X →` tab is hidden. See + `docs/gateway.md` for the discovery flow that lets clients + auto-find the sub-domain. ''; }; @@ -350,25 +307,15 @@ in type = lib.types.package; default = fluffychat-web-fixed; defaultText = lib.literalMD '' - `pkgs.fluffychat-web` patched via `postInstall` to add the - three files `flutter341.buildFlutterApplication` skips: - `native_executor.js` (compiled via `dart compile js` from - `web/native_executor.dart`), plus `Imaging.js` + - `Imaging.wasm` (built from the `native_imaging` dart - package's C source via `pkgs.emscripten`). See the `let` - block in `nix/modules/hive-matrix.nix` for the full - rationale (#685, #772). + `pkgs.fluffychat-web` + #685 `postInstall` patch (adds the + three files `flutter341.buildFlutterApplication` skips). ''; description = '' - Static web client dist to serve at the matrix sub-domain - root (`matrix.''${services.hyperhive.domain}/`). Defaults - to `pkgs.fluffychat-web` with the #685 `postInstall` patch - for the three missing files. Override to swap for - `hydrogen-web` (lightest), `cinny` (no threads), - `element-web` (heaviest, full features), or an out-of-tree - client dist — any replacement gets served at the sub-domain - root with the upstream-default ``, no - sub-path gymnastics needed. + Static web client dist served at `matrix./`. Override + to swap fluffychat for hydrogen-web, cinny, element-web, or + an out-of-tree dist — any replacement is mounted at the + sub-domain root with the upstream-default ``, + no sub-path gymnastics needed. ''; }; };