Ilia Denisov
cf34710b4f
Tests · Go / test (push) Successful in 1m56s
Add the operator console's user-administration pages over the existing
*user.Service (no new business logic).
- GET /_gm/users paginated account list
- GET /_gm/users/{id} account detail: profile, entitlement, sanctions
- POST /_gm/users/{id}/block apply permanent_block (reason required)
- POST /_gm/users/{id}/entitlement set the entitlement tier
- POST /_gm/users/{id}/soft-delete soft-delete the account (cascades)
The console depends on a UserAdmin interface (satisfied by *user.Service) so the
pages render in tests without a database. All writes flow through the CSRF
guard, carry the operator as the audit actor, and answer with a 303 redirect;
a generic message page handles not-found, validation, and failure notices.
Unblock is intentionally absent — the admin API exposes no remove-sanction
endpoint.
Tests: list/detail render, not-found, block (with actor/scope/reason
assertions), missing-reason 400, bad-CSRF 403, entitlement, soft-delete
redirect, and the service-unavailable path.
Docs: backend/docs/admin-console.md gains the page inventory.
107 lines
5.9 KiB
Markdown
107 lines
5.9 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). |
|
|
|
|
Each page reuses the same service layer as the corresponding `/api/v1/admin/*`
|
|
JSON endpoint; the console adds no business logic. 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. |
|