control

Overview ¶

OIDC login for the control plane: GET /auth/oidc/start redirects to the configured provider's hosted login; GET /auth/oidc/callback exchanges the authorization code and mints the same scs session password login mints, so everything downstream of login is identical for both paths.

These are raw chi handlers, not huma operations: they speak browser redirects and cookies, not JSON.

The provider is generic OIDC (issuer discovery via sdk/oauth). Per-dance state + PKCE verifier travel in a short-lived HttpOnly SameSite=Lax cookie rather than the session: the callback arrives as a cross-site top-level navigation, which a SameSite=Strict session cookie does not accompany.

GET /catalog/graph — the whole catalog as a minimal graph for the admin model picker.

Returns providers, hosts, and models (with their host bindings) in one call so the UI can render and cross-link them without three separate list fetches + client-side flattening. Only the fields the picker and the policy model view actually read are included — identity (id/name/ displayName), the enabled flag, host icon path, the featured flag (from the catalog's `labels.featured`), per-model deprecation, capabilities, context window, the pointer (the upstream wire name the bare model name resolves to at request time), and the (hostId, adapter, enabled) bindings. Heavy spec (full snapshot list, pricing refs, modalities, …) is deliberately omitted.

Reads the in-memory snapshot via the same index as /catalog/resolve, so it returns exactly what the data plane can route to right now: disabled providers/hosts/models are already absent, and disabled bindings are pruned here. The picker only offers routable targets; full-list / detail views use the CRUD APIs (PG), which show disabled rows.

GET /config.json — the public, unauthenticated runtime config the embedded admin UI fetches once at boot, same-origin (it is served from the control listener, which is also where the SPA is served from). Modelled on the OIDC `/.well-known/openid-configuration` discovery pattern.

Why runtime, not build-time: relay-ui is built once into a generic tarball and go:embed'd into the binary, so VITE_* build-time env can't encode a specific deployment's URLs/flags. The UI learns them here at boot instead.

WORLD-READABLE — public values only. Never add secrets (keys, DSNs to private services, internal hostnames). The body is rendered once at registration from static process env, so it is effectively a constant for the process lifetime.

Package control is the admin-plane HTTP API: /auth/*, CRUD across the eight catalog kinds, /version, /master-key/*, /reload.

Mount(r, deps) wires huma+chi onto an existing chi router and returns the huma.API. main.go constructs Deps and calls Mount.

GET /debug/snapshot — render the current data-plane snapshot for operator inspection. The snapshot is what the hot path actually sees; diffing it against PG (via the regular admin list endpoints) is the fastest way to spot what sanitize dropped.

detail=counts (default): per-kind row counts + per-policy reverse-join

sizes. Tiny payload, scans nothing.

detail=full: every entity in stable slug order, sanitized

spec included. Bigger; admin-only, no SLO.

list_filter.go wires the pure pkg/filter engine into the generic CRUD list handler. huma binds typed structs, but the filter allowlist is per-resource dynamic, so a small middleware stashes the raw url.Values on the request context and the list resolver reads them back to feed filterSchema.Parse. See registerKind in crud.go and the per-resource schemas in list_schemas.go.

list_schemas.go declares the per-resource filter allowlists consumed by the generic list handler (registerKind). Each schema is the single source of truth for that resource's filterable/sortable params: the accessors are typed closures, so renaming an underlying spec field is a compile error here. The query-param name, the allowlist entry, and the match logic all derive from one Field literal.

Covers all eight catalog kinds. Time filters (created/updated, release/ deprecation dates) read Metadata timestamps + spec date strings; ?label= k=v works on every kind via the Labels hook. The host-key circuit-breaker state filter (?health=) is intentionally absent here — it needs a snapshot+kv join the pure store-slice engine can't express.

Logs read-side endpoints: the full per-request lifecycle view that drives the frontend Logs page. A "log" is what happened on a request (routing, status, timing, tokens, errors, identity) — i.e. the full usage.Event — with the captured request/response bodies attached when payload logging was opted in for that request ("(not logged)" otherwise).

GET /logs                full lifecycle records, newest first, filterable
GET /logs/{request_id}   one record + its captured bodies (if any)

Distinction from /usage: /usage is the narrow metrics projection (billing); /logs is the full record + optional body. Both read the same log event stream via usagelog.Reader; the body joins by request_id via payload.Reader.

overlay.go binds the catalog-overlay subresource:

GET    /models/by-id/{id}/overlay   patch + template + effective + quarantine state
PUT    /models/by-id/{id}/overlay   set/replace the user's sparse patch
DELETE /models/by-id/{id}/overlay   factory reset (template resumes verbatim)

The overlay is an explicitly user-managed patch document — PUT replaces the whole patch. Writes hit PG only; the table's NOTIFY trigger fans the merge out to every pod's snapshot (~1s), same as generic CRUD.

Policy model-grant normalization + enabled-resolution guard.

At policy create/update the catalog-ref strings in Spec.Models (and each RLBinding's Models) are:

1. slugified to canonical form — operators may paste real-world names ("openai/GPT-4o", "anthropic/claude-3.5") and they're rewritten to the stored slug form ("openai/gpt-4o", "anthropic/claude-3-5"). This keeps PG, the data-plane snapshot, and the picker agreeing on one string.
2. resolved against the catalog and required to match at least one *enabled* binding (model enabled, host enabled, binding enabled). Host-only "@host" refs only require the host to exist + be enabled — they grant every present and future binding on that host.

Refs that resolve to nothing enabled are rejected with 400. This is the cross-entity check the per-row policy.Validate() (grammar only, no catalog access) can't perform. Host-key / relay-key existence is deliberately NOT checked here — the inference path handles those at request time.

Attach / detach RelayKey ↔ Policy from the policy side. The authoritative field is RelayKey.Spec.PolicyID (1:N — one policy per key, many keys per policy); these endpoints mutate it so the policy form can manage its key roster without round-tripping through the relay-key form.

POST   /policies/by-id/{id}/relay-keys/{relayKeyId}   — attach
DELETE /policies/by-id/{id}/relay-keys/{relayKeyId}   — detach

Attach overwrites any existing PolicyID on the relay key (no confirmation): moving a key from policy A to policy B is the common case. Detach succeeds when the key currently points at this policy; mismatched detach returns 409 to surface the drift instead of silently no-op'ing.

GET /{kind}/by-id/{id}/references — generic reverse-ref lookup.

Returns every PG row that references the target entity. Used by the admin UI for blast-radius confirmation dialogs ("deleting this rate limit will affect N policies") and for inline "in use by" lists.

Walks the relevant stores per kind; admin-only, no SLO. Indices come later if scan time matters. Reading PG (not the catalog snapshot) so disabled / soft-dropped refs are still visible — they exist in PG even when the data plane has filtered them out.

Custom POST /relay-keys: generates the bearer plaintext server-side via relaykey.Generate, persists only the hash + prefix, and returns the plaintext exactly once on the create response. The generic CRUD POST in registerKind is skipped for this kind (skipCreate=true) so callers can't sneak a precomputed keyHash through.

POST /relay-keys/by-id/{id}/rotate — mint a fresh bearer plaintext for an existing relay-key, replacing KeyHash + Prefix in place. All other fields (policy binding, flags, slug) survive, so customers swap the secret without re-wiring anything. The old plaintext stops authenticating as soon as the snapshot picks up the NOTIFY (~1s fleet-wide). Like create, the new plaintext is returned exactly once.

subresources.go binds the catalogview read projections to chi/huma as resource-navigation endpoints — "API UX":

GET /models/{ref}/hosts     hosts serving this model (+ binding + pricing)
GET /models/{ref}/pricing   pricing per host for this model
GET /models/{ref}/policies  policies granting this model (+ per-model limits)
GET /hosts/{ref}/models      models this host serves (+ binding + pricing)
GET /hosts/{ref}/keys        upstream credentials this host owns (secret-free)
GET /hosts/{ref}/policies    host-tier serving policies this host owns
GET /policies/{ref}/models       models this policy grants (+ per-model limits)
GET /policies/{ref}/hosts        hosts this policy reaches (+ host-keys)
GET /policies/{ref}/rate-limits  rate-limit rule sets this policy references

All composition lives in app/catalogview (PG-backed, full state incl. disabled rows). These handlers are thin: build the Service from the stores, call the projection, return its rows. {ref} is a slug or UUID id.

Usage read-side endpoints: surface the JSONL stream the post-flight observer writes via filtered + aggregated queries. Backed by a usagelog.Reader, so the store can swap (file today, ClickHouse later) without touching this layer.

GET /usage/events    raw events, newest first, filterable
GET /usage/summary   per-group aggregates over the filtered set