homelab-frontend/tasks/INDEX.md

# 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.