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,31 @@
+# 2.8 — Kong parity test (RED)
+
+Phase: 2 — LLM surface
+Stage: RED
+Depends on: [2.2](2.2-body-based-dispatch.md), [2.4](2.4-legacy-path-aliases.md), [2.5](2.5-models-endpoint.md), [2.6](2.6-embeddings-passthrough.md), [2.7](2.7-rerank-rewrite.md)
+
+- [ ] A repeatable check issues the same request to Kong and to the gateway and compares the real HTTP responses: status, meaningful headers, and body
+- [ ] It covers every migrated route: `GET /v1/models`, the three `/v1/{reasoning,ornith,qwen}/chat/completions` aliases, `POST /v1/embeddings`, `POST /v1/rerank`, and the new canonical `POST /v1/chat/completions`
+- [ ] It covers a streaming chat request and asserts equivalent chunk sequencing, not just an equal final concatenation
+- [ ] It covers a mid-stream client disconnect and asserts the upstream request is cancelled rather than left running
+- [ ] It asserts `reasoning_content` and `content` are both present and untouched for the `reasoning` model
+- [ ] Fields that legitimately differ per request — ids, timestamps, generated text — are normalised before comparison, and the normalisation is explicit rather than a blanket ignore
+- [ ] Any difference fails the check loudly and names the route and the field
+- [ ] `GET /v1/models` is expected to differ from Kong's static list only where the gateway's derived list is more accurate; that difference is recorded deliberately, not normalised away
+- [ ] The check passes before cutover ([6.5](6.5-cutover.md)) and blocks it if it does not
+
+Kong is serving live traffic while this runs. The check reads only; it changes no
+cluster state. Eleven ReplicaSets exist on the Kong Deployment, so re-run this
+immediately before cutover rather than trusting an old result.
+
+## Verify
+
+```bash
+./parity --kong https://api.riotpiao.com --gateway http://homelab-frontend.api.svc.cluster.local
+# expected: exit 0, one PASS line per route, explicit report of the /v1/models difference
+
+# spot-check by hand, same body to both
+curl -s -o /dev/null -w 'kong %{http_code}\n' https://api.riotpiao.com/v1/rerank \
+  -H 'content-type: application/json' -d '{"model":"BAAI/bge-reranker-base","query":"q","texts":["a"]}'
+# expected: identical status from both endpoints
+```