stitchkit 0.93.0 → 0.94.1

package/llms/server.2.txt

@@ -0,0 +1,361 @@
+# stitchkit/server — stitchkit docs slice, part 2 of 5
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+> Continues in `llms/server.3.txt`.
+
+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
+
+==============================================================================
+# Guide: HTTP server  (docs/guide/server.md)  (continued)
+==============================================================================
+
+## Server primitives
+
+`stitchkit/server` also exports the primitives most APIs need. Each is a small,
+focused helper — not a sub-framework.
+
+| Helper | Does |
+|--------|------|
+| `serveFile()` | serve a file with `Range` / `304` / `HEAD` (media seeking) |
+| `streamSSE()` | turn an `AsyncGenerator` into a Server-Sent-Events `Response` |
+| `ndjsonRoute()` / `sseRoute()` | a **long-lived** subscription route, with the whole checklist |
+| `parseMultipart()` | parse a typed buffered/streaming multipart descriptor |
+| `createRateLimiter()` | per-key token-bucket rate limiting |
+| `createCache()` + `cacheHeaders()` | in-memory TTL cache; `Cache-Control` builder |
+| `createEventBus<EventMap>()` | typed in-process pub/sub |
+
+### Contract-first streams
+
+Use an endpoint `stream` descriptor when the item schema and completion belong
+to the contract, rather than handing an application-owned `Response` to
+`rawResponse`:
+
+```ts
+const Item = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('line'), text: z.string() }),
+  z.object({ kind: z.literal('complete'), count: z.number().int() }),
+])
+
+const reports = defineContract({ prefix: 'reports' }, {
+  watch: {
+    method: 'GET', path: '/:id/watch', desc: 'Watch one report',
+    params: z.object({ id: z.string() }),
+    stream: {
+      item: Item,
+      format: 'ndjson',
+      maxFrameBytes: 64 * 1024,
+      terminal: z.object({ kind: z.literal('complete') }).loose(),
+    },
+  },
+})
+
+const service = implement(reports, {
+  watch: async function* ({ params, signal }) {
+    yield { kind: 'line', text: `starting ${params.id}` }
+    if (signal.aborted) return
+    yield { kind: 'complete', count: 1 }
+  },
+})
+```
+
+The handler return is inferred as `AsyncIterable<z.output<typeof Item>>`; an
+invalid JavaScript producer is rejected before its value reaches the wire. Data,
+safe errors and normal end use a framework envelope. The default encoded frame
+limit is 256 KiB. `format` defaults to `ndjson`; `heartbeatMs` defaults to five
+seconds; `idleTimeoutSeconds` defaults to disabled; `lifetimeMs` is optional.
+
+After headers, HTTP status can no longer report failure, so the stream sends a
+normalized code and never the raw internal exception. Normal producer completion
+sends an explicit `end`; when `terminal` is declared, at least one item must
+match it. Request abort and client iterator return abort `signal`, including a
+source waiting in `next()` or suspended at a yielded item.
+
+Contract streams are HTTP-only and cannot declare `output`, `rawResponse`,
+multipart or tool exposure. They do not provide replay, cursors or durable
+subscriptions. Keep using `streamingRoute` for an application-owned protocol and
+`rawResponse` for arbitrary response bodies. → ADR 0117.
+
+For an existing schema-owned NDJSON protocol, opt into direct item frames and
+terminal-owned completion:
+
+```ts
+stream: {
+  item: Item,
+  framing: 'item',
+  completion: 'terminal',
+  terminal: z.object({ kind: z.literal('complete') }).loose(),
+  finalLine: 'require-newline',
+}
+```
+
+`item` framing is NDJSON-only and requires terminal completion. The server
+writes each validated item directly, stops the source after the terminal and
+never reads trailing producer values. Because this wire has no framework error
+envelope, any producer/lifetime failure before terminal closes the response;
+the typed client reports `STREAM_TERMINAL_MISSING`. The terminal item therefore
+proves success without weakening safe post-header failure semantics. Existing
+streams retain the envelope and explicit end frame by default. → ADR 0126.
+
+### 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' }
+stream: () => streamSSE(tokens()),    // → a text/event-stream Response
+```
+
+The client side is [`parseSSE`](./client.md#sse).
+
+`streamSSE` is for a stream that **finishes** — a completion, a job's output.
+For one that stays open, see below.
+
+### Long-lived subscriptions
+
+`streamSSE` assumes the generator keeps producing. A **subscription** is the
+opposite: silence is its normal state, and three unrelated things have to be
+right or it breaks without saying anything. (Measured: with a heartbeat under
+the threshold, either of the first two alone keeps an in-process connection
+alive — the first earns its place against what a heartbeat cannot reach, an
+intermediary applying its own idle rule.)
+
+1. **The generic idle timeout has to go.** Without `server.timeout(req, 0)` Bun
+   resets the connection after ten seconds — a healthy connection severed on a
+   schedule, precisely because the subscriber had nothing to be told.
+2. **Something has to be on the wire.** Even with the timeout gone,
+   intermediate proxies are under no obligation to hold a connection carrying no
+   bytes.
+3. **The headers have to leave at open.** A runtime sends nothing until the body
+   produces a byte, so the consumer's `fetch` does not return. "Subscribed and
+   silent" then looks exactly like "not answering", and there is nothing to
+   inspect because there is no response yet.
+
+`ndjsonRoute` / `sseRoute` do all three, and close the source when the consumer
+goes away:
+
+```ts
+import { ndjsonRoute } from 'stitchkit/server'
+
+const events = ndjsonRoute({
+  path: '/events/subscribe',
+  heartbeatMs: 5_000,                       // default; keep it well under 10s
+  source: async function* (request, { signal }) {
+    for await (const event of subscribe({ signal })) yield event
+  },
+})
+
+createServer({ port: 3000, rawRoutes: [events] })
+```
+
+The client half is [`parseNDJSON`](./client.md#ndjson) — and the keep-alive
+frame is an **empty line**, so "blank lines are skipped" is part of the
+documented contract rather than an agreement between two halves of one project.
+`sseRoute` frames the same source as SSE and is read by `parseSSE` unchanged.
+
+**Honour `context.signal`.** It is the one part the route cannot do for you, and
+the reason is worth knowing: an async generator serialises its requests, so
+`iterator.return()` issued while a `next()` is in flight is *queued behind it*.
+A subscription is in `next()` almost always, so the close would wait for an
+event that may never come. The signal is aborted the moment the consumer
+disconnects — through either route, a request abort or a stream cancel — and a
+source that waits on it stops at once. (`iterator.return()` is still called; it
+closes a source suspended at a `yield`.)
+
+A failure part-way through arrives as a final frame carrying the framework
+error envelope, normalised — once the headers are gone there is no status left
+to send, and an internal message must not reach the wire raw.
+
+### Multipart
+
+The contract owns one descriptor for buffered and streaming delivery:
+
+```ts
+const uploads = defineContract({ prefix: 'uploads' }, {
+  create: {
+    method: 'POST', path: '/', desc: 'Upload media',
+    input: UploadMetadataSchema,
+    output: UploadedMediaSchema,
+    multipart: {
+      maxRequestBytes: 220 * 1024 * 1024,
+      maxFieldBytes: 64 * 1024,
+      files: {
+        cover: { required: false, maxBytes: 10 * 1024 * 1024, contentTypes: ['image/*'] },
+        media: { multiple: true, maxFiles: 4, maxBytes: 50 * 1024 * 1024 },
+      },
+    },
+  },
+})
+```
+
+Buffered delivery is the default. Each file becomes a Web `File`; single,
+optional and multiple cardinality is inferred on `ctx.files`. The request cap
+defaults to **25 MB** when omitted. The parser measures actual bytes including
+boundaries and headers instead of trusting `Content-Length`; per-file bytes,
+file count, text-field bytes and declared MIME policy are enforced while
+reading. Text fields remain strings until the endpoint's Zod `input` parses
+them.
+
+For large files, set `delivery: 'stream'` and define receivers. A receiver gets
+a Web `ReadableStream<Uint8Array>` and writes directly to consumer-owned
+storage; Stitchkit holds only bounded parser state:
+
+```ts
+const streamingUploads = defineContract({ prefix: 'uploads' }, {
+  create: {
+    method: 'POST', path: '/', desc: 'Upload media',
+    input: UploadMetadataSchema,
+    output: UploadedMediaSchema,
+    multipart: {
+      delivery: 'stream',
+      maxRequestBytes: 260 * 1024 * 1024,
+      files: { media: { maxBytes: 250 * 1024 * 1024, contentTypes: ['video/*'] } },
+    },
+  },
+})
+
+const service = implement(streamingUploads, {
+  create: defineMultipartStream(streamingUploads.endpoints.create, {
+    files: {
+      media: async ({ metadata, stream, signal }) => {
+        const stored = await storage.write({ metadata, stream, signal })
+        return {
+          value: stored,
+          cleanup: () => storage.remove(stored.key),
+        }
+      },
+    },
+    handler: ({ input, files }) => mediaService.attach(input, files.media),
+  }),
+})
+```
+
+Receivers run sequentially in multipart order. A multiple receiver runs once
+per part and the handler gets an ordered value array. `cleanup` is registered
+as soon as a receiver materialises external state. Disconnect, size/policy
+failure, a later receiver/text validation failure or handler failure rolls
+accepted handles back exactly once in reverse order. After handler success,
+ownership transfers to the application.
+
+Authorization always completes before the multipart parser or any receiver is
+started. The receiver signal is tied to the request abort. The core does not
+provide filesystem/S3 adapters, retries, antivirus or a distributed
+storage/database transaction; those policies belong to the application.
+
+`parseMultipart(req, descriptor, fieldsSchema?, receivers?)` is also exported
+for a custom raw transport. It uses the same descriptor and returns
+`{ files, fields, rollback }`; contract endpoints should prefer the automatic
+dispatcher path.
+
+Both delivery modes preserve UTF-8 `filename` metadata, including browser `FormData` names. For
+interoperability, a UTF-8 percent-encoded `filename*` parameter takes precedence over `filename`;
+unsupported charsets or malformed encoding are rejected rather than falling back silently. Literal
+percent sequences in ordinary `filename` are not decoded. Filenames remain untrusted metadata,
+not safe filesystem paths. Part headers have a 64 KiB byte limit, are case-insensitive and reject
+duplicates, folding, invalid header names and control characters. Disposition parameters reject
+duplicates and unsafe field names; declared part sizes must be nonnegative safe decimal integers.
+
+### Rate limiting
+
+```ts
+import { createRateLimiter } from 'stitchkit/server'
+
+const limiter = createRateLimiter()
+// in onRequest:
+if (!limiter.check(ip, { window: 60_000, max: 60 })) {
+  return new Response('Too many', { status: 429 })
+}
+```
+
+### Event bus
+
+```ts
+import { createEventBus } from 'stitchkit/server'
+
+const bus = createEventBus<{ 'user.created': { id: string } }>()
+bus.on('user.created', ({ id }) => sendWelcome(id))
+bus.emit('user.created', { id: '1' })
+```
+
+A typed in-process pub/sub — decouple a handler from the side effects of its
+write without reaching for an external queue.
+
+## OpenAPI
+
+`generateOpenApiDocument` builds an OpenAPI 3.1 document straight from the
+contracts — the contract *is* the spec, no decorators or hand-maintained
+annotations (→ ADR 0018). `openApiRoute` serves it as a raw route:
+
+```ts
+import { generateOpenApiDocument, openApiRoute } from 'stitchkit/server'
+
+const doc = generateOpenApiDocument({
+  info: { title: 'My API', version: '1.0.0' },
+  services: [users, orders],
+})
+createServer({ services: [users, orders], rawRoutes: [openApiRoute('/openapi.json', doc)] })
+```
+
+Only HTTP-exposed methods appear (an MCP/agent-only tool is skipped).
+
+OpenAPI 3.1 has no standard multi-segment path parameter. For a contract path
+ending in a named wildcard such as `/*filePath`, Stitchkit keeps the literal
+runtime path, omits `filePath` from the
+standard `in: path` parameter list, and emits
+`x-stitchkit-trailing-wildcard` on the operation with its parameter name,
+schema and semantics. A generic OpenAPI client therefore cannot invent
+catch-all expansion; use Stitchkit's typed client or teach the generator that
+extension.
+
+### Curating the spec — `includeMethod`
+
+To publish a **subset** — a public spec that advertises only some methods
+without revealing the rest — pass `includeMethod`. It keeps the core generic:
+*you* decide the policy, filtering on anything the method carries. The
+recommended declarative allowlist marks endpoints with the existing `meta`
+passthrough and keeps those:
+
+```ts
+// contract — declarative, one source of truth
+getBalance: { method: 'GET', path: '/balance', desc: '…', scope: 'account',
+              meta: { public: true }, output: BalanceSchema }
+
+// generation — the app's policy
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+})
+```
+
+An excluded method's whole entry — path *and* every schema inlined within it —
+is simply never emitted, so nothing about a hidden endpoint leaks.
+
+> **The filter advertises; it does not authorize.** Hiding a method from the
+> spec does **not** protect it — it is still callable, and the auth `scope` gate
+> is the only thing guarding it. And because `openApiRoute` closes over the
+> document you hand it, the filter only matters if you feed it a filtered one:
+> serve **two** documents — a full internal spec and a filtered public spec on
+> separate routes — never one unfiltered `openApiRoute` on a public path.
+
+```ts
+const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind auth
+const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
+```