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]>
This commit is contained in:
Story Crater Bot
+151
@@ -0,0 +1,151 @@
|
||||
# Task board — homelab-frontend
|
||||
|
||||
The Go API gateway replacing Kong OSS on `api.riotpiao.com`.
|
||||
|
||||
Contract: [REQUIREMENTS.md](../REQUIREMENTS.md).
|
||||
Why: [ADR-0001](../docs/adr/ADR-0001-retire-kong-for-go-gateway.md).
|
||||
What Kong does today and the cutover order: [docs/MIGRATION-kong.md](../docs/MIGRATION-kong.md).
|
||||
|
||||
## Rules carried from the ADR and requirements
|
||||
|
||||
- G1 — ingress-nginx owns TLS. The gateway never terminates TLS.
|
||||
- G2 — the gateway holds no Kubernetes credentials. Config comes from git, not a CRD.
|
||||
- G3 — public surfaces use standard protocol shapes. If an OpenAI SDK can't call it unmodified, it's wrong.
|
||||
- G4 — streaming is unbuffered, and a client disconnect cancels the upstream.
|
||||
- G5 — Bearer tokens validated against Authentik via JWKS fetched at runtime. No pinned keys.
|
||||
- G6 — every timeout, body cap and concurrency limit is explicit in config.
|
||||
- G7 — deployment flows through git and Argo. No `kubectl apply`, no `helm upgrade`.
|
||||
|
||||
## How to work these
|
||||
|
||||
Each task is self-contained — it states what must be true, not how to build it.
|
||||
Reason out the implementation; the acceptance criteria are the contract.
|
||||
|
||||
Stages follow red-green-refactor. A task marked RED means the test comes first and
|
||||
must fail for the right reason before any implementation exists.
|
||||
|
||||
**Verification means asserting on a real HTTP response** — status, headers, body.
|
||||
"It compiles" and "it starts" are not verification. Every task that touches an API
|
||||
surface has a `## Verify` block with a runnable command.
|
||||
|
||||
Kong is serving live traffic throughout phases 0–5. Nothing in those phases may
|
||||
change cluster state.
|
||||
|
||||
## Phase 0 — Foundations
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [0.1](0.1-module-and-entrypoint.md) | Go module, entrypoint, graceful shutdown |
|
||||
| [0.2](0.2-route-configuration.md) | Declarative route/upstream config from git, fail-loud validation |
|
||||
| [0.3](0.3-health-endpoints.md) | `/healthz` and `/readyz` |
|
||||
| [0.4](0.4-local-dev-harness.md) | Run with no cluster, no kubeconfig, no credentials — stub upstreams |
|
||||
| [0.5](0.5-structured-logging.md) | Structured logs, no secrets or bodies |
|
||||
| [0.6](0.6-ci-pipeline.md) | CI: build, vet, test, `govulncheck` |
|
||||
|
||||
## Phase 1 — Proxy core
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [1.1](1.1-reverse-proxy.md) | Reverse proxy to a configured upstream, connection reuse |
|
||||
| [1.2](1.2-streaming-passthrough.md) | SSE and chunked responses pass through unbuffered |
|
||||
| [1.3](1.3-disconnect-propagation.md) | Client disconnect cancels the upstream request |
|
||||
| [1.4](1.4-per-route-timeouts.md) | Explicit connect/read/write timeouts per route |
|
||||
| [1.5](1.5-header-hygiene.md) | Hop-by-hop stripping, `X-Forwarded-*` from nginx |
|
||||
| [1.6](1.6-websocket-upgrade.md) | WebSocket upgrade — `agent-pod/console` needs it |
|
||||
| [1.7](1.7-body-size-caps.md) | Per-route request body limits |
|
||||
|
||||
## Phase 2 — LLM surfaces (`/v1/*` and `/llm/*`)
|
||||
|
||||
Two protocol dialects over the same models and the same slot controller. Wire
|
||||
formats are documented in [docs/API-llm.md](../docs/API-llm.md).
|
||||
|
||||
### OpenAI dialect — `/v1/*`
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [2.1](2.1-model-registry.md) | Model → upstream map from config |
|
||||
| [2.2](2.2-body-based-dispatch.md) | `POST /v1/chat/completions` routes on the body's `model` — the reason this project exists |
|
||||
| [2.3](2.3-unknown-model-errors.md) | Unknown/missing model → RFC 9457 problem+json listing valid values |
|
||||
| [2.4](2.4-legacy-path-aliases.md) | Keep `/v1/{reasoning,ornith,qwen}/chat/completions` working during cutover |
|
||||
| [2.5](2.5-models-endpoint.md) | `GET /v1/models` derived from config, never hardcoded |
|
||||
| [2.6](2.6-embeddings-passthrough.md) | `POST /v1/embeddings` — no rewrite needed |
|
||||
| [2.7](2.7-rerank-rewrite.md) | `POST /v1/rerank` → upstream `/rerank` |
|
||||
| [2.8](2.8-kong-parity-test.md) | Gateway and Kong return equivalent responses for every migrated route |
|
||||
|
||||
### Anthropic dialect — `/llm/*`
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [2.9](2.9-canonical-request-model.md) | Dialect-neutral internal request both surfaces translate into |
|
||||
| [2.10](2.10-anthropic-request-translation.md) | `POST /llm/v1/messages` request → canonical; `system`, blocks, required `max_tokens` |
|
||||
| [2.11](2.11-anthropic-response-translation.md) | Upstream response → Messages shape; `reasoning_content` becomes a `thinking` block |
|
||||
| [2.12](2.12-anthropic-sse-state-machine.md) | Named-event SSE with block indices — the hardest task in the phase |
|
||||
| [2.13](2.13-anthropic-error-shape.md) | Anthropic error shape, not RFC 9457 — same rejection, two renderings |
|
||||
| [2.14](2.14-queue-position-event.md) | Custom `event: queue` before `message_start` — deliberate non-standard extension |
|
||||
| [2.15](2.15-dialect-scope-boundary.md) | Enforce what is deliberately unimplemented: tools, images, caching, batch |
|
||||
|
||||
## Phase 3 — Authentication (Authentik)
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [3.1](3.1-jwks-fetch-and-rotation.md) | Fetch and cache Authentik JWKS, handle rotation without a runbook |
|
||||
| [3.2](3.2-bearer-validation.md) | Validate `Authorization: Bearer` — the thing Kong OSS could not do |
|
||||
| [3.3](3.3-authentik-service-account.md) | Service account + `client_credentials` provider in Authentik |
|
||||
| [3.4](3.4-flag-gated-rollout.md) | Auth defaults off; enabling it is deliberate |
|
||||
| [3.5](3.5-capability-authorization.md) | A queue token must not invoke a GPU |
|
||||
| [3.6](3.6-pi-client-migration.md) | Move pi off the `apikey` header onto Bearer |
|
||||
|
||||
## Phase 4 — Limits and budgets
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [4.1](4.1-gpu-slot-semaphore.md) | Cap concurrent `reasoning` requests below 8 slots, bounded queue |
|
||||
| [4.2](4.2-per-caller-budgets.md) | Request budget per identified caller per window |
|
||||
| [4.3](4.3-problem-json-errors.md) | RFC 9457 rejections with `Retry-After` |
|
||||
|
||||
## Phase 5 — Observability
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [5.1](5.1-prometheus-parity.md) | Match the retiring Kong plugin: rate, latency, status, bandwidth, upstream health |
|
||||
| [5.2](5.2-gateway-metrics.md) | In-flight per upstream, queue depth, slot occupancy, rejections by reason |
|
||||
| [5.3](5.3-servicemonitor.md) | ServiceMonitor so Prometheus scrapes it |
|
||||
|
||||
## Phase 6 — Deploy and cutover
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [6.1](6.1-hardened-image.md) | Distroless, non-root, read-only rootfs, no shell, SHA tags |
|
||||
| [6.2](6.2-kubernetes-manifests.md) | Deployment, Service, NetworkPolicy |
|
||||
| [6.3](6.3-argocd-application.md) | Argo Application in the homelab-root GitOps repo |
|
||||
| [6.4](6.4-deploy-alongside-kong.md) | Deploy unexposed, verify in-cluster against the real upstreams |
|
||||
| [6.5](6.5-cutover.md) | Repoint the nginx Ingress from `kong-proxy` to the gateway — reversible |
|
||||
| [6.6](6.6-kong-teardown.md) | Delete kong Ingresses, plugins, Helm release. **Irreversible** |
|
||||
|
||||
## Phase 7 — Additional capability prefixes
|
||||
|
||||
Deliberately after cutover. Each is additive and must not disturb `/v1/*`.
|
||||
|
||||
| Task | Description |
|
||||
|---|---|
|
||||
| [7.1](7.1-cluster-prefix-atlas.md) | `/cluster/*` → atlas (`riotpiao-backend`) |
|
||||
| [7.2](7.2-sqs-prefix.md) | `/sqs/*` → kmsvc management-service, Kafka |
|
||||
| [7.3](7.3-workflow-prefix.md) | `/workflow/*` → Temporal |
|
||||
| [7.4](7.4-db-prefix.md) | `/db/*` → CloudNativePG, MinIO, monitoring reads |
|
||||
|
||||
## Progress
|
||||
|
||||
Status as of 2026-08-19: scaffolded, nothing implemented. Kong is still serving all
|
||||
live traffic on `api.riotpiao.com`, currently **unauthenticated**.
|
||||
|
||||
50 tasks. Suggested first slice: 0.1 → 0.2 → 0.4 → 1.1 → 1.2 → 2.1 → 2.2. That
|
||||
reaches the single capability Kong could not provide — body-based model dispatch —
|
||||
with a verification loop that needs no cluster.
|
||||
|
||||
The Anthropic dialect (2.9-2.15) can be worked in parallel with the OpenAI dialect
|
||||
once 2.9 lands, since both translate into the same canonical request. Do not build
|
||||
either surface's admission control separately — 4.1 owns it for both.
|
||||
|
||||
Decided 2026-08-19: authentication is `Authorization: Bearer` on **both** surfaces.
|
||||
A stock Anthropic SDK sends `x-api-key` and will get a 401; that is accepted because
|
||||
the `/llm` client is first-party. The 401 must say so rather than being bare.
|
||||
Reference in New Issue
Block a user