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

hive-gateway: serve the swagger-ui theme via nginx alias, not a c0re build hook

Browse source
This commit is contained in:
damocles 2026-08-02 20:19:33 +02:00 • committed by mara
commit de1659d10e
7 changed files with 117 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

1
flake.nix
View file

@ -128,6 +128,7 @@
frontend = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.frontend;
assets = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.assets;
xdgIcons = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.xdg-icons;
swaggerUiTheme = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.swagger-ui-theme;
hyperhiveFlake = lib.mkDefault "${sources.hyperhiveFlakeSource}";
# Narrow docs/ source, threaded as its own meta-flake input
# so doc edits don't re-hash the whole flake source.

21
hive-c0re/swagger-ui-theme/index.html
View file

@ -1,11 +1,16 @@
<!-- HTML for static distribution bundle build -->
<!-- Overrides the vendored Swagger UI's dist/index.html (byte-identical
otherwise) via `SWAGGER_UI_OVERWRITE_FOLDER`. Adds `colors.css`
(same origin as the dashboard — see dashboardProxyLocation in
nix/host-modules/hive-gateway/vhosts.nix — so this resolves the
operator's live stylix theme, not a frozen copy) and
hyperhive-theme.css, which consumes its `--baseNN` vars. See
docs/web-ui/dashboard.md::Dashboard endpoints. -->
<!-- Served by the gateway's nginx (an exact-match `location = /api/docs/`
alias straight to this file's nix store path — see
nix/host-modules/hive-gateway/vhosts.nix's swaggerThemeLocations),
NOT by hive-c0re: a theme tweak here is a gateway config change,
not a hive-c0re rebuild+restart. Byte-identical to the vendored
Swagger UI's dist/index.html except two added <link>s: `colors.css`
(same origin as the dashboard — so this resolves the operator's
live stylix theme, not a frozen copy) and hyperhive-theme.css,
which consumes its `--baseNN` vars. Every other path here (script
src, other stylesheets, favicons) stays relative and falls through
nginx's `/api/` prefix proxy to hive-c0re's own vendored,
unmodified Swagger UI assets — only this file and
hyperhive-theme.css are intercepted. -->
<!DOCTYPE html>
<html lang="en">
<head>

13
nix/host-modules/hive-c0re/options.nix
View file

@ -65,6 +65,19 @@
processes to their icon.
'';
};
swaggerUiTheme = lib.mkOption {
type = lib.types.package;
defaultText = lib.literalExpression "hyperhive.packages.\${system}.swagger-ui-theme";
description = ''
Swagger UI re-theme static override files (see
`nix/packages/swagger-ui-theme.nix`; output has `index.html` +
`hyperhive-theme.css`). The hive-gateway module `alias`es these
two files straight from the store over `/api/docs/`, so a theme
tweak is a gateway config change — hive-c0re's own vendored
Swagger UI build is untouched. Override to ship a custom theme
(or the vendored default) without a hive-c0re rebuild.
'';
};
hyperhiveFlake = lib.mkOption {
type = lib.types.str;
defaultText = lib.literalMD "the hyperhive flake's own filtered source store path";

7
nix/host-modules/hive-gateway/default.nix
View file

@ -24,6 +24,12 @@ let
# container's).
dashboardDist = "${config.services.hyperhive.c0re.servedFrontend}/dashboard";
# Swagger UI re-theme static override files — nginx `alias`es these
# straight from the store over `/api/docs/`, so a theme tweak ships
# as a gateway config change (see vhosts.nix's `swaggerThemeLocations`
# and nix/packages/swagger-ui-theme.nix).
swaggerUiTheme = config.services.hyperhive.c0re.swaggerUiTheme;
# Self-signed TLS is the implicit floor: when neither an operator cert
# (`tls.certDir`) nor ACME (`tls.acme.enable`) is configured, the gateway
# generates + serves a hive-CA-signed leaf (see hive-tls.nix). There is no
@ -261,6 +267,7 @@ in
matrixCfg
hyperhiveDomain
dashboardDist
swaggerUiTheme
tlsCert
tlsKey
;

29
nix/host-modules/hive-gateway/vhosts.nix
View file

@ -11,6 +11,7 @@
matrixCfg,
hyperhiveDomain,
dashboardDist,
swaggerUiTheme, # nix/packages/swagger-ui-theme.nix: has index.html + hyperhive-theme.css
errorPages, # ./error-pages.nix: { notFound, unreachable, unauthorized }
tlsCert,
tlsKey,
@ -304,6 +305,33 @@ let
proxyPass = "http://${cfg.upstreamHost}:${toString cfg.upstreamPort}";
};
};
# Swagger UI re-theme: exact-match locations `alias`ed straight to
# `swaggerUiTheme`'s store path, nginx-served with no involvement
# from hive-c0re at all. `=` locations win over the `/api/` prefix
# block above regardless of declaration order (nginx's own location-
# matching precedence — exact match beats longest-prefix), so this
# doesn't need to be declared before it. Every OTHER Swagger UI asset
# (bundle.js, openapi.json, favicons, the *vendored* index.html c0re
# would otherwise serve) still falls through `/api/` to c0re's own
# embedded `utoipa-swagger-ui` dist unchanged — only these two exact
# paths are intercepted. A theme tweak is therefore a change to
# `hive-c0re/swagger-ui-theme/` + a gateway container activation, not
# a hive-c0re rebuild+restart. See nix/packages/swagger-ui-theme.nix.
swaggerThemeLocations = {
"= /api/docs/" = {
extraConfig = ''
alias ${swaggerUiTheme}/index.html;
${dashboardAuth}
'';
};
"= /api/docs/hyperhive-theme.css" = {
extraConfig = ''
alias ${swaggerUiTheme}/hyperhive-theme.css;
${dashboardAuth}
'';
};
};
in
{
# Accept-header SPA map for the matrix GUI only (see docs/gateway.md
@ -325,6 +353,7 @@ in
// wellKnownLocations
// agentLocations
// dashboardProxyLocation
// swaggerThemeLocations
// lib.optionalAttrs cfg.auth.enable {
# Internal-only target for the 401 error_page above.
# `internal` prevents direct client access; `alias` serves

5
nix/packages/default.nix
View file

@ -158,6 +158,11 @@ in
xdg-icons = pkgs.callPackage ./hive-xdg-icons.nix {
hyperhiveSvg = ../../branding/hyperhive.svg;
};
# Swagger UI re-theme static override files — see
# ./swagger-ui-theme.nix. The gateway `alias`es these straight from
# the store; a theme tweak is a gateway config change, not a
# hive-c0re rebuild.
swagger-ui-theme = pkgs.callPackage ./swagger-ui-theme.nix { };
# Pre-built per-container system closures. Exposed as packages
# so operators can `nix build .#agent-base-toplevel` (or wire

49
nix/packages/swagger-ui-theme.nix Normal file
View file

@ -0,0 +1,49 @@
{
stdenv,
}:
# The hand-authored Swagger UI re-theme files (`hive-c0re/swagger-ui-
# theme/`), shipped as a standalone derivation so the gateway can
# `alias` them straight from the nix store instead of hive-c0re's own
# build serving them — see nix/host-modules/hive-gateway/vhosts.nix's
# `swaggerThemeLocations`. This is what lets a CSS tweak ship as a
# gateway config change (activate the gateway container) rather than a
# hive-c0re rebuild+restart: the two files nginx exact-matches
# (`/api/docs/` and `/api/docs/hyperhive-theme.css`) come from here;
# every other Swagger UI asset (bundle.js, openapi.json, favicons, …)
# still falls through the existing `/api/` prefix proxy to hive-c0re's
# own vendored (unthemed) `utoipa-swagger-ui` embed, unchanged.
#
# Pure data: copied verbatim, no build step.
#
# Output layout:
# $out/index.html — themed index.html Swagger UI page
# $out/hyperhive-theme.css — the re-theme, consumes --baseNN vars
# from the dashboard's own colors.css
# (loaded via an absolute /static/
# colors.css <link>, same origin)
stdenv.mkDerivation {
pname = "hyperhive-swagger-ui-theme";
version = "0.1.0";
# Narrow src keeps this derivation's input hash decoupled from the
# rest of the tree — a theme tweak only re-hashes this.
src = ../../hive-c0re/swagger-ui-theme;
dontBuild = true;
dontConfigure = true;
installPhase = ''
runHook preInstall
mkdir -p $out
cp -r ./* $out/
runHook postInstall
'';
dontFixup = true;
meta = {
description = "hyperhive Swagger UI Catppuccin Mocha re-theme (static override files)";
homepage = "https://forge.darkest.space/hyperhive/hyperhive";
};
}