stitchkit 0.26.0 → 0.28.0

package/llms-full.txt

@@ -242,6 +242,8 @@ export const users = defineContract({ prefix: 'users' }, {
 | `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
 | `idempotent` | no | safe to call twice with the same input (like `PUT`/`DELETE`); a retrying transport reads it — see [Realtime](./realtime.md#bring-your-own-transport) |
 | `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
+| `rawResponse` | no | the handler returns the `Response` itself — a download, a file, an SSE stream. HTTP-only, never a tool, no `output`. See [Raw-response endpoints](./server.md#raw-response-endpoints) |
+| `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
 
 ## `params` vs `input` vs `output`
 
@@ -313,8 +315,10 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
-Tool transports (`MCP`, `AGENT`) skip `multipart` endpoints automatically — a
-file upload is not a tool call.
+Tool transports (`MCP`, `AGENT`) skip two kinds of endpoint automatically:
+`multipart` (a file upload is not a tool call) and
+[`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
+a tool result cannot carry — it would serialize to `{}`).
 
 ## `toolName`
 
@@ -356,10 +360,22 @@ defineContract({ prefix: 'admin', meta: { public: true } }, {
 })
 ```
 
-One level deep — no deep merge, no way to unset an inherited key; declare it on
-the endpoint instead. `expose` deliberately has **no** contract-level equivalent
-(→ [ADR 0036](../decisions/0036-contract-level-meta.md)).
+One level deep — no deep merge. To **opt an endpoint out** of an inherited key,
+declare it with an explicit `undefined`:
+
+```ts
+defineContract({ prefix: 'leads', meta: { page: 'LEADS' } }, {
+  // Public website form inside an otherwise admin-gated contract:
+  submit: { method: 'POST', path: '/', desc: 'Submit', meta: { page: undefined } },
+  //                                       meta → { page: undefined } — gate off
+  list: { method: 'GET', path: '/list', desc: 'List' },   // meta → { page: 'LEADS' }
+})
+```
 
+The key stays *present* with value `undefined`, so read `meta` by **value**
+(`method.meta?.page`), never by key membership. `expose` deliberately has **no**
+contract-level equivalent
+(→ [ADR 0036](../decisions/0036-contract-level-meta.md)).
 
 `meta` is an **opaque, app-defined** bag the core attaches no meaning to — the
 same escape-hatch spirit as `scope` being a free string ([ADR 0002](../decisions/0002-generic-core.md) /
@@ -602,13 +618,49 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `rawRoutes` | non-contract routes (see below) |
 | `maxUploadBytes` | default multipart upload cap (bytes); per-route `EndpointDef.maxUploadBytes` overrides |
 | `port` / `hostname` | listen address — port defaults to `3000` |
-| `cors` | CORS policy — `{ origin, … }` |
+| `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }` |
 | `hooks` | lifecycle hooks (see below) |
-| `logging` | `true` for built-in request logs, or a custom `StitchLogger` |
-| `traceId` | override per-request trace-id resolution |
+| `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
+| `traceId` | override per-request trace-id resolution — may return `undefined` to fall back |
+| `wrapFetch` | compose wrappers around the finished handler (request context, audit) |
 | `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
 | `routes` / `development` / `bun` | passthrough to `Bun.serve` |
 
+### Request logging
+
+`logging: true` is shorthand for `logging: {}` — **any object turns logging
+on**, and the fields tune it:
+
+```ts
+createServer({
+  services,
+  logging: {
+    // Route lines into your stack instead of the built-in formatter.
+    logger: myLogger,
+    // Silence noise. Runs after the built-in filter (framework assets,
+    // favicon, preflights), so it can only quieten more.
+    skip: (_req, url) => url.pathname === '/health' || url.pathname.startsWith('/socket.io/'),
+    // Extra fields on the completion line.
+    enrich: (req, _url, { status }) => ({
+      userAgent: req.headers.get('user-agent') ?? undefined,
+      cacheable: status === 200,
+    }),
+  },
+})
+```
+
+Three things worth knowing about `enrich`: it reaches the **structured** output
+only (the production JSON line and a custom logger's `data`) — the development
+`←` line stays human-readable, so enriched fields are invisible in dev; it runs
+at close, when the request body is already consumed; and framework fields
+(`traceId`, `status`, `path`, …) always win a key collision. A throw in `skip`
+or `enrich` is swallowed — neither can fail a request.
+
+With an observability context active, the line also carries `userId`,
+`serviceName`, `action` and `dimensions` for free — and, like `enrich`'s fields,
+only in the structured output, never on the development `←` line. See
+[Observability](./observability.md).
+
 ## Route groups
 
 A group gives a set of services a shared path prefix and its own hooks:
@@ -722,6 +774,87 @@ createServer({
 Hooks see `RuntimeContext` (loose types); handlers see `HandlerContext` (typed).
 That split is deliberate — see [ADR 0003](../decisions/0003-two-context-types.md).
 
+## Raw-response endpoints
+
+An endpoint that answers with **bytes rather than data** — a PDF download, a
+file, an SSE stream — declares `rawResponse: true` and returns the `Response` itself:
+
+```ts
+// contract
+export const documents = defineContract(
+  { prefix: 'documents', scope: 'admin' },
+  {
+    download: {
+      method: 'GET', path: '/:id/pdf', desc: 'Download a document as a PDF',
+      params: z.object({ id: z.uuid() }),
+      rawResponse: true, contentType: 'application/pdf',
+    },
+  },
+)
+
+// handler — no guard on the first line; `beforeHandle` already ran
+download: (ctx) => serveFile(ctx.req, { path: pathFor(ctx.params.id),
+                                        filename: 'offer.pdf' }),
+```
+
+The request half is untouched: `params`, `input` and `multipart` parse and
+validate exactly as elsewhere, and the endpoint goes through `beforeHandle` — so
+the **auth gate applies without a guard in the handler**. Only the response is
+handed over, so there is no `output` schema, `afterHandle` is skipped (it
+transforms data; there is none) and the endpoint is HTTP-only: never an MCP
+tool, an agent tool or a CLI command. Declaring `output`, `toolName`, `ui`,
+`annotations` or a non-HTTP `expose` alongside `rawResponse` is a type error, and throws
+at definition time for a contract assembled at runtime.
+
+On the typed client the method resolves to the untouched `Response` — the
+filename lives in `Content-Disposition`, so a `Blob` alone would lose it:
+
+```ts
+const client = createClient(documents, http)
+const res = await client.download({ id })          // Response
+const name = res.headers.get('Content-Disposition')
+const blob = await res.blob()
+```
+
+Cross-origin, remember that those headers are readable only because CORS exposes
+them — see [`cors.exposeHeaders`](#serving-files--range-requests).
+
+**Raw response or [raw route](#raw-routes)?** Both hand the `Response` to your
+code. A raw-response *endpoint* stays in the contract: only its response is
+raw — it is still routed, gated, typed and documented like every other endpoint.
+A raw *route* is outside the contract entirely — no schemas, no auth gate, no
+client — which is what you want for an OAuth redirect or a webhook, and what you
+do not want for a download.
+
+⚠️ **Delete the old raw route when you move an endpoint into the contract.** Raw
+routes are matched **first**, so a leftover one keeps serving the bytes and the
+contract endpoint — with its auth gate — never runs. stitchkit warns at startup
+when a raw route shadows a contract route, naming both and the scope being
+bypassed; treat that warning as a bug.
+
+⚠️ **A path built from user input needs a containment check.** `staticRoute`
+enforces it; `serveFile` deliberately leaves it to the caller, so an endpoint
+serving `/:filename` must not pass it through:
+
+```ts
+import { isWithinDir, serveFile } from 'stitchkit/server'
+import { resolve } from 'node:path'
+
+const ROOT = resolve('./uploads')
+
+file: (ctx) => {
+  const target = resolve(ROOT, ctx.params.filename)
+  // `../../etc/passwd` resolves outside ROOT — reject before touching disk.
+  if (!isWithinDir(ROOT, target)) throw notFound('File not found')
+  return serveFile(ctx.req, { path: target })
+},
+```
+
+`implementRemote` proxies a raw-response endpoint like any other — the remote
+`Response` is forwarded verbatim. Request headers are not relayed, so a `Range`
+sent to the proxy does not reach the origin and the full body comes back.
+→ ADR 0038.
+
 ## Raw routes
 
 Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
@@ -815,6 +948,13 @@ It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
 and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
 pass `disposition` / `cacheControl` / `etag: false`, via the options.
 
+Cross-origin, the browser lets JavaScript read only the CORS-safelisted response
+headers. stitchkit therefore exposes the download-relevant ones by default
+(`Content-Disposition`, `Content-Range`, `ETag`, …) — without that a `fetch`-based
+download cannot recover the file's name. Override with `cors.exposeHeaders`
+(extend `DEFAULT_CORS_EXPOSE_HEADERS` rather than replacing it), or pass `[]` to
+emit none.
+
 `serveFile` takes an explicit `path` and trusts it — **the caller owns
 containment**. For a URL-derived path use `staticRoute` (which enforces it) or
 `isWithinDir` first. The byte-range parser is exported on its own as
@@ -836,11 +976,20 @@ focused helper — not a sub-framework.
 
 ### SSE streaming
 
+`streamSSE` returns a `Response`, so its endpoint declares
+[`rawResponse: true`](#raw-response-endpoints) — in a plain contract handler the response
+would be serialized into `{}` (that now fails loudly instead of shipping silently).
+
 ```ts
 import { streamSSE } from 'stitchkit/server'
 
+// contract
+stream: { method: 'GET', path: '/stream', desc: 'Stream tokens',
+          rawResponse: true, contentType: 'text/event-stream' },
+
+// handler
 async function* tokens() { yield 'a'; yield 'b' }
-return streamSSE(tokens())            // → a text/event-stream Response
+stream: () => streamSSE(tokens()),    // → a text/event-stream Response
 ```
 
 The client side is [`parseSSE`](./client.md#sse).
@@ -1202,8 +1351,14 @@ By default every endpoint is a tool on every transport. `expose` narrows it:
 { method: 'GET', path: '/lookup', desc: 'Look up a price', expose: ['MCP'] }     // MCP tool only
 ```
 
+Two kinds of endpoint are **never** tools, whatever `expose` says: a `multipart`
+upload (not a tool call), and a
+[`rawResponse`](./server.md#raw-response-endpoints) endpoint (its answer is
+bytes — a tool result cannot carry them, and it would reach the model as `{}`).
+Pin the full list with `listToolNames` in a snapshot test.
+
 `desc` is the tool description the model reads — write it for the model, not
-just for a human. A `multipart` endpoint is never a tool. The tool name defaults
+just for a human. The tool name defaults
 to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
 `get_widget`); set `toolName` for an explicit one. Derivation normalises every
 character outside `[a-zA-Z0-9_]` to `_` — the hyphen included, so `bot-status`
