Ilia Denisov
27916bbe61
Tests · Go / test (push) Successful in 2m0s
Add the server-rendered operator console at /_gm, exposed publicly through the gateway behind the existing admin_accounts Basic Auth. Backend: - new internal/adminconsole package (html/template Renderer, stateless HMAC CSRF signer, embedded stylesheet) - /_gm route group reusing basicauth.Middleware(admin.Service) + a CSRF guard (per-operator token + same-origin check); dashboard landing page - BACKEND_ADMIN_CONSOLE_CSRF_KEY config (per-process random fallback) Gateway: - new "admin" public route class (per-IP rate limit, body + GET/HEAD/POST method limits) classifying /_gm traffic - reverse proxy to the backend /_gm surface, preserving Host and relaying the backend 401 Basic Auth challenge; 502 when the backend is unreachable - GATEWAY_PUBLIC_HTTP_ANTI_ABUSE_ADMIN_* config dev-deploy: - Caddy routes /_gm/* to the gateway - bootstrap admin + stable CSRF key; enable Prometheus /metrics exporters on backend and gateway (forward-compat for a future Prometheus/Grafana stack) Docs: ARCHITECTURE 14.1/16, FUNCTIONAL 10.2.1 (+ru mirror), backend and gateway READMEs, new backend/docs/admin-console.md. Tests: renderer + CSRF unit tests; backend router auth/render/asset/CSRF; gateway classifier, proxy forwarding/Host/401/405/413/429/502.
91 lines
4.6 KiB
Markdown
91 lines
4.6 KiB
Markdown
# Operator console (`/_gm`)
|
|
|
|
The operator console is a server-rendered web UI for the platform's admin
|
|
operations. It is the human-facing counterpart to the JSON admin API under
|
|
`/api/v1/admin/*`: both call the same service layer, but the console renders
|
|
HTML pages an operator drives in a browser, while the JSON API stays internal
|
|
to the deployment for programmatic and test use.
|
|
|
|
## Design choices
|
|
|
|
- **Server-rendered, no client framework.** Pages are rendered with the
|
|
standard library's `html/template`. Navigation is by ordinary links and
|
|
query parameters; every state change is an HTML form `POST` answered with a
|
|
Post/Redirect/Get redirect. There is no build step, no JavaScript framework,
|
|
and no separate asset pipeline — a single embedded stylesheet under
|
|
`/_gm/assets/`.
|
|
- **Reuses the existing admin auth.** The console mounts behind the same
|
|
`basicauth.Middleware(admin.Service)` verifier that gates `/api/v1/admin/*`,
|
|
so there is one credential store (`admin_accounts`, bcrypt-12) and no second
|
|
secret to manage.
|
|
- **Lives in the backend.** The backend owns the admin domain and the data, so
|
|
rendering there lets the console call the service layer directly. The gateway
|
|
stays a thin proxy.
|
|
|
|
## Request path
|
|
|
|
```
|
|
Browser ── /_gm/* ──► edge Caddy ──► gateway (public listener)
|
|
gateway: anti-abuse `admin` class (per-IP rate limit, body + method limits)
|
|
└─► reverse proxy ──► backend /_gm/*
|
|
backend: basicauth.Middleware(admin.Service)
|
|
└─► CSRF guard (state-changing methods)
|
|
└─► console handler ──► admin service layer ──► html/template
|
|
```
|
|
|
|
The gateway preserves the inbound `Host` and relays the backend's `401` Basic
|
|
Auth challenge unchanged, so the browser shows its native credential dialog.
|
|
The gateway adds only the edge anti-abuse layer; authentication and every state
|
|
change are enforced by the backend. The gateway answers `502` when the backend
|
|
is unreachable. See the gateway README "Operator Console Proxy" section for the
|
|
`admin` route-class env vars.
|
|
|
|
## Components (package `internal/adminconsole`)
|
|
|
|
The package is framework-agnostic (no gin) so it unit-tests in isolation:
|
|
|
|
- `Renderer` — parses the embedded layout plus one content page per route and
|
|
renders a named page wrapped in the shared layout. Rendering goes through an
|
|
intermediate buffer, so a template failure never emits a partial document.
|
|
- `CSRF` — issues and verifies the stateless anti-CSRF token: HMAC-SHA256 over
|
|
the authenticated username, keyed by `BACKEND_ADMIN_CONSOLE_CSRF_KEY`. When
|
|
the key is unset a per-process random key is used (secure, but forms reset on
|
|
restart and do not validate across replicas — set a shared key for
|
|
multi-replica deployments).
|
|
- `Assets` — the embedded stylesheet filesystem served under `/_gm/assets/`.
|
|
|
|
The gin glue (route group, Basic Auth, the CSRF guard middleware, the per-page
|
|
handlers) lives in `internal/server/handlers_admin_console.go` and
|
|
`internal/server/router.go` (`registerAdminConsoleRoutes`).
|
|
|
|
## CSRF protection
|
|
|
|
Because the console is sessionless (HTTP Basic Auth, whose credentials the
|
|
browser replays automatically), state-changing requests are double-guarded:
|
|
|
|
1. A stateless per-operator token (`_csrf` form field) that a cross-site page
|
|
cannot read or forge.
|
|
2. A same-origin `Origin`/`Referer` check (when the browser sends one), which
|
|
relies on the gateway preserving the inbound `Host`.
|
|
|
|
Safe methods (`GET`/`HEAD`/`OPTIONS`) pass without a token.
|
|
|
|
## Monitoring
|
|
|
|
The dashboard is the console landing page. It surfaces backend-visible
|
|
operational state — service health, game-runtime status, and queue depths —
|
|
read through the existing service and persistence layers. Richer cross-service
|
|
metrics are out of scope for the console itself: the `/metrics` Prometheus
|
|
exporters on `backend` and `gateway` are wired and enabled in the dev
|
|
deployment so a future Prometheus + Grafana stack can scrape them without code
|
|
changes.
|
|
|
|
## Configuration
|
|
|
|
| Variable | Where | Notes |
|
|
| --------------------------------- | ------- | ------------------------------------------------------------ |
|
|
| `BACKEND_ADMIN_CONSOLE_CSRF_KEY` | backend | CSRF token key; unset → per-process random key. |
|
|
| `BACKEND_ADMIN_BOOTSTRAP_USER` | backend | Bootstrap operator account (shared with the JSON admin API). |
|
|
| `BACKEND_ADMIN_BOOTSTRAP_PASSWORD`| backend | Bootstrap operator password. |
|
|
| `GATEWAY_PUBLIC_HTTP_ANTI_ABUSE_ADMIN_*` | gateway | `admin` route-class rate-limit and body budgets. |
|