68bac7986b
mara on PR #729: "this still feels hacky - is there a proper way to do this?" damocles: agreed, "Accept-header map is meaningfully better than the allowlist [...] one map definition that encodes browser semantics directly, vs ~20 extensions to keep synced with whatever fluffychat (and any future hyperhive-served SPA) decides to ship". The previous shape (#684 catch-all regex, then this PR v1's extension allowlist) leaned on heuristics to distinguish "missing asset → 404" from "unknown SPA route → fall back to index.html". Both shapes were fragile against a SPA shipping a new extension, and the allowlist became dead code the moment a route ended in `.html-ish-suffix`. The proper distinction lives at the HTTP layer: top-frame browser navigations send `Accept: text/html,...` (chrome/firefox/safari are consistent on this). Asset fetches from script tags / img / fetch() / XHR send asset-typed Accepts (`image/*`, `application/javascript`, `*/*`) without `text/html`. Mechanics: an `nginx http`-context `map` keyed on `$http_accept` emits either `/matrix/index.html` (navigation) or a sentinel nonexistent path (`/__matrix_spa_no_html_fallback`); the location's `try_files $uri $uri/ $matrix_spa_target =404;` does the right thing for both cases. No extension list, no regex narrowing, no `if` block, no named-location fallback. The `map` lives in `services.nginx.appendHttpConfig` (only added when the matrix GUI is on, otherwise no `map` directive at all). The location's `extraConfig` is now a single `try_files` line. Verified via `nix eval` on both the rendered `appendHttpConfig` and the location's `extraConfig`. Full closure build pending operator deploy. Closes #686.
278 lines
12 KiB
Nix
278 lines
12 KiB
Nix
{
|
|
pkgs,
|
|
lib,
|
|
config,
|
|
...
|
|
}:
|
|
let
|
|
cfg = config.services.hyperhive.gateway;
|
|
hyperhiveDomain = config.services.hyperhive.domain;
|
|
matrixCfg = config.services.hyperhive.matrix;
|
|
in
|
|
{
|
|
# Single nginx in front of every hyperhive surface (#609 / #15 v0).
|
|
# Lives in its own nixos-container (like hive-forge / hive-matrix) so
|
|
# the operator can opt out without touching the host's own nginx, and
|
|
# so the static-serve responsibility for the matrix GUI moves off
|
|
# hive-c0re's axum router. Shares host netns so `localhost`
|
|
# upstream resolution works without any port-forward dance.
|
|
#
|
|
# Routes (v0):
|
|
# `location /matrix/` → static-serve fluffychat-web dist (when
|
|
# `services.hyperhive.matrix.gui.enable` is true)
|
|
# `location /` → proxy_pass to hive-c0re's dashboard upstream
|
|
#
|
|
# Container name `hive-gateway` keeps hive-c0re's lifecycle scanner
|
|
# (which only sees `h-*`) out of the picture. State-free — nginx
|
|
# config lives in the nix store, no runtime persistence to manage.
|
|
|
|
options.services.hyperhive.gateway = {
|
|
enable = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = true;
|
|
description = ''
|
|
Run hive-gateway — a single nginx in front of every hyperhive
|
|
surface. On by default: the gateway hosts the matrix GUI static
|
|
dist (when `services.hyperhive.matrix.gui.enable` is true) and
|
|
proxies everything else to hive-c0re's dashboard upstream. Set
|
|
`services.hyperhive.gateway.enable = false` to bypass nginx
|
|
entirely and reach hive-c0re directly on its dashboard port
|
|
(7000 by default).
|
|
|
|
v0 is HTTP-only; TLS / public-domain shape is tracked
|
|
separately.
|
|
'';
|
|
};
|
|
|
|
port = lib.mkOption {
|
|
type = lib.types.port;
|
|
default = 80;
|
|
example = 8080;
|
|
description = ''
|
|
TCP port the gateway listens on. Default 80 (canonical web
|
|
port). nginx inside the container binds <1024 because the
|
|
container's init runs as root; if 80 is already taken on the
|
|
host (existing nginx, traefik, etc.) override to an unused
|
|
port like 8080 or move the conflicting service.
|
|
'';
|
|
};
|
|
|
|
upstreamHost = lib.mkOption {
|
|
type = lib.types.str;
|
|
default = "127.0.0.1";
|
|
description = ''
|
|
Host the gateway proxies non-static requests to. Defaults to
|
|
`127.0.0.1` because the gateway container shares the host
|
|
netns, so loopback resolves directly to hive-c0re.
|
|
'';
|
|
};
|
|
|
|
upstreamPort = lib.mkOption {
|
|
type = lib.types.port;
|
|
default = 7000;
|
|
description = ''
|
|
TCP port the gateway proxies non-static requests to. Defaults
|
|
to `7000` (hive-c0re's out-of-the-box dashboard port). Operators
|
|
who change `services.hyperhive.c0re.dashboardPort` should set
|
|
`upstreamPort` to match — kept as a hardcoded default rather
|
|
than a cross-reference to keep this module's options eval
|
|
independent of c0re's option tree shape.
|
|
'';
|
|
};
|
|
|
|
openFirewall = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = false;
|
|
example = true;
|
|
description = ''
|
|
Open `port` in the host firewall. Off by default (#651,
|
|
secure-by-default). Flip to `true` to expose the gateway to
|
|
the operator's browser / external clients — required for any
|
|
out-of-host reach, since the agents themselves talk to
|
|
hive-c0re via the per-agent unix sockets and don't need the
|
|
nginx vhost. Leave off when running behind another reverse
|
|
proxy (e.g. caddy / traefik on the host) that handles TLS
|
|
termination + forwards to `port`.
|
|
|
|
**Breaking change as of #651**: this used to default to
|
|
`true`. If you relied on the old default for external reach
|
|
(the common case — the gateway is the operator's primary
|
|
entry point), add `services.hyperhive.gateway.openFirewall = true;`
|
|
to your host config before rebuilding.
|
|
'';
|
|
};
|
|
|
|
localHostsEntry = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = false;
|
|
example = true;
|
|
description = ''
|
|
Add an `/etc/hosts` entry mapping `services.hyperhive.domain`
|
|
to `127.0.0.1` on the host. Useful for local deployments +
|
|
tests where there's no real DNS for `services.hyperhive.domain`
|
|
but the operator (or browser-based tests) want to hit
|
|
`http://''${services.hyperhive.domain}` to exercise the
|
|
gateway shape. Off by default — operators running with real
|
|
DNS shouldn't have a stale `/etc/hosts` entry sticking
|
|
around. Requires `services.hyperhive.domain` to be set.
|
|
'';
|
|
};
|
|
};
|
|
|
|
config = lib.mkIf cfg.enable {
|
|
assertions = [
|
|
{
|
|
assertion = !cfg.localHostsEntry || hyperhiveDomain != null;
|
|
message = ''
|
|
services.hyperhive.gateway.localHostsEntry = true requires
|
|
services.hyperhive.domain to be set. Either pin a hostname
|
|
or leave `localHostsEntry` at its default of false.
|
|
'';
|
|
}
|
|
];
|
|
|
|
containers.hive-gateway = {
|
|
autoStart = true;
|
|
ephemeral = false;
|
|
# Share host netns — nginx then binds host-level ports directly,
|
|
# `localhost` upstream resolution reaches hive-c0re without any
|
|
# port-forward dance, and the firewall config below is the only
|
|
# layer that matters.
|
|
privateNetwork = false;
|
|
config =
|
|
{ pkgs, ... }:
|
|
{
|
|
system.stateVersion = "26.05";
|
|
services.nginx = {
|
|
enable = true;
|
|
recommendedProxySettings = true;
|
|
recommendedOptimisation = true;
|
|
# SPA-fallback target keyed on the `Accept` request header
|
|
# (#686, mara + damocles on PR #729). This decides whether a
|
|
# `/matrix/...` miss falls through to `index.html` (route
|
|
# navigation) or returns a clean 404 (asset miss) — see the
|
|
# `/matrix/` location comment below for the full rationale.
|
|
#
|
|
# Top-frame browser navigations always send
|
|
# `Accept: text/html,...` (chrome/firefox/safari are
|
|
# consistent on this). Asset fetches from script tags / img
|
|
# / fetch() / XHR send asset-typed Accepts (`image/*`,
|
|
# `application/javascript`, `*/*`) without `text/html`.
|
|
# Mapping is purely on the header → no extension allowlist
|
|
# to keep in sync with whatever the SPA ships, no regex
|
|
# heuristic to false-positive on dot-segment routes.
|
|
#
|
|
# `$matrix_spa_target` defaults to a sentinel nonexistent
|
|
# path so `try_files` falls through to the trailing `=404`
|
|
# for asset misses. Browser navigations route to
|
|
# `/matrix/index.html` where the SPA's client-side router
|
|
# takes over.
|
|
#
|
|
# Only emitted when the matrix GUI is on (saves a no-op
|
|
# `map` directive otherwise).
|
|
appendHttpConfig = lib.optionalString (matrixCfg.enable && matrixCfg.gui.enable) ''
|
|
map $http_accept $matrix_spa_target {
|
|
default "/__matrix_spa_no_html_fallback";
|
|
"~*text/html" "/matrix/index.html";
|
|
}
|
|
'';
|
|
virtualHosts."_" = {
|
|
listen = [
|
|
{
|
|
addr = "0.0.0.0";
|
|
port = cfg.port;
|
|
}
|
|
];
|
|
locations =
|
|
# Matrix GUI: when the operator has flipped both
|
|
# `services.hyperhive.matrix.enable` and `matrix.gui.enable`
|
|
# on, nginx serves fluffychat-web (or whatever override)
|
|
# as a static dist at `/matrix/`.
|
|
#
|
|
# SPA fallback (iris/#643, rewritten in #686 per mara
|
|
# + damocles on PR #729): the original
|
|
# `try_files $uri $uri/ /matrix/index.html;` shape
|
|
# silently masked missing assets — flutter's bootstrap
|
|
# requesting e.g. `/matrix/native_executor.js` got
|
|
# `index.html` (Content-Type: text/html, status 200)
|
|
# when the file was absent from the dist, so the JS
|
|
# runtime never loaded and `/matrix/` rendered blank
|
|
# without any visible error.
|
|
#
|
|
# The followup #729 narrowed it with an extension
|
|
# allowlist; this version uses `$matrix_spa_target`
|
|
# (defined in the `appendHttpConfig` above, keyed on
|
|
# the `Accept` header) so the decision lives in HTTP
|
|
# semantics rather than a maintained extension list.
|
|
# Navigations (Accept: text/html) fall to index.html;
|
|
# asset fetches (Accept: */*, image/*, etc.) get a
|
|
# clean 404 via the trailing `=404`.
|
|
lib.optionalAttrs (matrixCfg.enable && matrixCfg.gui.enable) {
|
|
"/matrix/" = {
|
|
alias = "${matrixCfg.gui.package}/";
|
|
extraConfig = ''
|
|
try_files $uri $uri/ $matrix_spa_target =404;
|
|
'';
|
|
};
|
|
}
|
|
//
|
|
# `.well-known/matrix/*` auto-discovery (#660): when
|
|
# `services.hyperhive.matrix.enable` is on and the
|
|
# operator's set a hive domain, the gateway serves
|
|
# the matrix-spec discovery JSON at the canonical
|
|
# location so clients pointed at `${hyperhive.domain}`
|
|
# resolve through to the actual tuwunel endpoint
|
|
# without needing a `matrix.` subdomain.
|
|
#
|
|
# `m.homeserver.base_url` advertises the client-server
|
|
# API. `m.server` advertises the federation
|
|
# `host:port` (tuwunel serves both client + federation
|
|
# on the same `httpPort` — see hive-matrix.nix).
|
|
#
|
|
# CORS `*` on the client endpoint per the matrix spec
|
|
# (https://spec.matrix.org/v1.15/client-server-api/#getwell-knownmatrixclient).
|
|
# No-op until the operator turns matrix on; until then
|
|
# there's no homeserver to advertise.
|
|
lib.optionalAttrs (matrixCfg.enable && hyperhiveDomain != null) {
|
|
"= /.well-known/matrix/client" = {
|
|
extraConfig = ''
|
|
default_type application/json;
|
|
add_header Access-Control-Allow-Origin *;
|
|
return 200 '{"m.homeserver":{"base_url":"http://${hyperhiveDomain}:${toString matrixCfg.httpPort}"}}';
|
|
'';
|
|
};
|
|
"= /.well-known/matrix/server" = {
|
|
extraConfig = ''
|
|
default_type application/json;
|
|
return 200 '{"m.server":"${hyperhiveDomain}:${toString matrixCfg.httpPort}"}';
|
|
'';
|
|
};
|
|
}
|
|
// {
|
|
# Everything else proxies to hive-c0re. Upgrade
|
|
# headers stay set so SSE (`/dashboard/stream`,
|
|
# `/events/stream`) + websocket (`/screen/ws`)
|
|
# endpoints keep working transparently.
|
|
"/" = {
|
|
proxyPass = "http://${cfg.upstreamHost}:${toString cfg.upstreamPort}";
|
|
proxyWebsockets = true;
|
|
extraConfig = ''
|
|
proxy_buffering off;
|
|
proxy_read_timeout 1d;
|
|
'';
|
|
};
|
|
};
|
|
};
|
|
};
|
|
};
|
|
};
|
|
|
|
networking.firewall = lib.mkIf cfg.openFirewall {
|
|
allowedTCPPorts = [ cfg.port ];
|
|
};
|
|
|
|
networking.hosts = lib.mkIf (cfg.localHostsEntry && hyperhiveDomain != null) {
|
|
"127.0.0.1" = [ hyperhiveDomain ];
|
|
};
|
|
};
|
|
}
|