Request path and state¶

How one request reaches one provider call, what the two health endpoints are each evidence of, and every file the process writes. For the ownership split and the rule at each trust boundary, see ownership and boundaries.

One listener, two routers¶

brama serve binds one address (loopback unless BRAMA_BIND_ADDRESS names an IP) and mounts two route sets (src/core/server.rs:3400-3455): a public pair — /health, /readyz — and seventeen bearer-protected routes. Every route, including /health, sits behind the transport guard.

The request path¶

flowchart TD
    A[peer connects] --> B{transport guard}
    B -- not loopback/trusted --> B426[426 secure_transport_required]
    B --> C{bearer}
    C -- unknown --> C1[Skarbiec introspection / Wisent Identity, 5s cache]
    C -- invalid --> C401[401 unauthenticated]
    C --> D{path scope / allowlist}
    D -- out of scope --> D403[403 forbidden]
    D --> E{model name}
    E -- alias --> F[alias resolution: the registry's single route]
    E -- provider/model --> G[direct dispatch: capability at final use]
    E -- best / selector --> H{HMAC trio}
    H -- missing/expired/wrong --> H401[401]
    H --> I[subscription dispatch: rank candidates, pin the chosen account]
    F -- alias undeclared --> F404[404, details.state + details.route]
    F -- route cannot serve --> F503[503 alias_unserviceable, details.state + details.route]
    F --> G
    G --> J[provider HTTP call, 16MiB body bound]
    I --> J
    J -- provider refuses --> JR[refusal returned to the caller]
    J --> K[response in caller's dialect + records]

Alias resolution has exactly one outcome per alias: the destination recorded in routes. If that route refuses the call, its refusal is what the caller receives, and Brama dispatches nowhere else. That attempt finishes on its provider result or transport failure, not on an elapsed-time cutoff. brama aliases prints the alias, its state and its route, and GET /v1/aliases returns the same reading as rows of {"alias","state","route","reason","required","authorized","last_answer","concurrency"} with the states serving, no_route, capability_absent, capability_check_failed and routes_file_invalid. A failed credential-route inspection retains the authority's operation and cause; it is not cached as an absent credential.

Validation is strict before any provider is considered: unknown JSON fields are refused, a stated max_tokens must be at least one, temperature is bounded at 2, and a model name outside the four-part vocabulary is 400 invalid_request (http-api). Every failure is logged beside the client body as a fleet envelope (concepts/envelope).

/health versus /readyz¶

The evidence rule, stated once: a green /health is evidence the process exists; a green /readyz is evidence the product works. Nothing else about the gateway may be concluded from /health.

/health never redeems a credential, lists subscriptions, or contacts a provider, and its body says so — "dependencies": "not_probed". It answers ok from a gateway whose every redemption is being refused (verified: a standalone gateway with a garbage credential answers /health ok).

/readyz earns its verdict per request: it redeems one capability per configured provider through the same broker call the request path makes, checks that every active subscription contributes at least one discoverable model, redeems one credential per active subscription, and reports vault subscription accounts that carry no brama:agent: tag. ready is true only when all four pass and at least one provider capability is configured; otherwise the status is 503 and reason is one of the five sentences in the runbook — with providers, denied, routing, unroutable, subscriptions, unredeemable, unroutable_accounts, operator_action_required, and build beside it, and never a secret. Deploy gates and uptime monitors read /readyz.

State on disk¶

Everything Brama writes, and what it never writes:

The route registry document is read, not owned: Stado stages it and the admin routes commit to it, each write an atomic owner-only replacement of the whole document. brama routes migrate uses that same replacement to rewrite an existing file into the three known top-level fields (schema_version, whose value is the number one, plus deployments and routes), and prints the committed result.

Secrets live in Skarbiec; tokens and grants cross Brama only in memory. Process telemetry is not durable billing evidence; the ledger is the record that spans months.