Files
OKF_CV_Website/architecture/gateway.md
T
Noel SabiaandClaude Opus 5.5 64fef83314 docs(okf): move bundle to repo root and retire brief
The brief is fully captured in the bundle; it stays in git history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 14:22:03 +02:00

1.7 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

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.

RBAC

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