@@ -1633,7 +1788,10 @@ mountMcp(server, services, { hooks: createToolLogger() })
 ```
 
 Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
-structured `ToolCallRecord`. For a boot-time picture of what is exposed where,
+structured `ToolCallRecord`. That record carries `traceId` whenever an
+observability context is active, so a tool call made inside an HTTP request
+joins that request's log line on one key — see
+[Observability](./observability.md). For a boot-time picture of what is exposed where,
 `summarizeTransports(services)` returns per-transport operation counts (HTTP /
 MCP / AGENT / CLI) for you to log.
 
@@ -2671,6 +2829,16 @@ Bun.serve({
 })
 ```
 
+`createServer` and `serveNode` build their own `fetch`, so compose through
+**`wrapFetch`** instead — same order, the context outermost:
+
+```ts
+createServer({
+  services,
+  wrapFetch: (fetch) => wrapInRequestContext(audit.http(fetch)),
+})
+```
+
 Some fields are filled in late. Set them from the hooks that know:
 
 ```ts
@@ -2710,8 +2878,51 @@ application logs carry one id — by passing `getTraceId` as the resolver:
 createHandler({ /* … */ traceId: getTraceId })
 ```
 
+`getTraceId` returns `undefined` outside an active context, and the framework
+falls back to its own resolver — a trusted inbound `x-request-id` / `x-trace-id`,
+else a fresh id — so the line never carries the string `"undefined"`.
+
 `getRequestContext()` / `getTraceId()` then return the active values from
 anywhere in the call — stamp `getTraceId()` onto every line your logger writes.
