Files
OKF_CV_Website/architecture/gateway.md
T
Noel Sabia f0a9d58cff docs(okf): switch reverse proxy to Caddy across bundle
own-proxy decision, terraform provisioner, system diagram, gateway SSE notes, server-budget comment and roadmap 0.4.0 now use Caddy with ACME-managed TLS instead of nginx plus certbot
2026-10-15 14:44:49 +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".

Caddy proxy and SSE

  • Terminate SSE at the gateway; Caddy proxies it per-connection with buffering off (flush_interval -1).
  • Send a comment line (: ping) every 30 seconds so idle connections are not closed through the proxy'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.