Gateway

The gateway is a Pingora proxy on 127.0.0.1:8000 by default (CHELABASE_GATEWAY_LISTEN takes a list, e.g. 127.0.0.1:8000,[::1]:8000). It routes by host name: the API host serves the APIs, and the Studio, docs, landing and mail hosts are passed through to their apps. The auth host serves nothing (every path is 404): it only names the issuer of member tokens. All API traffic goes through it: the Management API (/v1/*), the login API (/auth/v1/*) and the data API (/data/v1/*). It never reads request bodies.

One declaration per endpointCopy Anchor Link

Every public endpoint is declared once, in the chelabase-routes crate: method, path, owning service, who may call it and which origins may use it from a browser. The gateway routes and applies policy from that list; the owning service builds its axum routes from the same list, so the two cannot drift. The OpenAPI tests also check each document against it (see API generation).

Each request goes through a fixed pipeline: request id, host scope, route, CORS, authentication, internal identity. Nothing is configurable per route except the declared policy.

Management API requestsCopy Anchor Link

Management endpoints require Authorization: Bearer <member access token>, the EdDSA JWT that auth signs at POST /auth/v1/token (see Identity service). The gateway verifies it locally with the member public key (CHELABASE_MEMBER_JWT_PUBLIC_KEY): the algorithm, key id, issuer (derived from CHELABASE_AUTH_HOST and CHELABASE_PUBLIC_SCHEME; see Hosts), audience chelabase-member, claim set and lifetime are all pinned. Without a verify key every bearer is a 401 and the gateway reports itself not ready. It then forwards the request with an internal identity token in the x-chelabase-identity header:

• an EdDSA JWT, valid for 60 seconds, signed for exactly one target service (its aud is orchestrator, auth, rest or realtime);
• the gateway never forwards Authorization, the Chelabase-User header or a client-supplied x-chelabase-identity.

The internal token carries the member's tenant (the member token's tid). The orchestrator trusts only that token (it holds the verify key, CHELABASE_INTERNAL_VERIFY_KEY) and still requires an active membership in that tenant on every request. Calling the orchestrator's port :8081 directly returns 401.

init-secrets (or just workbench up on a workbench stack) creates the gateway's key pair once; it is never overwritten.

Data API requestsCopy Anchor Link

A data API request carries Authorization: Bearer <key>. The gateway:

1. hashes the key (SHA-256) and looks the hash up in a cache (30 seconds; unknown keys are cached for 30 seconds too);
2. on a miss, asks the orchestrator's internal listener for the key's branch, role, project and database allow-list;
3. if the request carries Chelabase-User: <access token> (an app user), verifies that token with the app-user public key and checks that its session is still live (cached 30 seconds). A user token is refused with a secret key (400 user_token_with_secret_key), and the request then runs as authenticated with the user's claims; an invalid, expired or revoked token is a 401, never a fall back to the key's own role;
4. mints an identity token for rest that carries the branch, key id, role, claims, project and database allow-list.

rest enforces the allow-list, because the gateway never reads bodies. A revoked key stops working within 30 seconds, the cache lifetime.

Cache misses are rate limited to 20 per second per client address, and a request over the limit gets 429 rate_limited. The limiter keys on the connection's address, or on the client address forwarded by a proxy listed in CHELABASE_GATEWAY_TRUSTED_PROXIES; it ignores X-Forwarded-For from anyone else, and groups IPv6 clients by their /64 prefix. It remembers at most 100,000 addresses (idle ones are forgotten after 60 seconds); past that it evicts entries, and an evicted address starts again with a full allowance. Behind a load balancer every client shares one address.

The gateway answers its own 404 and 405 under /data/ with the data API's error body (code invalid_query), so a client sees one error shape for the whole prefix.

Forwarding and CORSCopy Anchor Link

• The gateway sets X-Forwarded-For to the client's address (never trust it for authorization), X-Forwarded-Host to the request's host, and X-Forwarded-Proto to CHELABASE_PUBLIC_SCHEME. It speaks plain HTTP itself.
• Studio endpoints allow Studio's origin (from CHELABASE_STUDIO_HOST); the sign-in routes also allow cookies for it. The data API endpoints allow any origin (Access-Control-Allow-Origin: *, never with credentials), so browsers can call them with a public key.
• Only GET /v1/realtime/socket takes a protocol upgrade, and only Upgrade: websocket; its socket may sit idle up to an hour both ways. Any other API request that asks for an upgrade gets 400 invalid_request before it reaches an upstream.
• A host the gateway does not serve gets a 404 with an empty body, and a request without a Host a 400 with an empty body: nothing in the answer names the gateway or its hosts.

HealthCopy Anchor Link

GET /health is public and answered by the orchestrator. GET /_gateway/health is the gateway's own liveness check, answered before any host or route check.

SettingsCopy Anchor Link

The development bearer values (chelabase-dev-…) are used only with CHELABASE_DEV_DEFAULTS=1 (the workbench); otherwise an unset or development bearer stops the service at start-up. Each bearer can also be given as a file through <NAME>_FILE.