# @ultimat3/http 🌐 A thin, **owned** layer over `Bun.serve`. Not a framework-agnostic HTTP kit β€” the lifecycle belongs to us so ALS context, tracing, locale/tz and authz are impossible to skip. `bun add @ultimat3/http` Β· guide: [Routes And Render Modes](https://github.com/developerz-ai/ultimate/wiki/Routes-And-Render-Modes) ```ts import { configureHttp } from '@ultimat3/http'; configureHttp({ bodyLimitBytes: 8 * 1024 * 1024, requestTimeoutMs: 300_000 }); ``` ## What it owns | Concern | Module | |---|---| | server lifecycle, drain, `/healthz` + `/readyz` | `server.ts`; `health-disclosure.ts` owns the `healthDetailPeers` key, its screen and the proxy half β€” the body rule is `@ultimat3/core`'s | | route table, matcher, `describeRoutes()` | `router.ts` | | a pathname's segments, their decoding, and its ONE spelling (`canonicalPath`) β€” shared by the matcher and by every store keyed on an address; `ctx.routePath` and `requestAddress(ctx)` say where a request was matched | `route-path.ts`, `locale-prefix.ts` | | the ordered request lifecycle | `pipeline.ts` | | typed request (params, query, body) | `request.ts` | | response constructors + `problem()` | `response.ts` | | code β†’ status, closed table | `error-map.ts`, composing `error-map-http.ts` + `error-map-tier-.ts` | | `factsOf()`, the problem document, the terminal lines | `error-facts.ts` | | token-bucket limiting, `toBucket` | `rate-limit.ts` | | the app's own HTTP declaration, and the boot's facts over it | `app-config.ts` | | CORS, CSP/HSTS | `cors.ts`, `security-headers.ts` | | CSRF (origin proof for an unsafe request a browser sent) | `csrf.ts` | | the request deadline and `ctx.signal` | `deadline.ts` | | the caller's real address behind a proxy | `forwarded.ts` | | the inbound request id and trace, read before the span | `correlation.ts` | | the `server` span (OpenTelemetry's stable `http.*`/`url.*`/`server.*` names, `ultimate.request_id`) and `http.request` on core's instrumentation bus, once per request | `pipeline.ts` | | dev error overlay | `overlay.ts` | | whether the caller is THIS machine β€” `callerLocality({ ip, headers })` β†’ `'local' \| 'relayed' \| 'remote'` (`CallerLocality`), `RELAY_HEADERS` | `local-caller.ts` | | the listener's own TLS (`tls: { cert, key }`, both PEMs or neither) | `config-tls.ts` | ## What an app declares: `configureHttp()` ```ts // apps/web/app/http.ts β€” module scope, imported by the app like any other module import { configureHttp } from '@ultimat3/http'; configureHttp({ cors: { origins: ['https://app.example.com'], credentials: true }, bodyLimitBytes: 8 * 1024 * 1024, // this API takes a 4 MB CSV requestTimeoutMs: 300_000, // and an export that really does take five minutes rateLimit: { tenantBucket: 'tenant', buckets: { tenant: { capacity: 5_000, refillPerSecond: 100 } }, }, }); ``` One registration, read once by whatever process starts the web role β€” the same seam `configureAuthenticator(authenticate, { credentialTtlMs? })` is. `credentialTtlMs` is what a resolved identity is worth on a connection that carries no further request (the `sync` node's websocket re-asks after it; omitted, five minutes) β€” the credential's lifetime is the authenticator's fact, so it is declared beside the function, never as a second authenticator. The authenticator answers "nobody" with `null` β€” or with a session refusal it throws (`X_UNAUTHENTICATED`, `X_SESSION_EXPIRED`: core's `isSessionRefusal`), which the `auth` stage reads as the same anonymous actor, so a stale cookie still reaches sign-in and a required route answers it the no-cookie `401`. Any other throw propagates. **Breaking, `As of 2026-08-24`**: before it, the only `HttpConfig` any shipped process built was a fixed literal inside `@ultimat3/cli`, so none of the four values above could be set from an app at all β€” `cors.origins` was `[]` in every deployment, which refuses every cross-origin browser call, permanently. `AppConfig` has never carried an `http` key and does not gain one: `@ultimat3/core` is tier 0 and cannot hold this package's types. `cors.allowHeaders` and `cors.exposeHeaders` default to what the typed clients send and read, off core's constants (`idempotency-key`, `x-request-timeout-ms`, `traceparent`; `x-ultimate-records`, `x-ultimate-dates`, `x-ultimate-replayed`, `ratelimit-*`, `deprecation`, `sunset`, `link`), so listing an origin is the whole declaration. A list of the app's own replaces the default whole. `AppHttpConfig` is `Omit` β€” `port`, `hostname`, `dev`, `buildId`, `signInPath`, `trustProxy`, `trustedProxyHops` and `rateLimit.scope` are the boot's, and writing one here is a **type error** rather than a value silently overwritten at the next boot. `mergeHttpConfig(configuredHttp(), boot)` is the layering, and it merges `security.csp.extend` per directive: the app's CDN source and the boot's inline-script hash are each the whole answer for something. ## The pipeline is the guarantee ``` request-id β†’ admit β†’ trace β†’ context β†’ locale β†’ auth β†’ rate-limit β†’ csrf β†’ body β†’ authz β†’ handler β†’ cache-headers β†’ (error-map) β†’ response β†’ compress ``` Exported as `PIPELINE_STAGES`, each entry carrying a `why`. `pipeline.test.ts` asserts the order. Ordering rules worth restating: | Rule | Reason | |---|---| | admit second | a stopped or saturated process refuses before any work β€” no route match, no auth, no body; a DRAINING one serves and closes the connection | | auth before rate-limit | limiter keys per actor/tenant, not per NAT address. A request that FAILS `auth: 'required'` leaves here, so this stage spends `rateLimit.defaultBucket` for it under `unauthenticated\|ip:
` β€” one key per address across every route, the bearer mount's bad tokens included; a signed-in caller behind that address spends nothing from it | | csrf after auth | it has to know who is calling: a bearer caller is exempt (not ambient); an anonymous write is judged like a signed-in one once it carries `Origin` or `sec-fetch-site`, because a forged sign-in lands the visitor in the attacker's account. Anonymous with neither header β€” a webhook, a server-to-server call β€” passes. A route declaring `meta.csrf: 'cookieless'` (an RFC 6749 token endpoint) passes an anonymous caller; it needs its own `meta.authenticate`, or `httpRouter` refuses it `X_CONFIG_INVALID` | | csrf before body | a forged write never makes the server allocate its payload | | rate-limit before body | a limited request never allocates its payload | | body before authz | policies take parsed input as their subject | | cache-headers before response | a directive can never drop a security header | What the lifecycle refuses on the caller's behalf, `As of 2026-08`: | Guard | Answer | |---|---| | a body past `bodyLimitBytes` | read through the stream and abandoned the instant the running total crosses the limit β€” `content-length` or not, multipart included β€” as `X_BODY_INVALID` | | a request carrying an identity on an `auth: 'public'` route | `cache-control: private`, never `s-maxage`; an anonymous one is shared-cacheable and keyed `vary: accept-language, cookie, x-timezone`. **Whatever the handler wrote**, `As of 2026-08-23`: the `cache-headers` stage REVIEWS a declared `cache-control` instead of standing down, because `@ultimat3/render`'s `ssrHeaders` offers every page without a `policy` to a CDN for 30s. An `immutable` answer is left alone β€” a content-addressed body is a function of its URL. **A declared hint too**, `As of 2026-09-23`: `meta.cache` / `ctx.cache` with `mode: 'public'` becomes `private` for a signed-in actor (`reviewedHint`) | | any 5xx whose code did not opt in with `registerProblemMeta({ CODE: { publicCause: true } })` | `As of 2026-09-23`, not only an undeclared one β€” `X_DB_STATEMENT_FAILED` has a status row and served the Postgres message and the SQL. The framework opts in `X_DRAINING`, `X_OVERLOADED`, `X_FLIGHT_GATE_OVERLOADED` and `X_TIMEOUT`, whose cause is the instruction. The rest: | | a 5xx nobody declared a status for | the code, the request id and a `fix:`; never the exception's own text. `error-page.ts` locked the browser out of it, and the problem document handed the same string to an agent β€” a driver's DSN, the row Postgres rejected. The real text goes to the log and the error report. `dev: true` renders it in full | | a `security.csp.extend` key that is not a CSP token, or a source carrying `;`, `,` or a space | `X_CSP_DIRECTIVE_INVALID` at `defineHttpConfig` β€” `{ 'x; script-src *': [] }` is a second directive nobody declared | | a repeated form field | a LIST, exactly as a repeated query parameter is. One collector for query, urlencoded and multipart; `Object.fromEntries` kept the last value, so a checkbox group reached the schema as one string | | a cross-origin request from an origin the allow-list refuses | no `access-control-allow-origin`, but always `vary: origin`, so a shared cache never answers an allowed origin out of the refusal's slot | | `cors.origins: ['*']` with `credentials: true` | `X_CORS_CONFIG_INVALID` at `defineHttpConfig`, because a browser accepts that pair from nobody | | a `cors.origins` entry no browser sends β€” `'https://app.com/'`, `'https://App.com'`, `'https://app.com:443'`, `'app.com'` | `X_CORS_CONFIG_INVALID` at `defineHttpConfig`, its `fix` naming the canonical form (`URL.origin`). `As of 2026-11` (v31): the match is byte for byte, so each spelling matched nothing and refused every cross-origin write | | a body past `maxRequestBodyBytes` (default 128 MiB, never below `bodyLimitBytes`) β€” declared or streamed | `X_BODY_TOO_LARGE` (413). `As of 2026-11`: Bun's own `maxRequestBodySize` is off β€” it answered an empty, uncoded 413 before any framework code, and its 128 MiB default refused every larger signed upload. `configureHttp({ maxRequestBodyBytes })` raises the ceiling | | `?next=` carrying anything but a same-origin path | the fallback β€” including a value whose TAB/CR/LF a browser strips back into `//evil.test`, and any other control character. `nextAfterSignIn` takes the value its caller's parser already decoded and never decodes it again, `As of 2026-10`: `?q=a%26b` lands as `?q=a%26b`, not `?q=a&b`. A code point above U+007F is percent-encoded so a `Location` header can carry it. The answer is the normalised path (`/a/../b` β†’ `/b`), and one whose pathname starts `//` (`/.//evil.test`) is refused; `x-ultimate-location` never carries a same-origin pathname starting `//` either | | a browser with no session on a localized URL (`/es/account`) | `303` to the sign-in page in that locale (`/es/login?next=%2Fes%2Faccount`), `As of 2026-11` β€” it went to the default-locale `signInPath` and switched the visitor's language at the door | | `Range: bytes=5-3` (last byte before the first) | ignored, `200` with the whole body (RFC 9110: an invalid range-spec is ignored), `As of 2026-11`; `416` stays for a valid range past the size | | HSTS | emitted only when the connection is affirmatively https (`ctx.https`); never by the zero-argument default | | `rateLimit.scope: 'shared'` on a per-process store | `X_RATE_LIMIT_NOT_SHARED` at `httpServer`, because N replicas each holding their own counters enforce N Γ— every configured number | | a route's own bucket and a configured bucket of that name disagreeing | `X_RATE_LIMIT_BUCKET_CONFLICT` at `httpServer`, because the loser would be a number someone read and nothing applied | | a `rateLimit.tenantBucket` naming a bucket nothing declares | `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN` at `defineHttpConfig`, because the name would fall through to `default` and a whole tenant's cap would silently be the 120-burst read bucket | | an injected limiter that does not hold a bucket a route declares | `X_RATE_LIMIT_BUCKET_UNBOUND` at `httpPipeline`, because the name would fall through to `default` β€” measured at 120 burst for a route declaring 5 | | a config that never declared `rateLimit.scope` | `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `'process'` used to be the default, so "nobody asked" and "the app said one replica" were the same value while the chart runs three | | `trustProxy: true` with no `trustedProxyHops` | `X_TRUST_PROXY_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `trustProxy` now defaults to `false`, and `x-forwarded-for` is read at `entries.length - hops` β€” never at `[0]`, which is whatever the client typed | | an unsafe method from a browser β€” signed in, or anonymous with `Origin`/`sec-fetch-site` β€” that cannot be shown to be same-origin | `X_CSRF_BLOCKED` (403). `sec-fetch-site: same-origin`, `Origin` equal to this app, or an EXACT listing in `cors.origins` β€” anything else is refused before the body is read. `origins: ['*']` lists nobody here: `'*'` is a value for the response header, not a per-origin allowance | | a request past `requestTimeoutMs` (30s) | `ctx.signal` aborts and the socket is answered `X_TIMEOUT` (504); a caller may shorten the deadline with `x-request-timeout-ms`, never lengthen it. A handler still running after the 504 stays in core's in-flight count until it settles, so a drain waits for it instead of closing the pool under it | | a handler silent for longer than Bun's 10 s idle default | ANSWERED: `start()` hands `Bun.serve` an `idleTimeout` of `socketIdleTimeoutSeconds(requestTimeoutMs)` β€” `ceil(ms / 1000) + 2` s, `0` (off) for no deadline or one past Bun's 255 s ceiling β€” so the socket outlives the deadline. `As of 27.16.0`: Bun's default cut every such request at ~10–12 s, a 502 behind a proxy, whatever `requestTimeoutMs` said | | a budget above `2_147_483_647` ms | no timer holds it: `requestTimeoutMs` past it is `X_CONFIG_INVALID`, and an `x-request-timeout-ms` past it is ignored β€” it used to arm a ~1 ms timer | | the caller going away mid-request | `ctx.signal` aborts on the inbound `Request.signal` too, so a closed tab unwinds cooperative work instead of holding its pool slot for the rest of the budget. Both halves are one signal β€” the caller's abort is forwarded into the deadline's controller, first abort wins with its own reason β€” and `requestTimeoutMs: 0` still delivers the caller's | | a request while the process is draining | SERVED, with `connection: close` so the client's next request lands on another pod, `As of 2026-09-23` β€” refusing it failed 598 of 7,690 requests across one helm upgrade on kind, every one on a kept-alive connection inside the readiness grace. Only a STOPPED process (resources closed) answers `X_DRAINING` (503) + `retry-after` | | SIGTERM | `/readyz` answers 503 at once, the listener stays open for `drain.readinessGraceMs` (core; 5000 ms outside development/test, 0 inside), then closes and the drain runs. Pass `httpServer({ …, drain: appConfig.drain })` so `app.config.ts`'s value is the one applied; omitted, core's default holds and a `configureLifecycle({ readinessGraceMs })` stands | | `?locale=es` | the locale source that outranks the cookie and the header (`resolveLocale`'s order), `As of 2026-09-23` β€” documented in `wiki/I18n.md` and never read before | | a 4xx | logged at `warn` (401, 403, 429) or `info` (every other 4xx); only a 5xx is an `error` line. Every `info` refusal β€” routine, 404, 400, 422 β€” is `info` once per route and code per minute, `debug` after | | `x-forwarded-client-cert` without `trustClientCertHeader: true` | `ctx.peer` is `null`. **Breaking**: `trustProxy` alone used to read it, and an ingress that appends to `x-forwarded-for` need not strip a certificate header the client sent | | `/healthz`, `/readyz` from a peer `healthDetailPeers` does not list | `{ state, ready, role }` and the same status code; `buildId`, `inflight`, `uptimeMs`, `checks` and `registered` go to a listed peer only (default `['loopback']`), and behind a declared proxy the forwarded caller must be listed too | | a `//…` URL | `301`/`308` to the unprefixed path, normalised as the router matches it β€” `//host/x` after the prefix is `/host/x`, never a scheme-relative `Location` | | a 3xx to a client-router request whose target is not `http:`/`https:` | `x-ultimate-location` names the REQUESTED url as a path; the target is never handed over, and one that will not parse is treated the same | | a handler's `cache-control` carrying `max-age`, `must-revalidate` or `proxy-revalidate` with no `private`/`no-store` | an offer to a shared cache (RFC 9111 Β§3): `private, max-age=0` for a request carrying an identity, `vary`-keyed for an anonymous one. `immutable` stays exempt | | a `text/*` body | decoded by its `charset` parameter (UTF-8 when none), `As of 2026-11`: `utf-8`, `utf-16le`, `utf-16be`, `windows-1252` (`latin1`/`iso-8859-1` resolve to it); any other label, known or not, is `X_BODY_INVALID`. JSON and forms stay UTF-8 by their own specs (`request-charset.ts`) | | a body with no `content-type` | `X_BODY_INVALID` from `bodyRaw()` / the `body` stage β€” it used to read as "no body", so an all-optional schema validated a request nobody parsed. `bodyBytes()` still reads it | | a dev-only disclosure β€” the overlay, the `Server-Timing` breakdown, `x dev`'s `/_x`, the dev MCP token β€” to a caller that is not this machine | withheld, `As of 2026-11`: `callerLocality` answers `'local'` only for a direct loopback caller carrying none of `RELAY_HEADERS` (`x-forwarded-for`, `forwarded`, `x-real-ip`). A LAN peer on `x dev --host`, a forged forwarded loopback past a declared hop and a Host-rewriting tunnel on this machine all get the production page and `total` alone | | `tls: { cert, key }` in the config | the listener serves TLS; a direct TLS socket counts as https (`ctx.https`, so HSTS) with no header consulted. One half, an empty one or a non-PEM value is `X_CONFIG_INVALID` naming the half, never its bytes. Absent: the options `Bun.serve` always got. The boot sets it from `TLS_CERT`/`TLS_KEY` or `x dev --tls` | | two cookies set in one request | two `Set-Cookie` lines: the `response` stage appends them, where `headers.set` in a loop kept the last and dropped any on the handler's own Response | | a 5xx whose cause is withheld | its `fix` is the error's `callerFix`, else `x errors explain --json` β€” never the developer's `fix:`, which is written from the same statement, row or path the cause was | | `buildId: null` | skew detection off, whatever `BUILD_ID` says; `hostname` never defaults from `HOSTNAME` (the container id under Docker) | | an `x-forwarded-client-cert` value in quotes | unescaped ONCE, after the pairs are split β€” `Subject="O=Acme; Inc,CN=svc-one"` is that whole subject, not `O=Acme` | | a request past `maxInflight` (1000) | `X_OVERLOADED` (503) + `retry-after`, shed in the `admit` stage before any work | | `shedLagMs: 250` and an event loop whose lag p99 (two seconds, sampled every 20 ms) is past it | `X_OVERLOADED` (503) + `retry-after: 1` from `admit`: the CPU-bound overload `maxInflight` cannot see. **Off by default in 31.x** (`0`): no sampler runs, nothing is shed on lag, `As of 2026-11` | | a request slower than `slowRequestMs` (1000; `0` off) | one `http.request.slow` line at `warn` (`SLOW_REQUEST_MESSAGE`): `http.request.method`, `http.route` (the pattern), `http.response.status_code`, `durationMs`, `gateMs` (the stages before the handler), `handlerMs`, `dbStatements`, `dbMs`, `renderMs`, `cacheHits`, `cacheMisses`, and the request and trace ids. No per-request access log: the request metric and the trace are that record | | `Server-Timing` | `total;dur=…` always; under `x dev` also `gate`, `handler`, `db` (with the statement count), `render` and `cache` β€” never in production, where a statement's duration is a timing oracle. The statement, render and cache figures are heard on the bus by `subscribeRequestTimings()`, which the boot installs once beside `subscribeSemconvMetrics()`; `requestTimings(ctx)` reads them | | an anonymous hit on an `auth: 'required'` route (`X_UNAUTHENTICATED`, routine) | counted in `http_refusals_total{code}` (every 4xx is), logged at `info` once per route and code per minute and at `debug` after. A credential checker's own `X_UNAUTHENTICATED` stays `warn` | | `accept-encoding` on a compressible public answer | `compress` negotiates `zstd` then `gzip` (RFC 9110 weights), gives a 304 the same validator form as its 200 (`etag-form.ts`), and codes a public strong-ETag body once per process (`compress-cache.ts`, LRU 512 entries / 16 MiB) at zstd 9 / gzip 9 β€” paid once, so stronger than the per-request zstd 3 / gzip 6 (170,641 B sheet: 22,051 B against 27,136 B, `As of 2026-11`). A `public, immutable` answer with no strong ETag (island chunks, surface stylesheets) is coded once more after its first hit, on the thread pool, as brotli 11, zstd 19 and gzip 9 (`compress-precode.ts`; keyed by path + length + byte hash, 2 at a time), and every later hit is a lookup: `br` when the client also offers `zstd` or `gzip`. Measured on a 170,641 B sheet: 19,496 B brotli against 27,136 B zstd 3, `As of 2026-11`. Exported: `PRECODERS` (the three coders, each on the thread pool; `x build --target static` writes `.br`/`.gz` siblings with them), `PRECODINGS`, `Precoding` | | a public text answer of at least 1 KiB, or with no declared length | gzip on the wire, from the last stage (`compress`), `vary: accept-encoding` and a weak `etag`. Up to 256 KiB with a declared length it is coded whole (`gzipSync`, with its `content-length`); past that, or a stream with no declared length once its first 1 KiB has arrived β€” CSV, a large JSON export β€” it is coded as the client pulls (`CompressionStream`, no `content-length`), `As of 2026-11`; an undeclared body that ends under 1 KiB leaves identity with its length, and an undeclared NDJSON feed is never coded (the coder emits nothing until its source closes). A HEAD answered with no body has nothing to measure and stays identity. A private answer, a signed-in one that is not `immutable`, `no-store`, `no-transform` or a range stays identity and unread. HEAD carries GET's coded headers. Exported: `isCompressibleType(contentType)`, `COMPRESS_MIN_BYTES`, `COMPRESS_MAX_BYTES` | `handle()` resolves to a Response, always β€” a stage that throws after the handler, or while rendering another stage's throw, degrades to `X_PIPELINE_FINALIZE_FAILED` (500, the stage named in `cause`) and the chain finishes that document instead. `finalize.ts` owns that promise. ## Rate limiting holds where the app says it holds The counters live in a `RateLimitStore`. `memoryRateLimitStore()` is the default and is **one process' worth of state**, so a deployment at `replicas: 3` enforces every bucket three times over. The app declares which it needs and passes the store that provides it β€” the store is the only thing that knows where its counters live, and a framework that inferred the answer from the environment would get it wrong on the first deployment that scaled differently. A store answers three calls: `take(key, bucket, cost, nowMs)` spends, `peek(key, bucket, nowMs)` reads (refill applied, **no write and no row** β€” a key never taken is full; `rateLimitPeek` and `refilledTokens` do the arithmetic) and `reset(key)`. `peek` is required, `As of 2026-10`: the `auth` stage asks it on every request to an `auth: 'required'` route. **One store, one place to choose it, `As of 31.0.0`.** Routes and primitives (an action's or a query's declared `rateLimit:`) count in ONE installed store. The boot installs `postgresRateLimitStore` over the pool it opened; an app that wants another names it in `apps//runtime.ts`, and nowhere else β€” `httpServer({ rateLimitStore })` and the barrel's `installRateLimitStore` / `adoptRateLimitStore` are gone (Upgrading, 30 β†’ 31). The installer lives on `@ultimat3/http/adapter`, which the boot imports; an app never calls it. ```ts // apps/web/runtime.ts import type { RateLimitStore } from '@ultimat3/http'; declare const myStore: RateLimitStore; // its own scope is 'shared' export const runtime = { rateLimitStore: myStore }; ``` | Declared | Store | Result | |---|---|---| | nothing | any | `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig` β€” **breaking, `As of 2026-08`** | | `'process'` | any | boots; the limit is per replica, which is what was asked for | | `'shared'` | `scope: 'shared'` | boots; one bucket for the fleet | | `'shared'` | `scope: 'process'`, or `enabled: false` | `X_RATE_LIMIT_NOT_SHARED` at boot | There is no default. `'process'` used to be one, which made "the app never said" and "the app said one replica" the same value while `docker/helm/values.yaml` runs three β€” and `X_RATE_LIMIT_NOT_SHARED` only fires on a `'shared'` declaration, so the silent case was exactly the one nobody declared. A limiter with `enabled: false` owes no declaration: nothing is enforced, so nothing can be wrong. The installed store feeds the `PipelineDeps.limiter` seam rather than sitting beside it: the bucket maths stays in `rateLimiter`, so every driver agrees on the numbers. **One request spends a LIST of keys, `As of 2026-08-24`** β€” the caller's (`actor`, else `org`, else `ip`) and, when the app declared `rateLimit.tenantBucket`, that caller's tenant. The key builder used to pick exactly ONE subject and consult `orgId` only when there was no actor id, which no authenticated request ever satisfies: a tenant with 8,000 seats took 8,000 Γ— the per-actor burst against one shared pool, every bucket inside its own limit, and no number an operator could set would have refused it. The tenant key is `tenant|org:` and is deliberately NOT scoped to the route β€” a per-route tenant bucket is the same allowance once per route. The spend stops at the first refusal, so a caller its own bucket refused costs its tenant nothing, and the `ratelimit-*` headers report the bucket closest to refusing. `tenantBucket` defaults to `null`: one tenant is a person and the next is five thousand seats, so there is no allowance a framework can pick for you. **A shared store ships, `As of 2026-08`** β€” `postgresRateLimitStore({ executor })`, one table and one `insert … on conflict` per take (a peek is one `select`), so N replicas count against one bucket. Until it landed, `scope: 'shared'` was a declaration nothing in the framework could satisfy while `x new` scaffolded `replicas: 2`. `executor` is a `PgExecutor` β€” anything speaking `query(text, values)`, which is one line over the client the boot already opened; **never `Bun.sql`**, whose `.query` is `undefined`. ```ts // apps/web/runtime.ts β€” only when the boot's own default is not the one you want import { baseClient, dbExecutor } from '@ultimat3/db'; import { type PgExecutor, postgresRateLimitStore } from '@ultimat3/http'; // The pool this process already opened, never a request's open transaction β€” the boot builds // the same executor when it installs the store for you. const executor: PgExecutor = dbExecutor(baseClient); export const runtime = { rateLimitStore: postgresRateLimitStore({ executor }) }; ``` **The table is UNLOGGED, `As of 2026-11`** β€” `x_rate_limit` is declared `RATE_LIMIT_STORAGE` (`unlogged`, `fillfactor = 70`), so a take writes no WAL record (2 before, measured with `explain (analyze, wal)`) and stays a HOT update (0.949 over 2,000 live buckets, 0.315 at the default fillfactor), and a take no longer writes `updated_at`. The boot converges a table an earlier version created: `alter table x_rate_limit set unlogged` rewrites it under `ACCESS EXCLUSIVE`, bounded by the migrate role's `lock_timeout`. **After a crash** Postgres truncates an unlogged table, so every bucket comes back FULL β€” one free burst per key, never a lockout; a clean restart keeps it, a promoted standby starts empty. `x_auth_lockouts` stays logged. **A Redis store ships too, `As of 2026-11`** β€” `redisRateLimitStore({ client })`, one Lua token bucket per take (`EVALSHA`, falling back to `EVAL` on `NOSCRIPT`), a peek one `HMGET`. A hot key β€” one NAT, a tenant bucket β€” no longer serialises every request on one Postgres row lock. Each key expires once it would be full again, so it needs no purge. Same `scope: 'shared'`, same deadline (`deadlineMs`, 250 ms) and the same degrade-to-this-pod's-memory on an outage, `ERR_REDIS_CONNECTION_CLOSED` included. Connect the client before the first request, or the first takes are decided in memory. ```ts // apps/web/runtime.ts import { redisClient } from '@ultimat3/core/redis'; import { redisRateLimitStore } from '@ultimat3/http'; export const runtime = { rateLimitStore: redisRateLimitStore({ client: redisClient(), prefix: 'app' }) }; ``` **An IPv6 caller is its `/64`, `As of 2026-11` (v31)** β€” `@ultimat3/core`'s `addressNetwork(ip)` is the address every anonymous key and the failed-credential key count by: IPv4 whole (an IPv4-mapped IPv6 is its IPv4), any other IPv6 `::/64`. One subscriber holds a /64, so the full address handed each holder a fresh bucket per request. The table bounds itself only when something asks it to: `store.purgeExpired(ctx.now().getTime())` from a `task` drops every bucket that has refilled to capacity, which is the memory store's forget rule. `nowMs` is required and must come from the same clock the takes use β€” measured against the server's clock instead, the offset between the two reads as refill and deletes buckets a throttled caller is still sitting in. The maths reads an injected `Clock`, defaulting to `systemClock`: `rateLimiter({ config, clock })`. **Breaking, `As of 2026-08-19`** β€” it took `now?: () => number` before and read `Date.now()` when nothing passed one, which both production call sites did, so the limiter that actually throttles a request could not be frozen. Replace `now: () => t` with `clock: frozenClock(t)`; a limiter you build yourself still reaches the pipeline through `PipelineDeps.limiter`, which stays the only seam for one. ### A route may bring its own bucket `meta.rateLimit` names a bucket; `meta.rateLimitBucket` is the numbers that bucket must hold. `withRouteBuckets` registers them at construction β€” `httpServer` and `httpPipeline` both apply it, idempotently β€” because `defineHttpConfig` runs before any route exists and cannot have them. Without that half, a name nothing defined fell through `bucketFor` to `default`: an action declaring `limit: 5` ran on 120 burst, and the number reached the OpenAPI document all the same. | Declared | Configured under the same name | Result | |---|---|---| | nothing | β€” | `default`, unchanged β€” most routes | | numbers | nothing | the route's numbers, registered | | numbers | the same numbers | boots; a restatement is not a disagreement | | numbers | different numbers | `X_RATE_LIMIT_BUCKET_CONFLICT` at boot | Neither source wins a disagreement, because whichever lost would stay a number an author read and nothing enforced. `toBucket` β€” in **this** package, beside `Bucket` and the maths it validates, because `action` and `query` are the same tier and can never import each other β€” is the one conversion from a declaration's `{ limit, windowMs }` to a bucket's `{ capacity, refillPerSecond }`, and it refuses a pair the limiter could not run on β€” including one whose two halves look fine and whose **division** does not, like `{ limit: Number.MAX_VALUE, windowMs: 1 }` computing to an infinite refill. Registering into the config is only half of it, because the limiter resolves names against the table **it** closed over. `RateLimiter.buckets` publishes that table β€” declared, never inferred, the same rule as `RateLimitStore.scope` β€” and `assertRouteBuckets` compares it against the routes at construction. A limiter passed to `PipelineDeps.limiter` that cannot enforce a declared bucket is refused rather than rebound: a `RateLimiter` is opaque, so rebinding would mean discarding the store it carries, and a caller who built their own limiter may have meant their own numbers. Pass no limiter β€” `httpServer({ routes })` builds one over the installed store from the merged table. ## Routing Precedence is structural, not declaration-ordered: **static > param > wildcard**, depth-first with backtracking. A tie is `X_ROUTE_CONFLICT` at startup, never a coin flip. `HEAD` falls back to the `GET` route. `meta.auth` is **required** β€” a route cannot forget to declare its auth posture. ```ts import { httpServer, defineHttpConfig, jsonResponse } from '@ultimat3/http'; const handle = httpServer({ routes: [{ method: 'GET', path: '/posts/:id', meta: { name: 'posts.show', auth: 'public' }, handler: (req) => jsonResponse({ id: req.param('id') }) }], config: defineHttpConfig({ port: 3000 }), role: 'web', }).start(); ``` Static paths are registered in Bun's native `routes` table (keyed `encodeURI`'d: `Bun.serve` refuses a non-ASCII key); param/wildcard paths, and any other spelling of a static one, fall through to `fetch`. Method resolution stays ours so a 405 still carries problem+json. `As of 2026-10-02`: a literal segment matches its percent-encoded request spelling, either hex case (`/precios-espa%C3%B1a` reaches `/precios-espaΓ±a`), and a wildcard matches an empty rest β€” `/docs` and `/docs/` reach `/docs/*path` with `path: ''`, after a static `/docs` route if one is declared. A malformed escape is still `X_PATH_INVALID` or a 404, never a thrown `URIError`. ### No WebSocket upgrade on the `web` role, and no hand-written `api/` route `As of 2026-09-05`, and stated because an app went looking for both. The `web` role's `Bun.serve` is built with no `websocket` handler (`server.ts`: "the `web` role does not use one"), so nothing under `/api` can `server.upgrade()` a request; and `/api/*` is a **projection** β€” `apiRoutes()` in `@ultimat3/cli` mounts every `action` and `query` the registries hold, and `x g route --surface api` does not exist (`readSurface` refuses `api` by name). A raw socket is not an action, so it has no home on this role. The framework's one WebSocket is the `sync` role's (`@ultimat3/realtime/server`, `PORT + 1`), authenticated by `SyncAuthenticator` and reached from the browser through `LiveClient`. A bidirectional stream β€” a PTY, a log tail β€” is written as **two halves that already exist**: | Direction | Primitive | Why | |---|---|---| | server β†’ browser | a `channel` topic on the sync socket (`ChannelHub`, `topic(...)`, `client.subscribe(topic, …)`) | ordered frames, reconnect and backpressure are the sync node's, not a second socket's | | browser β†’ server | an `action` β€” one call per keystroke batch | it gets a policy, a schema, rate limiting, audit and the typed client for free; a socket message gets none | A `web`-role upgrade hook was refused rather than half-built: the pipeline returns a `Response` at every stage (middleware, finalize, security headers), and an upgraded request must return `undefined` from `fetch` β€” a second exit from the pipeline with none of its guarantees. If the two halves above cannot carry a case, the fallback is a long-poll `action` (`GET`-shaped, returning `{ frames, cursor }` and re-called on return), which is what the app that asked shipped. A client that is **not a browser** (a device agent) is the one exception, and it is declared, not hand-written: `deviceSocket()` from `@ultimat3/realtime/server` ([Realtime](../../wiki/Realtime.md#device-sockets)). Several mounts on one listener β€” the sync node's beside a device socket's β€” are joined by `joinWebSocketMounts(mounts)`: routed by path at the upgrade, and each socket's events back to the mount that upgraded it, keyed by the `data` object it upgraded with (`As of 2026-11-06`). ### A second door: `bearerMount` (`/v1/*`) `As of 22.6.0`. `bearerMount({ prefix, routes, scopes, resolveToken, rateLimit?, rateLimitStore? })` re-serves routes the app already projects under a prefix β€” same handler, same policy β€” and changes exactly three things. Apps declare it through `defineApi({ http: { mounts } })` (`@ultimat3/action`); `@ultimat3/cli` builds it in both boots over `apiRoutes()`. | On the mount | Answer | |---|---| | credential | `Authorization: Bearer` ONLY β€” `meta.authenticate` replaces the app's authenticator, so a session cookie authenticates nothing here (and a bearer call needs no CSRF proof) | | no / unresolved token | 401, `WWW-Authenticate: Bearer` / `Bearer error="invalid_token"` | | a primitive outside the token's `scopes` | 404 `X_ROUTE_NOT_FOUND`, identical to an unknown path β€” MCP's hidden-tool rule | | per-token allowance | `RateLimit-Limit/-Remaining/-Reset` on every answer, 429 + `Retry-After` past it; keyed by a SHA-256 of the token | | paths | `/api/` β†’ `/`, `/_x/query/` β†’ `GET /` (`mountedPath`); a pinned `:param` template keeps its params β€” `/orders/:id/refund` β†’ `/orders/:id/refund`. Only the prefix is parameter-free | | `rateLimit` declared | spent once per request in the mount's authenticator, before `body` and `authz`, so a 422 or a 403 pays too; it REPLACES `default` on the mount's routes (`rateLimitedBy: 'handler'`); a route's own `meta.rateLimit` and the tenant allowance still apply. Not declared: `default` stands | | `Link: rel="successor-version"` | the mounted path when the successor is in the cut and this token holds its scope, success or refusal; otherwise removed. Any other `Link` is the handler's | `RouteMeta.authenticate` is the mechanism: a route that states one is reached only through it. For API keys, `resolveToken` is `@ultimat3/auth`'s `apiKeyResolver(() => store)` β€” a live key is `{ actor, scopes }`, every wrong one is the same `null`, and a store fault stays a throw. `resolveToken(token, facts)` (`As of 2026-10`): `facts` is `RequestFacts` β€” `{ address, userAgent, origin, path }`, frozen, built by `requestFacts()`. `address` is `ctx.ip`, the pipeline's trusted-hop answer, never a forwarding header. `@ultimat3/mcp` hands its resolver the same object (`McpRequestFacts`), so one resolver can bind a token to a network or refuse a browser `Origin` on both doors. A one-argument resolver still works. ## Inbound webhooks `verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook mechanism. It is a plain function and not a pipeline stage, because the secret is **per sender** and only the route knows which one applies. ```ts // The check alone. Mounted, it is the `verify` of a `webhookReceiver()` from @ultimat3/jobs β€” // verify(inbound) { return verifyWebhookSignature(inbound.request(), { secret }) } β€” which // queues durably before it acks; a hand-mounted route like this one acks before anything is kept. import { verifyWebhookSignature } from '@ultimat3/http'; declare const env: { readonly PARTNER_WEBHOOK_SECRET: string }; // the app's defineEnv() result // The seen-set and the dispatch are the app's β€” this package has nowhere to keep either. declare function alreadyHandled(eventId: string): Promise; declare function handle(topic: string, payload: unknown, eventId: string): Promise; export async function POST(request: Request): Promise { const { eventId, topic, body } = await verifyWebhookSignature(request, { secret: env.PARTNER_WEBHOOK_SECRET, }); // Parse the bytes that were SIGNED. Never `request.json()` β€” the stream is spent, and a // re-serialisation would not be the bytes the mac covers. const payload: unknown = JSON.parse(body); if (await alreadyHandled(eventId)) return new Response(null, { status: 200 }); await handle(topic, payload, eventId); return new Response(null, { status: 202 }); } ``` | Property | How | |---|---| | constant time | the mac is compared with `@ultimat3/core`'s `timingSafeEqual`, never `===` β€” where two macs first differ is exactly what a timing oracle forges one byte at a time | | a replay expires | the signature's timestamp is checked against `toleranceMs` (5 minutes by default), **both** directions β€” a sender whose clock runs ahead is the same window pointed the other way | | a replay is detectable | `eventId` is signed and returned, so it cannot be moved in transit; the seen-set is your table, because the framework has nowhere to keep one | | moving the timestamp breaks it | the timestamp is inside the canonical string, so editing `t=` on a captured request invalidates the mac | | the raw bytes are what is verified | the body is read through core's counting reader β€” the same one `UltimateRequest` uses β€” so a sender that declares no length cannot make this handler hold an unbounded payload | | no secret is refused, never verified against | an empty or non-string `secret` (an unset `process.env.X`) throws `X_CONFIG_INVALID` before the request is read β€” a mac under an empty key is one anyone can compute. Only empty is refused, not short: the sender signs with any non-empty secret | | the mac is checked BEFORE the window | `X_WEBHOOK_SIGNATURE_STALE` means *authentic and old*, never *unreadable and old*, so an operator reading it goes to a clock or a replay | `X_WEBHOOK_SIGNATURE_INVALID` and `X_WEBHOOK_SIGNATURE_STALE` are both **401**: the request is well formed and carried a credential, and the credential is what failed. Neither triggers the sign-in redirect, which keys on `X_UNAUTHENTICATED` alone. The sending half is `webhook()` in `@ultimat3/jobs`. Neither package may import the other, so the wire format β€” the canonical string, `WEBHOOK_ID_HEADER`, `WEBHOOK_SIGNATURE_HEADER`, `WEBHOOK_TOPIC_HEADER`, `WEBHOOK_SIGNATURE_VERSION` β€” is `@ultimat3/core`'s (`webhook-signature.ts`), and a receiver imports the names from there: 25.0.0 dropped this package's re-exports of them, and of `escapeHtml` and `readCookie` (`X_HELPER_COPY`). ### A vendor's hmac: `verifyBodyHmac` Every other sender signs its own way, so no vendor verifier ships. `verifyBodyHmac` is the one shared step: HMAC-SHA256 under a UTF-8 secret over the bytes you name, compared in constant time, under any secret of a rotation list. Which bytes (`body`, `${t}.${body}`) and which header are the vendor's, and yours to pass. A secret the vendor hands out encoded (Svix's base64 `whsec_`) is not this helper's: the mail receivers decode their own. It answers `{ bytes, text }` β€” read the event id from `text`, never from an unsigned header. ```ts import { verifyBodyHmac } from '@ultimat3/http'; declare const bytes: Uint8Array; // the exact body β€” `webhookReceiver`'s inbound.bytes declare const headers: Headers; const { text } = verifyBodyHmac({ bytes, secret: [Bun.env['VENDOR_SECRET'] ?? '', Bun.env['VENDOR_SECRET_PREVIOUS'] ?? ''], given: headers.get('x-hub-signature-256'), encoding: 'hex', // or 'base64' prefix: 'sha256=', // compared, never stripped }); ``` | Answer | When | |---|---| | `{ bytes, text }` | one secret's mac, behind `prefix`, equals `given`; `text` is `null` when the bytes are not UTF-8 | | `X_WEBHOOK_SIGNATURE_INVALID` (401) | no signature, or none matches. The cause names the encoding, the prefix and the secret count β€” never a mac, a secret or a byte | | `X_CONFIG_INVALID` | an empty or unset secret, an empty list, or one empty entry in it | ## The exact body bytes `As of 2026-09-24`. `UltimateRequest#bodyBytes()` returns the body exactly as it was sent, whatever its content type. It is size-capped (`bodyLimitBytes`), read once and cached, and it is the same byte array that `bodyRaw()` parses. An action handler receives a `Ctx` and not the request, so it calls `useRequestBodyBytes()` to read the request in scope: ```ts import { action, t } from '@ultimat3/action'; import { useRequestBodyBytes, useRequestHeader } from '@ultimat3/http'; import { allow } from '@ultimat3/policy'; // The app's own check: SNS signs a canonical string of fields, a gateway signs the bytes. declare function verifySender(bytes: Uint8Array, header: string | null, body: string): Promise; export const ingestSesEvent = action({ input: t.string.max(600_000), // SNS posts text/plain: the decoded body output: t.object({ ok: t.boolean }), policy: allow('public'), // the signature below authenticates the sender async handle({ input }) { const bytes = await useRequestBodyBytes(); // what the sender signed, byte for byte await verifySender(bytes, useRequestHeader('x-signature'), input); return { ok: true }; }, }); ``` | | | |---|---| | why not the decoded string | a decode can rewrite a BOM or an invalid UTF-8 byte, and the signature then fails with no visible cause | | one reader | `bodyRaw()` and `bodyBytes()` share one capped read, so an action that reads both reads the stream once | | off HTTP | `X_NO_REQUEST`: a job or an MCP call has no body bytes | ## Serving a stored object `As of 2026-11-02`. `objectResponse(request, { object, open }, { cache?, headers? })` is the one correct answer to a GET for bytes held elsewhere: `/_storage`, `/media`, a query's download, and your own route for an object a stranger may fetch. | Argument | Is | |---|---| | `request` | anything with `header(name)` | | `object` | `{ contentType, size, etag?, lastModified? }`. Structural: this package imports no storage, and a `StorageObject` fits. No etag (or `''`): no `etag` header, no 304 | | `open(range?)` | exactly those bytes as a `BodyInit`, or a promise of them. A 304 and a 416 open nothing | | `cache` | a `CacheHint` applied to every status. Omitted, the route's `meta.cache` decides | | `headers` | replaces the stored-object rule (`attachment` + `sandbox` for any type but a raster image, audio or video), for a caller with its own | A failing `if-range` (another etag, a weak one, a date that is not exact) ignores the range and answers the whole object, so no window of an older revision is spliced onto this one. `notModified(request, etag, headers?)` is the 304 alone, or `undefined`, for bytes not yet in hand: a route that would have to decode to answer asks it first. `*`, a weak validator and a comma list all count. ## Setting a cookie `As of 2026-10-06`. A route handler, a page `load()` or an action cannot hand the pipeline a `Response` of its own, so it calls `setCookie` on the request in scope. The line is `@ultimat3/core`'s `serializeSetCookie` β€” the one serializer β€” appended to the context's response headers, which the `response` stage appends to whatever is sent. ```ts import { action, t } from '@ultimat3/action'; import { deleteCookie, setCookie } from '@ultimat3/http'; import { allow } from '@ultimat3/policy'; export const choosePreferences = action({ input: t.object({ theme: t.string.max(16), reset: t.boolean }), output: t.object({ ok: t.boolean }), policy: allow('public'), handle({ input }) { if (input.reset) deleteCookie('theme', { path: '/' }); else setCookie('theme', input.theme, { httpOnly: false, maxAge: 60 * 60 * 24 * 365 }); return { ok: true }; }, }); ``` | | | |---|---| | defaults | `Path=/; HttpOnly; Secure; SameSite=Lax` β€” core's; every option is `SetCookieOptions` | | a line already built | `setCookie(line)`, `As of 2026-11`: **the one way to send what `@ultimat3/auth` answers** β€” `setCookie(sessionCookie(issued.token, policy))`, `setCookie(signedIn.cookie)`. Sent unchanged, and only if `serializeSetCookie` writes exactly those bytes back: CR/LF, an attribute it never writes or a hand-edited line is `X_COOKIE_INVALID`, and the refusal never repeats the line, which can hold a session token | | two calls | two `Set-Cookie` lines, in call order. The same name on two paths is two cookies; nothing overwrites | | clearing | **`deleteCookie(name, { path, domain })` is the one way**: empty value, `Max-Age=0`, the `Path`/`Domain` (and `Partitioned`) the cookie was set with. `setCookie` with `maxAge: 0`, or an `expires` at or before `ctx.now()`, is `X_COOKIE_INVALID` naming `deleteCookie`. So is a line with an empty value and `Max-Age=0`; a line that still carries a value keeps its `Max-Age=0` (a rotated session in its last second) | | an invalid cookie | `X_COOKIE_INVALID` (core) before anything is appended: a non-token name, `__Host-` without `Secure`, a pair over 4096 octets | | off HTTP | `X_NO_REQUEST` in a job, a task or an impersonated child context; `X_NO_CONTEXT` outside any | | is there a request | `hasRequest()`: `true` in a request and in any context derived inside one (where readers still refuse), `false` in a job, a task or no context. For a reader whose honest answer off HTTP is `null` (`useActionAnswer`) | | by hand | refused: `bun run set-cookie-literals` fails the build on a `Set-Cookie` attribute spelled in a literal anywhere but `packages/core/src/cookie.ts` (`X_SET_COOKIE_HAND_BUILT`) | ## Rendering a shared document `withAnonymousRequest(ctx, url, (scope) => …)`: run as this request with nobody behind it. What `@ultimat3/cli` renders `isr` and `static` in, so a stored document holds no visitor's answer. | | | |---|---| | the actor | anonymous, with registered services rebuilt for it | | the inbound headers | none: no header is in a stored page's key, and `accept-language` is already `ctx.locale` | | `url` | the one handed in: the document's address, already narrowed to its key | | `tz` | the app's default; `locale` stays, because it is in the key | | `ip`, `peer`, `clientBuildId`, `authz`, `rateLimit`, `readBody` | empty | | a redirect | `setRedirect()` lands on `scope`: read it with `takeRedirect(scope)` | | the response headers | `scope.headers` is `ctx.headers` | | the outer `ctx` | unchanged: the pipeline still answers the identified request privately | ## Errors `X_ROUTE_NOT_FOUND` Β· `X_METHOD_NOT_ALLOWED` Β· `X_BODY_INVALID` Β· `X_UNAUTHENTICATED` Β· `X_FORBIDDEN` Β· `X_RATE_LIMITED` Β· `X_BUILD_SKEW` Β· `X_ROUTE_CONFLICT` Β· `X_CORS_CONFIG_INVALID` Β· `X_RATE_LIMIT_NOT_SHARED` Β· `X_WEBHOOK_SIGNATURE_INVALID` Β· `X_WEBHOOK_SIGNATURE_STALE` One `factsOf()` feeds three renderings β€” terminal, `application/problem+json`, dev overlay β€” so the `code`/`cause`/`fix` strings can never diverge. Which of them a caller gets is one sniff, `acceptsHtml(request)` β€” an `Accept` naming `text/html`. Exported so a projection answering a browser differently (an action's `native` form answer) asks the same question the error page does, never a copy of it. Every problem document carries `retry` (`terminal`, `retryable` or `retry-after`, core's `errorRetry`) at its root, a 401 and a scope 404 included. A hidden 5xx answers the class and nothing else about the failure. It is what a client maps to an exception, so no app carries a middleware to add it. A problem document's `type` and `docs` answer different questions and are two different values. `type` is `problemTypeFor(code)` β€” `urn:ultimate:error:X_BODY_INVALID`, the RFC-9457 identifier a client switches on, per code, with no host to resolve or rot. `docs` is `@ultimat3/core`'s `ERROR_DOCS_URL`, one wiki page for every code, because a code lives there in a table row and a table row has no anchor. Assert against `problemTypeFor` and `ERROR_DOCS_URL`, never against a copy of either string. An error's `meta` is **operator-only by default** and the document never carries it: that bag is where `bodyInvalid` keeps the excerpt the parser choked on, where the limiter keeps the internal key it promoted an anonymous caller to, and where core's `assert` keeps the rejected value. An app that wants a key on the wire declares it, per code, beside the status β€” and both declarations are needed, because a code with no status is an unclassified 5xx whose `meta` is blanked with its `cause`: An app code declared with `defineError` (`@ultimat3/core/page`) takes both in its one call β€” `status: 409, problemMeta: ['sessionId', 'title', 'state']`, `publicCause: true` β€” written to the same table. `registerProblemMeta` is the lower-level call, for a code whose class is not `defineError`'s: ```ts import { registerErrorStatus, registerProblemMeta } from '@ultimat3/http'; registerErrorStatus({ X_SESSION_CHECKOUT_BUSY: 409 }); registerProblemMeta({ X_SESSION_CHECKOUT_BUSY: ['sessionId', 'title', 'state'] }); // A 5xx whose cause is written for the caller, and may be shown in production: registerProblemMeta({ X_BILLING_DOWN: { publicCause: true } }); // Both at once: { keys: ['sessionId'], publicCause: true } ``` The document then carries `meta: { sessionId, title, state }` β€” the declared keys that are set, copied member by member (`__proto__` skipped at every depth), and nothing else off the error. It is all-or-nothing, as `issues` is: one value JSON cannot carry (a `Date`, a `bigint`, a class instance, a cycle) or a serialisation past `MAX_PROBLEM_META_BYTES` (4096) drops the whole member, because a document missing one declared key is a claim the server never made. Absent when no declared key is set β€” never `{}`. A framework-owned code is refused (`X_PROBLEM_META_INVALID`), as is `issues`, which has its own top-level home. `@ultimat3/action`'s typed client puts the member back on the rebuilt error's `meta`, so an island reads `error.meta.sessionId` where it used to run a regex over `cause`. A framework code's public keys are not an app's call: they are one reviewed table, `problem-meta-framework.ts`, held by its test to a 4xx code and keys an app's declaration could carry, none secret-shaped. One row, `As of 2026-11`: `X_METER_EXCEEDED` carries `meta: { meter, limit, resetsAt }` (its delay is the `Retry-After` header). ### Error classes Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or a job boundary the class is gone and the `code` is what survives β€” match on that. | Class | Code | Declared in | |---|---|---| | `HttpError` | any `HttpErrorCode` β€” `HTTP_ERROR_CODES` | `src/errors.ts` | ## Boundaries Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`, `@ultimat3/time` and `@ultimat3/db` β€” tiers 0 and 1, which is the whole rule. `db` for one value: `RATE_LIMIT_STORAGE`, the `x_rate_limit` table's storage declaration (`tableStorage`), rendered into its DDL and compared by drift. Authentication and policy evaluation arrive through `ServerHooks`, declared structurally, because `@ultimat3/policy` is a sibling tier. There is no plugin API: `Middleware` wraps a handler, the pipeline is everything else. `hooks.explainMiss(method, pathname)` is the same kind of seam for a request the router matched nothing for: the error it returns is thrown in place of `X_ROUTE_NOT_FOUND`, `undefined` keeps the plain miss. Synchronous, given only the request line, never asked about a matched route or a 405. `@ultimat3/action` answers it for a path that is one of its actions under a `pathStyle` this server does not serve (`X_CONTRACT_DRIFT`, 404). ## Supporting exports `As of 2026-11-02`. Types of `objectResponse`. | Name | What | |---|---| | `ServableObject` | what the answer needs before it opens anything. `StorageObject` is one | | `ObjectSource` | `{ object, open }`: `open(range?)` returns the body | | `ObjectRequest` | the one thing asked of the request, `header(name)`, so a test needs no `Request` | | `ObjectResponseOptions` | `cache` and `headers`. `cache` omitted, the route's declared `meta.cache` decides |