Files
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

71 lines
2.6 KiB
Markdown

---
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` |
| 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
```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".
# 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](/decisions/own-tracker.md).
```sql
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](/architecture/server-budget.md).
# RBAC
ServiceAccount `gateway` in `cv`, Role with `get/list/watch` on `pods`,
`events` and `jobs`. No create, delete or patch.