Ilia Denisov
7cac910de4
Add the mail, notifications, and broadcast pages over the mail, notification,
and diplomail services (no new business logic), completing the operator console.
- GET /_gm/mail deliveries (paginated) + dead-letters
- GET /_gm/mail/deliveries/{id} delivery detail + attempts
- POST /_gm/mail/deliveries/{id}/resend re-enqueue a non-sent delivery
- GET /_gm/notifications notifications + dead-letters + malformed
- GET/POST /_gm/broadcast multi-game admin diplomatic broadcast
Console depends on MailAdmin / NotificationAdmin / DiplomailAdmin interfaces
(satisfied by the concrete services); pages render in tests without a database.
Delivery detail and dead-letters live under /_gm/mail/deliveries/* and
/_gm/mail/... static segments to avoid a param/static route conflict. Resend
and broadcast flow through the CSRF guard.
Tests: mail page, delivery detail (+ not-found), resend (+ bad-CSRF),
notifications overview, broadcast form + send (input assertions) + bad game
ids, and unavailable. Plus an integration test that drives /_gm end to end
through the real gateway → backend (401 challenge + authenticated dashboard).
Docs: backend/docs/admin-console.md page inventory completed.
129 lines
8.2 KiB
Markdown
129 lines
8.2 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.
|
|
|
|
## Pages
|
|
|
|
| Path | Method | Purpose |
|
|
| --------------------------------- | -------- | -------------------------------------------------------------- |
|
|
| `/_gm`, `/_gm/` | GET | Dashboard: health, runtime/mail/notification status, queues. |
|
|
| `/_gm/assets/*` | GET | Embedded stylesheet. |
|
|
| `/_gm/users` | GET | Paginated account list. |
|
|
| `/_gm/users/{id}` | GET | Account detail: profile, entitlement, active sanctions. |
|
|
| `/_gm/users/{id}/block` | POST | Apply a permanent block (reason required). |
|
|
| `/_gm/users/{id}/entitlement` | POST | Set the entitlement tier. |
|
|
| `/_gm/users/{id}/soft-delete` | POST | Soft-delete the account (cascades). |
|
|
| `/_gm/games` | GET/POST | Paginated game list; POST creates a public game. |
|
|
| `/_gm/games/{id}` | GET | Game detail with the runtime snapshot. |
|
|
| `/_gm/games/{id}/force-start` | POST | Force-start the game. |
|
|
| `/_gm/games/{id}/force-stop` | POST | Force-stop the game. |
|
|
| `/_gm/games/{id}/ban-member` | POST | Ban a member (user id + reason). |
|
|
| `/_gm/games/{id}/runtime/restart` | POST | Restart the engine container. |
|
|
| `/_gm/games/{id}/runtime/patch` | POST | Patch the runtime to a target version. |
|
|
| `/_gm/games/{id}/runtime/force-next-turn` | POST | Force the next turn now. |
|
|
| `/_gm/engine-versions` | GET/POST | Version registry; POST registers a version. |
|
|
| `/_gm/engine-versions/{ver}/disable` | POST | Disable a registered version. |
|
|
| `/_gm/operators` | GET/POST | Admin-account list; POST creates an operator. |
|
|
| `/_gm/operators/{user}/disable` | POST | Disable an operator. |
|
|
| `/_gm/operators/{user}/enable` | POST | Re-enable an operator. |
|
|
| `/_gm/operators/{user}/reset-password` | POST | Reset an operator's password. |
|
|
| `/_gm/mail` | GET | Mail deliveries (paginated) + a dead-letter snapshot. |
|
|
| `/_gm/mail/deliveries/{id}` | GET | Delivery detail with its attempts. |
|
|
| `/_gm/mail/deliveries/{id}/resend`| POST | Re-enqueue a non-sent delivery. |
|
|
| `/_gm/notifications` | GET | Notifications, dead-letters, and malformed intents overview. |
|
|
| `/_gm/broadcast` | GET/POST | Admin multi-game diplomatic broadcast. |
|
|
|
|
Each page reuses the same service layer as the corresponding `/api/v1/admin/*`
|
|
JSON endpoint; the console adds no business logic. Collection-mutating POSTs are
|
|
mounted on the collection path (`POST /_gm/games`, `POST /_gm/engine-versions`)
|
|
so a static action segment never collides with a path parameter in the gin
|
|
router. Unblocking a user is not yet available because the JSON admin API
|
|
exposes no remove-sanction endpoint.
|
|
|
|
## 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. |
|