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,26 @@
+# 1.1 — Reverse proxy to configured upstreams (GREEN)
+
+Phase: 1 — Proxy core
+Stage: GREEN
+Depends on: [0.2](0.2-route-configuration.md), [0.4](0.4-local-dev-harness.md)
+
+- [ ] A request matching a configured route is proxied to that route's upstream address
+- [ ] The upstream's status code, response headers and body reach the client unmodified
+- [ ] The request method, query string and body reach the upstream unmodified
+- [ ] The route's configured path rewrite is applied to the upstream request path
+- [ ] Connections to upstreams are pooled and reused across requests — a second request to the same upstream does not open a new TCP connection
+- [ ] A request matching no configured route returns `404` and contacts no upstream
+- [ ] An unreachable upstream returns a `5xx` to the client and is logged with the upstream name
+
+Connection reuse is not a micro-optimisation here: the chat upstreams hold long-lived
+streaming responses, and churning connections under that pattern wastes handshakes and
+file descriptors on both ends.
+
+## Verify
+
+```bash
+go test ./internal/proxy/... -run 'TestProxy|TestConnectionReuse' -v
+# expected: passes — stub upstream sees the rewritten path and original body, client
+# sees the stub's exact status/headers/body, and the stub records one accepted
+# connection across two sequential requests
+```