chore: initial commit of Go API gateway

Baseline for the Kong replacement on api.riotpiao.com. Brings the working tree under version control for the first time: gateway source, the task board that drives the agent runs, test fixtures, and K8s manifests. Anchor the gateway ignore rule to the repo root. Unanchored, "gateway" also matched the cmd/gateway/ source directory, so the program entrypoint was excluded from every commit. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
2026-08-19 20:54:34 -07:00
commit 058f11cf2b
109 changed files with 8992 additions and 0 deletions
@@ -0,0 +1,25 @@
+# 0.3 — Health endpoints (GREEN)
+
+Phase: 0 — Foundations
+Stage: GREEN
+Depends on: [0.2](0.2-route-configuration.md)
+
+- [x] `GET /healthz` returns `200` whenever the process is alive
+- [x] `GET /healthz` contacts no upstream and performs no network I/O
+- [x] `GET /readyz` returns `200` only when configuration is valid and, if auth is enabled, JWKS has been fetched at least once
+- [x] `GET /readyz` returns a non-`2xx` status while configuration is invalid or JWKS has never been fetched
+- [x] Neither endpoint requires authentication, even when the auth flag is on
+- [x] Neither path is proxied to any upstream, and neither can be shadowed by a configured route
+
+`/healthz` backs the liveness probe, so it must stay cheap and must not fail because
+an upstream is down — restarting the gateway does not fix a sick vLLM pod. `/readyz`
+backs the readiness probe and is allowed to fail, taking the pod out of the nginx
+endpoint pool until it can actually serve.
+
+## Verify
+
+```bash
+go test ./internal/server/... -run TestHealthEndpoints -v
+# expected: passes — /healthz is 200 with upstreams unreachable; /readyz is non-2xx
+# before first JWKS fetch and 200 after; both answer with no Authorization header
+```