stitchkit 0.93.0 → 0.94.1

package/llms/server.5.txt

@@ -0,0 +1,250 @@
+# stitchkit/server — stitchkit docs slice, part 5 of 5
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/server.txt`: Guide: HTTP server  (docs/guide/server.md)
+- `llms/server.2.txt`: Guide: HTTP server  (docs/guide/server.md)
+- `llms/server.3.txt`: Guide: Realtime  (docs/guide/realtime.md)
+- `llms/server.4.txt`: Guide: Auth & errors  (docs/guide/auth-and-errors.md) · Guide: Multi-tenant  (docs/guide/multi-tenant.md)
+- `llms/server.5.txt`: API reference: `stitchkit/server`  (docs/api/reference.md)
+
+Also read:
+- see `llms/testing.txt` for the Testing & deployment guide
+
+==============================================================================
+# API reference: `stitchkit/server`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/server`
+
+Server-only. Builds and runs the HTTP server, and carries the server primitives.
+Also re-exports the error helpers from `stitchkit/contract`.
+
+### Server & handlers
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createServer` | function | build the router and start `Bun.serve` — [guide](../guide/server.md#createserver) |
+| `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
+| `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
+| `createImplement` | function | fix the handler context type once |
+| `createScopedImplement` | function | fix one scope→context map, then type every handler by its endpoint's effective scope; `.declare(contract)(handlers)` types without binding for the registry path, `.stream(scope, …)` covers streaming multipart — [guide](../guide/server.md#per-scope-handler-context--createscopedimplement) |
+| `ScopedHandlers` | _type_ | handler map typed per endpoint by its effective scope |
+| `ScopeContexts` | _type_ | scope → extra context fields map accepted by `createScopedImplement` |
+| `EffectiveScope` | _type_ | an endpoint's own `scope`, else its contract's group scope |
+| `createScopedImplementRegistry` | function | the registry form of `createScopedImplement` — one contract registry, handlers still typed per endpoint scope |
+| `ScopedRegistryHandlers` | _type_ | scoped handler registry inferred from a contract registry |
+| `ScopedImplementationRegistry` | _type_ | contract registry whose every group scope is a key of the scope map |
+| `StreamScope` | _type_ | the scope `createScopedImplement(...).stream` accepts for one endpoint |
+| `ExactScopedRegistryHandlers` | _type_ | fail-first scoped registry shape that rejects extra registry and endpoint keys |
+| `implementRegistry` | function | bind one exact contract registry to one exact backend handler registry |
+| `createImplementRegistry` | function | context-typed factory for `implementRegistry` |
+| `ImplementationRegistry` | _type_ | flat literal registry of concrete contracts accepted by `implementRegistry` |
+| `ImplementOptions` | _type_ | `{ onMissingHandler }` — how a binding treats a contract endpoint with no handler |
+| `MissingHandlerPolicy` | _type_ | `'throw'` (default) or `'stub'`, the dev-stand policy that mounts a `501` instead of refusing to start |
+| `KeyedServices` | _type_ | registry result: the mount-ordered `ServiceDef[]` carrying the same services under `.byKey` |
+| `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
+| `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
+| `staticRoute` | function | a raw route that serves a directory |
+| `serveFile` | function | serve a file with `Range` / `304` / `HEAD` — [guide](../guide/server.md#serving-files--range-requests) |
+| `parseByteRange` | function | parse a single `Range` header → range / `unsatisfiable` / `null` |
+| `isWithinDir` | function | path containment — `(root, resolvedTarget) => boolean`; call it before `serveFile` on any URL-derived path |
+| `weakETag` | function | a weak `ETag` from size + mtime |
+| `ServeFileOptions` | _type_ | options for `serveFile` |
+| `ByteRange` | _type_ | an inclusive `{ start, end }` byte range |
+| `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
+| `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
+| `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400 with structured `details.issues`, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
+| `errorCode` | function | the stable error code for a thrown value (side-effect-free — for log attribution) |
+| `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
+| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |
+| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) |
+| `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
+| `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
+| `BunServerConfig` | _type_ | config for `createServer` (Bun); `unix` listens on a unix domain socket (mutually exclusive with `port`/`hostname`) — [details](../guide/server.md#local-daemon-over-a-unix-socket) |
+| `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
+| `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
+| `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |
+| `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | HTTP/application grace, a separate WebSocket close-handshake bound, bounded forced-completion timeout, retry hint and optional external abort signal |
+| `ShutdownStatusSchema` / `ShutdownStatus` | schema / _type_ | live state and request/WebSocket counters; owned streams remain pending through source cleanup |
+| `ShutdownResultSchema` / `ShutdownResult` | schema / _type_ | clean/forced result with final counters, outer-force snapshots and `forcedWebSockets` including bounded realtime terminations |
+| `ShutdownStateSchema` / `ShutdownState` | schema / _type_ | managed lifecycle state machine |
+| `ServiceDef` | _type_ | the result of `implement` |
+| `MethodDef` | _type_ | one resolved endpoint inside a service |
+| `OperationIdentity` | _type_ | path-free service/action/scope/method identity shared by contract and native tool operations |
+| `Handlers` | _type_ | the typed handler map `implement` expects |
+| `LifecycleHooks` | _type_ | `onRequest` / pre-body `authorize` / `beforeHandle` / `afterHandle` / `onError` |
+| `composeLifecycleHooks` | function | compose HTTP lifecycle phases in declaration order with short-circuit/fallthrough semantics |
+| `AuthorizationContext` | _type_ | HTTP pre-body context with validated params, `input: undefined` and no files |
+| `RouteGroup` | _type_ | a prefixed group of services with its own hooks; matched errors try group `onError` → global `onError` → standard envelope, keeping the original error on fallback — [precedence](../guide/server.md#lifecycle-hooks) |
+| `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context and optional stable `serviceName` / `action` observability identity |
+| `RawRouteContext` | _type_ | the Bun-bound routing context a raw handler receives |
+| `BunServer` | _type_ | the `Bun.serve` instance type |
+| `ServerPassthrough` | _type_ | extra `Bun.serve` options |
+| `StitchLogger` | _type_ | the custom-logger interface |
+| `LoggingConfig` | _type_ | the `logging` object — `logger` / `format` / `skip` / `enrich` |
+| `LogFormat` | _type_ | `'pretty'` or `'json'` — what the built-in formatter writes |
+| `LogOutcome` | _type_ | how a request finished, as `enrich` sees it |
+| `FetchHandler` | _type_ | what `createHandler` returns, bound to `BunServer` here |
+| `FetchComposition` | _type_ | the Bun-bound `wrapFetch` seam |
+
+### Auth
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAuthHook` | function | one scope gate for HTTP `authorize` and tool `beforeHandle` — [guide](../guide/auth-and-errors.md#createauthhook) |
+| `composeAuthHooks` | function | route multiple canonical auth domains by owned scope and atomically commit their typed contributions |
+| `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a `defineErrors` vocabulary or a code map, plus an envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
+| `ErrorHookBase` / `ErrorHookMapping` | _type_ | common hook fields and the vocabulary-or-map branch accepted by `createErrorHook` |
+| `ErrorHookConfig` | _type_ | async observer/renderer config with partial `codeMap` and optional typed `unmappedCode` fallback |
+| `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
+| `createBearerResolver` | function | a bearer-token identity resolver |
+| `signJwt` | function | sign an HS256 JWT |
+| `VerifyJwtOptions` | _type_ | options for `verifyJwt` |
+| `verifyJwt` | function | verify an HS256 JWT |
+| `extractToken` | function | read a bearer token from header or cookie |
+| `deriveCodeChallenge` | function | PKCE — derive the `code_challenge` from a verifier |
+| `verifyPkce` | function | PKCE — verify a verifier against a stored challenge |
+| `AuthHook` | _type_ | the hook `createAuthHook` returns |
+| `AuthHookConfig` | _type_ | config for `createAuthHook` |
+| `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
+| `AuthRuleContribution` | _type_ | plain context fields a sync/async rule may contribute after authorizing |
+| `ScopedAuthRule` | _type_ | a rule plus its typed context contribution — `{ rule, inject? }` |
+| `AuthRules` | _type_ | the `rules` map: bare rules or scoped rules |
+| `RuleScopes` | _type_ | scope→context map derived from a `rules` object; `'public'` fields become optional |
+| `ScopedAuthHook` | _type_ | an auth hook carrying its derived scope map at the type level |
+| `AuthScopes` | _type_ | recover the derived map — `createScopedImplement<AuthScopes<typeof hook>>()` |
+| `ComposeAuthHooksConfig` | _type_ | ordered canonical hooks plus the optional explicit composite default scope |
+| `ComposedAuthScopes` | _type_ | scope→context map derived from every owner in a composed auth hook |
+| `BearerResolverConfig` | _type_ | config for `createBearerResolver` |
+| `JwtPayload` | _type_ | a decoded JWT payload |
+| `SignJwtOptions` | _type_ | options for `signJwt` (expiry, claims) |
+| `PkceMethod` | _type_ | the PKCE challenge method — `'S256' \| 'plain'` |
+
+### Cookies & CORS
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineCookie` | function | a typed cookie `get` / `getAll` / `set` / `clear` handle; `duplicates` names what `get` answers when two cookies share the name — [guide](../guide/auth-and-errors.md#cookies) |
+| `parseCookies` | function | parse a `Cookie` header to a record (the last of two same-named cookies wins) |
+| `parseCookieHeader` | function | parse a `Cookie` header to `[name, value]` pairs in header order, duplicates kept |
+| `serializeCookie` | function | build a `Set-Cookie` value |
+| `corsHeaders` | function | compute CORS response headers |
+| `corsPreflightResponse` | function | build a preflight `Response` |
+| `DEFAULT_CORS_ALLOW_HEADERS` | const | the default `Access-Control-Allow-Headers` (incl. `traceparent`) — extend it when overriding `cors.headers` |
+| `DEFAULT_CORS_EXPOSE_HEADERS` | const | the default `Access-Control-Expose-Headers` (incl. `Content-Disposition`, `ETag`, `Content-Range`, `X-Build-Id`) — extend it when overriding `cors.exposeHeaders`, or a cross-origin page loses the build id |
+| `CookieDef` | _type_ | the `defineCookie` handle |
+| `CookieOptions` | _type_ | cookie attributes, plus the `duplicates` read policy |
+| `CookieDuplicatesPolicy` | _type_ | `'last'` (default) / `'first'` / `'reject'` — `reject` yields `undefined` for two different values and the value when they agree |
+| `CorsConfig` | _type_ | CORS policy |
+
+### Realtime (server)
+
+| `bindSocketRegistry` | function | room membership and consistent replay over an already-authenticated realtime server |
+| `AuthorizedSocketRoom` / `SocketRegistry` / `SocketRegistryConnection` / `SocketRegistryOptions` / `SocketRegistryServer` / `SocketRegistrySnapshot` / `SocketReplayFrame` | _type_ | authorized room token, structural server boundary, replay frames and immutable registry state |
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createSocketIOServer` | function | the typed Socket.IO server — [guide](../guide/realtime.md#server--createsocketioserver) |
+| `bindRealtimeServer` | function | inferred, runtime-validated connection and broadcast boundary |
+| `RealtimeServer` | _type_ | validated broadcast and connection API inferred from a realtime contract |
+| `RealtimeServerConnection` | _type_ | one validated connection with raw socket access for auth and rooms |
+| `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer`; carries the handshake identity type through to `connection.raw.data` |
+| `SocketIORequestPolicy` | _type_ | runtime-neutral async-capable Web `Request` handshake admission policy |
+| `SocketIOServerConfig` | _type_ | config for `createSocketIOServer`; `handshake` is the typed identity gate — [guide](../guide/realtime.md#handshake-auth--cookie-or-token) |
+| `SocketIOPeerLoaders` | _type_ | `peers: { server, bunEngine }` — literal dynamic imports written in YOUR source, so a bundler puts the optional peers inside a self-contained artifact. Omit for the lazy default |
+| `SocketIOHandshakeConfig` | _type_ | the `handshake` gate — Zod `schema` over `handshake.auth` plus optional async `verify`; the result lands typed in `socket.data` |
+| `SocketIOServerHandle` | _type_ | typed Socket.IO server plus Bun mount fields and idempotent lifecycle |
+| `SocketIOServerLifecycle` | _type_ | non-generic Bun mount/shutdown portion accepted by `createServer` |
+| `composeWebSocketHandlers` | function | compose one Bun `websocket` from N lanes — a raw binary lane beside Socket.IO ([guide](../guide/realtime.md#raw-binary-lane-bun)) |
+| `webSocketLane` | function | a typed, cast-free lane for `composeWebSocketHandlers` |
+| `socketIoLane` | function | the Socket.IO catch-all lane for `composeWebSocketHandlers` |
+| `ComposedLane` | _type_ | a lane bridged to the loose data type |
+| `WebSocketLane` | _type_ | a typed lane (`{ match, handlers }`) |
+| `WebSocketComposeConfig` | _type_ | server-wide tuning for the composed handler |
+
+### Primitives
+
+| `createFileStateStore` | function | cross-process locked atomic JSON state updates over one Zod schema |
+| `FileStateStoreCorruption` / `FileStateStoreOptions` | _type_ | explicit corrupt-state report/policy and lock timing configuration |
+| Export | Kind | Summary |
+|--------|------|---------|
+| `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |
+| `streamingRoute` | function | a long-lived subscription route: idle timeout, heartbeat, opening flush, cancellation — [guide](../guide/server.md#long-lived-subscriptions) |
+| `ndjsonRoute` | function | `streamingRoute` framed as NDJSON |
+| `sseRoute` | function | `streamingRoute` framed as SSE |
+| `DEFAULT_STREAM_HEARTBEAT_MS` | const | 5000 — deliberately well under Bun's ten-second idle threshold |
+| `MultipartLifecycle` | _type_ | request-scoped rollback ownership for accepted streamed handles |
+| `MultipartResult` | _type_ | what `parseMultipart` returns |
+| `parseMultipart` | function | parse a typed buffered/streaming multipart descriptor — [guide](../guide/server.md#multipart) |
+| `defineMultipartStream` | function | bind typed streaming file receivers and a final endpoint handler |
+| `createMultipartStream` | function | fix one handler context type for streaming multipart endpoints |
+| `MultipartStreamConfig` | _type_ | receivers plus the context-typed handler accepted by the streaming builders |
+| `MultipartFileMetadata` | _type_ | field, filename, declared media type and optional declared size |
+| `MultipartReceiver` | _type_ | consumer-owned Web-stream storage receiver |
+| `MultipartReceiverResult` | _type_ | receiver value plus rollback cleanup |
+| `StreamingMultipartImplementation` | _type_ | receiver registry and handler shape inferred by `defineMultipartStream` |
+| `bindReleaseRefreshSignal` / `ReleaseRefreshSignalOptions` / `ReleaseRefreshSignal` | function / _type_ | a deploy signal (`SIGUSR2`, the one user-defined signal the process vocabulary has) refreshes a `stitchkit/release` marker, whose subscribers tell every socket; never throws at the signal — [guide](../guide/release.md) |
+| `bindProcessSignals` | function | bind `SIGINT` / `SIGTERM` to one managed `shutdown()` — one chain, force on a later signal, default disposition on the one after — [guide](../guide/testing-and-deployment.md#process-signals--bindprocesssignals) |
+| `ProcessSignalsOptions` | _type_ | config for `bindProcessSignals` |
+| `ProcessSignalsBinding` | _type_ | the `{ promise, close }` handle `bindProcessSignals` returns |
+| `ProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'shutdown' \| 'complete'` — which phase an `onError` report came from |
+| `SignalSource` | _type_ | injectable signal source — `process` by default |
+| `ProcessSignalName` | _type_ | signal names the binding accepts (owned, so the published types need no `@types/node`) |
+| `ShutdownTarget` | _type_ | the `shutdown`-only slice a binding needs — an interface, so a [composite target](../guide/testing-and-deployment.md#composite-shutdown-target--parallel-domain-drains) can drain several domains under one signal machine |
+| `createRateLimiter` | function | token-bucket rate limiting — [guide](../guide/server.md#rate-limiting) |
+| `createCache` | function | an in-memory TTL cache |
+| `CacheOptions` | _type_ | bounded-cache options, including the maximum retained entry count |
+| `cacheHeaders` | function | build a `Cache-Control` header |
+| `EventBusOptions` | _type_ | options for `createEventBus` |
+| `EventHandler` | _type_ | one event-bus subscriber |
+| `DefaultEventMap` | _type_ | the default event map — `Record<string, unknown>` |
+| `createEventBus` | function | typed in-process pub/sub — [guide](../guide/server.md#event-bus) |
+| `generateTraceId` | function | a fresh trace id |
+| `resolveTraceId` | function | the default per-request trace-id resolver |
+| `extractIp` | function | the caller IP from a request |
+| `isPublicIp` | function | whether an address belongs to the public internet; anything unparseable is not |
+| `resolveSocketIp` | function | the caller IP for a Socket.IO handshake (proxy-aware) |
+| `getClientInfo` | function | caller IP + user-agent |
+| `EventBus` | _type_ | the `createEventBus` handle |
+| `RateLimitConfig` | _type_ | config for `createRateLimiter` |
+| `ClientIpOptions` | _type_ | trusted-proxy config for `extractIp` / `resolveSocketIp` |
+| `StreamingRouteOptions` | _type_ | options for `streamingRoute` / `ndjsonRoute` / `sseRoute` |
+| `StreamingSourceContext` | _type_ | what a streaming source is given, including the cancellation `signal` |
+| `StreamingFormat` | _type_ | `'ndjson' \| 'sse'` |
+| `createUnixClientTransport` | function | owned Fetch-compatible Unix-socket transport on Bun and Node; every redirect stays on the socket — [guide](../guide/client.md#unix-domain-sockets) |
+| `UnixClientTransportConfig` | _type_ | absolute socket path plus request/header/connection/redirect bounds and an explicit bounded-or-streaming response policy |
+| `UnixClientTransport` | _type_ | `{ fetch, closed, close() }`; `close()` settles owned active work |
+| `UnixResponseBodyMode` | _type_ | `bounded \| streaming`; bounded is the 16 MiB cumulative default, streaming keeps pull-driven buffering without a lifetime total |
+| `UnixClientTransportError` | class | stable transport failure with `code` and dispatch certainty in `delivery` |
+| `UnixClientTransportErrorCode` | _type_ | finite Unix transport failure-code union |
+| `UnixClientDeliveryState` | _type_ | `not-dispatched \| possibly-dispatched \| response-received`; input to application retry policy, never an implicit retry |
+
+### OpenAPI
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `generateOpenApiDocument` | function | an OpenAPI 3.1 document from contract services — [ADR 0018](../decisions/0018-openapi-generation.md) |
+| `openApiRoute` | function | a `RawRoute` that serves the document as JSON |
+| `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
+| `OpenApiDocument` | _type_ | the generated document |
+| `OpenApiInfo` | _type_ | the spec `info` block |
+| `OpenApiServer` | _type_ | a spec `servers` entry |
+
+---
+
+### Trust fence
+
+Refuses a request whose `Host` is not a declared authority, at both admission points — the socket
+lane never reaches the hooks on either runtime.
+→ [ADR 0151](../decisions/0151-a-trust-fence-names-its-lanes-because-one-of-them-bypasses-hooks.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTrustFence` | function | `hooks` for the HTTP lane and `allowRequest` for the Socket.IO lane; a bare 403 that never says which rule refused |
+| `isLoopbackAddress` | function | whether an address is this machine — for the auth rule a privileged operation belongs in, not for the fence |
+| `TrustFence` / `TrustFenceConfig` / `TrustRefusal` / `TrustRefusalReason` / `TrustLane` | _types_ | the two admission points, the declared authorities, and why and where a request was refused |
+| `RouteGroupHooks` | _type_ | a route group's hooks — `LifecycleHooks` without `onRequest`, which runs before the group is known |
+
+---