Files
OKF_CV_Website/architecture/gateway.md
T

2.6 KiB

type, title, description, tags, status, generated
type title description tags status generated
Service Gateway The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
architecture
go
security
stable
by at
claude-code/claude-opus-5-5 2026-10-11T12:15:30Z

Routes

Route Does
GET / and static paths Serves the Nuxt build, embedded with go:embed
GET /api/events SSE stream: full state on connect, then each change
POST /api/fall/{chapter} Allowlist, cooldown, rate limit, then calls the chapter's /fall
every route Counted by the tracker

Reading cluster state

  • v1 polls list pods and list events in cv every 2 seconds and diffs the result. At about 10 pods this is cheap. Upgrade path: a client-go informer.
  • Recovery times come from the pod's Ready condition lastTransitionTime, so they are exact even though polling is not.
  • Dependency: k8s.io/client-go. It authenticates through the in-cluster ServiceAccount.

SSE event shape

{"chapter": "example", "phase": "Running", "ready": true, "restarts": 3, "event": "recovered", "seconds": 4.2}

The same stream feeds the life map and the developer view.

Limits

  • Per-chapter cooldown: a map[string]time.Time behind a mutex. Default 30 seconds.
  • Global limit: golang.org/x/time/rate, for example 1 fall per second with burst 3.
  • Knockdowns are shared state on purpose: every viewer sees "someone just knocked down X".

Cloudflare Tunnel and SSE

  • Send Content-Type: text/event-stream and flush after every message.
  • Send a comment line (: ping) every 30 seconds so idle connections are not closed.

Tracker

Middleware that counts page views, PDF downloads and falls. See decision.

CREATE TABLE counts (day TEXT, event TEXT, n INTEGER, PRIMARY KEY (day, event));
-- event: 'view:/', 'pdf', 'fall:example', ...
INSERT INTO counts VALUES (?, ?, 1) ON CONFLICT DO UPDATE SET n = n + 1;
  • Daily totals only. No IP addresses, no cookies, no personal data.
  • Skip requests whose user agent looks like a bot.
  • SQLite file on a small local-path volume. Deployment strategy Recreate, so two gateway pods never write the file at the same time.
  • Read the numbers with sqlite3 or a small admin route later; no dashboard in v1.

Resources

64Mi memory limit with GOMEMLIMIT=50MiB, 100m CPU. See server budget.

RBAC

ServiceAccount gateway in cv, Role with get/list/watch on pods, events and jobs. No create, delete or patch.