+The **request log picks the context up on its own**: with a context active, each
+completion line carries `userId`, `serviceName`, `action` and `dimensions`
+without any configuration.
+
+⚠️ In the **structured** output only — the production JSON line and a custom
+`logger`'s `data`. The development `←` line is a line to read, not a record to
+query, and never carries them (nor `enrich`'s fields). On `logging: true` in
+development you will see no difference; check with `NODE_ENV=production` or a
+custom `logger`.
+
+### Correlating with a reverse proxy
+
+Every response the stitchkit handler produces carries the resolved id as
+**`x-request-id`**. With `cors` configured it is in the default
+`Access-Control-Expose-Headers`, so a browser client can read it and quote it in
+a bug report. Note the deliberate asymmetry: inbound the id may arrive as
+`X-Trace-Id` *or* `X-Request-Id`; outbound there is one name and no alias.
+
+Log the same id from nginx and the two logs join on one key. `log_format` and
+`map` are `http {}`-context directives — put the block there, not inside
+`server {}`:
+
+```nginx
+log_format  stitch  '$remote_addr $status $request_time rid=$rid "$request"';
+
+# Fall back to nginx's own id for responses stitchkit never produced — Bun's
+# native `routes`, a throwing `onRequest` (which escapes before any response
+# exists), a redirect whose headers are immutable.
+map $upstream_http_x_request_id $rid {
+    ""      $request_id;
+    default $upstream_http_x_request_id;
+}
+
+access_log /var/log/nginx/access.log stitch;
+```
+
+`grep rid=<id>` across both logs then reconstructs the whole request. Tool calls
+join too: `createToolLogger`'s record carries `traceId`, so an MCP or agent call
+made inside a request lines up with it.
 
 ### Trace context
 
@@ -2957,10 +3168,13 @@ Notes for a Node host:
 
 - **CORS** — set `cors.origin` to your real front-end origin(s). Do not ship
   `origin: '*'` with credentials.
-- **Logging** — `logging: true` for built-in request logs, or pass a
-  `StitchLogger` to route them into your logging stack.
+- **Logging** — `logging: true` for built-in request logs, or
+  `logging: { logger, skip, enrich }` to route them into your logging stack,
+  drop probe noise and add your own fields.
 - **Trace ids** — override `traceId` to reuse an id your platform already
-  assigns, so request logs and application logs share one id.
+  assigns, so request logs and application logs share one id. Every response
+  carries it as `x-request-id`; log `$upstream_http_x_request_id` at the proxy
+  to join the two logs.
 - **Rate limiting** — `createRateLimiter` in `onRequest` for a global limit;
   per-route limits belong in `beforeHandle`.
 - **Auth** — a `createAuthHook` `beforeHandle` guards every transport at once;
@@ -3366,6 +3580,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `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 |
@@ -3389,6 +3604,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `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` / `skip` / `enrich` |
+| `LogOutcome` | _type_ | how a request finished, as `enrich` sees it |
+| `FetchHandler` | _type_ | what `createHandler` returns |
+| `FetchComposition` | _type_ | the `wrapFetch` seam shared by the servers |
 
 ### Auth
 
@@ -3422,6 +3641,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `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`) — extend it when overriding `cors.exposeHeaders` |
 | `CookieDef` | _type_ | the `defineCookie` handle |
 | `CookieOptions` | _type_ | cookie attributes |
 | `CorsConfig` | _type_ | CORS policy |

package/llms.txt

@@ -7,7 +7,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 ## Guide
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app
 - [Contracts](https://github.com/max-listov/stitchkit/blob/master/docs/guide/contracts.md): every endpoint field — method, path, params/input/output, scope, expose, meta, multipart
-- [HTTP server](https://github.com/max-listov/stitchkit/blob/master/docs/guide/server.md): createServer/createHandler, implement, lifecycle hooks, raw routes + helpers, scopePrefixes, serveFile, primitives
+- [HTTP server](https://github.com/max-listov/stitchkit/blob/master/docs/guide/server.md): createServer/createHandler, implement, lifecycle hooks, raw routes + raw-response endpoints + helpers, scopePrefixes, serveFile, primitives
 - [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/index-khwedj16.js

@@ -1,40 +0,0 @@
-// src/observability/trace.ts
-var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
-function randomHex(bytes) {
-  const arr = new Uint8Array(bytes);
-  crypto.getRandomValues(arr);
-  let hex = "";
-  for (const byte of arr)
-    hex += byte.toString(16).padStart(2, "0");
-  return hex;
-}
-function createTraceContext() {
-  return { traceId: randomHex(16), spanId: randomHex(8) };
-}
-function parseTraceparent(header) {
-  if (!header)
-    return null;
-  const match = TRACEPARENT_RE.exec(header.trim());
-  if (!match?.[1] || !match[2])
-    return null;
-  const traceId = match[1].toLowerCase();
-  const parentSpanId = match[2].toLowerCase();
-  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
-    return null;
-  return { traceId, spanId: randomHex(8), parentSpanId };
-}
-function formatTraceparent(ctx) {
-  return `00-${ctx.traceId}-${ctx.spanId}-01`;
-}
-function resolveTraceContext(req) {
-  return parseTraceparent(req.headers.get("traceparent")) ?? createTraceContext();
-}
-function childSpan(parent) {
-  return {
-    traceId: parent.traceId,
-    spanId: randomHex(8),
-    parentSpanId: parent.spanId
-  };
-}
-
-export { createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan };