Files
OKF_CV_Website/architecture/gateway.md
T
Noel Sabia 3636053a35 docs(okf): replace Cloudflare Tunnel with own nginx reverse proxy
direction change: own nginx proxy (Terraform-installed, certbot TLS) is the only public entry; add own-proxy decision; update system, gateway SSE notes, server budget and accepted-downtime docs
2026-10-14 21:54:33 +02:00

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".

nginx proxy and SSE

  • Terminate SSE at the gateway; nginx proxies it per-connection with buffering off (proxy_buffering off).
  • Send a comment line (: ping) every 30 seconds so idle connections are not closed through nginx's default read timeout.

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.