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>
This commit is contained in:
1 parent
957a386b58
commit
64fef83314
22 files changed
+37
-153
No files matched your search
@@ -0,0 +1,48 @@
|
||||
---
|
||||
type: Service
|
||||
title: Gateway
|
||||
description: The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
|
||||
tags: [architecture, go, security]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 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
|
||||
|
||||
```json
|
||||
{"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.
|
||||
Reference in new issue
Block a user