From ac15c68cd28710b49480888a0044f4147e63a17b Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 12 Aug 2026 10:22:06 +0200 Subject: [PATCH] docs(3189): the error-page scope text describes the new shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two claims this branch falsified and left standing, both caught in review: `vhosts.nix`'s `errorPages` param comment enumerated the set (`{ notFound, unreachable, unauthorized }`) and adding a fourth member made the enumeration wrong at the point a reader consults it. `gateway.md` said extending custom error pages beyond the per-agent routes was "a separate follow-up" — while this branch is that follow-up, so the doc contradicted the code sitting next to it. Rewrites the scope rule as the criterion rather than a list, since a list is what went stale: a route earns a page when the default status would point at the wrong component. That covers the per-agent routes and the sso vhost, and explains why forge/matrix/fluffychat still don't qualify — their upstreams being down means what the code says. --- docs/gateway.md | 14 ++++++++++---- nix/host-modules/hive-gateway/vhosts.nix | 2 +- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/gateway.md b/docs/gateway.md index 544296da..b02b9752 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -477,10 +477,16 @@ palette (`#1e1e2e` bg, `#cdd6f4` text, `#cba6f7` heading). No dependencies on the frontend dist — these pages render even when hive-c0re itself is down. -Scope is intentionally narrow: only routes already special-cased in -the nginx config get custom error pages. Other gateway routes -(forge / matrix / fluffychat) get nginx defaults — extending the -custom-error pattern there is a separate follow-up. +Scope is intentionally narrow: a route earns a custom page when the +default status code would point at the wrong component. The per-agent +routes qualify (a 502 there means the harness is restarting, not that +the gateway is broken), and so does `auth.` — a dead authelia +upstream almost always means the user store was never bootstrapped, and +a bare 502 blames the proxy, which is the one part that is working. + +Forge / matrix / fluffychat still get nginx defaults: their upstreams +being down means what the status code says, so a themed page would add +styling and no information. ## HTTP Basic auth diff --git a/nix/host-modules/hive-gateway/vhosts.nix b/nix/host-modules/hive-gateway/vhosts.nix index 297c724f..06eb4482 100644 --- a/nix/host-modules/hive-gateway/vhosts.nix +++ b/nix/host-modules/hive-gateway/vhosts.nix @@ -13,7 +13,7 @@ hyperhiveDomain, dashboardDist, swaggerUiTheme, # nix/packages/swagger-ui-theme.nix: has index.html + hyperhive-theme.css - errorPages, # ./error-pages.nix: { notFound, unreachable, unauthorized } + errorPages, # ./error-pages.nix: { notFound, unreachable, unauthorized, ssoUnavailable } tlsCert, tlsKey, svcCert, # swarm-services leaf, for names the hive CA cannot sign