stitchkit 0.60.1 → 0.61.0

package/llms-full.txt

@@ -1515,6 +1515,7 @@ focused helper — not a sub-framework.
 |--------|------|
 | `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 |
@@ -1540,6 +1541,64 @@ 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:
@@ -2172,7 +2231,42 @@ for await (const event of parseSSE(res)) {
 }
 ```
 
-The server side is [`streamSSE`](./server.md#sse-streaming).
+The server side is [`streamSSE`](./server.md#sse-streaming), or
+[`sseRoute`](./server.md#long-lived-subscriptions) for a subscription that stays
+open.
+
+## NDJSON
+
+`parseNDJSON` reads a newline-delimited JSON body — the client half of
+[`ndjsonRoute`](./server.md#long-lived-subscriptions):
+
+```ts
+import { parseNDJSON } from 'stitchkit'
+
+const subscription = new AbortController()
+const res = await fetch('/api/events/subscribe', { signal: subscription.signal })
+for await (const event of parseNDJSON(res)) {
+  console.log(event)
+}
+
+// ...to unsubscribe:
+subscription.abort()
+```
+
+**Use the `AbortController` for a subscription.** Leaving the loop with `break`
+cancels the body, and on a stream that ends that is enough — but it is not a
+reliable way to tell the *server* you are gone: measured against Bun today, the
+source stayed alive for seconds after a client-side cancel. Aborting the request
+reaches [`context.signal`](./server.md#long-lived-subscriptions) on the other
+end at once, which is what actually ends the work.
+
+**Blank lines are skipped**, and that is the contract rather than a
+convenience: a long-lived stream must send something while it is idle or
+intermediaries drop it, and an empty line is the natural pulse for this framing.
+Writing the rule down on both sides is what stops it being a verbal agreement —
+the server's keep-alive and the reader's skip are one decision with two
+implementations. A frame that is not valid JSON goes to `onParseError` rather
+than throwing, so one bad line does not end the subscription.
 
 
 ==============================================================================
@@ -3939,6 +4033,71 @@ may retain lifecycle `ready`, but snapshot health is `degraded`, never
 
 Readiness is not hidden polling. A resource reports health changes through its
 lifecycle context; the application decides when a database/provider probe runs.
+
+**A `reportHealth` call inside `start` is kept.** A resource that says nothing
+is assumed healthy once it is ready; one that reports its own health has already
+answered the question, and the answer stands. (It used to be overwritten — and
+the example above hides that, because `healthy` is the same value that
+overwrote it.)
+
+**A resource is required unless you write `required: false`.** That default is
+what makes the next sentence bite.
+
+**Readiness requires every required resource to be healthy**, so "ready but
+degraded" is unreachable for a required resource by construction: an
+application whose required resource reports anything but `healthy` refuses to
+start, and says which resource and in what state. The refusal distinguishes the
+two ways to get there — a resource that was never healthy is pointed at
+`required: false`; one that was healthy and stopped is pointed at
+`onResourceFailure`. A resource that is *expected* to start
+degraded — up, but still dialling something external — belongs behind
+`required: false`, where it keeps its own health and does not gate the
+application:
+
+```ts
+defineManagedResource({
+  id: 'dialling',
+  required: false,
+  start: ({ reportHealth }) => { reportHealth('degraded') },
+})
+```
+
+An optional resource reporting non-healthy does not gate readiness, but it does
+move the application **aggregate** to `degraded` — which a readiness endpoint
+mapping `degraded` to non-200 will notice.
+
+If startup fails, every resource that was already started is closed in reverse
+order. The rollback runs **one** phase — `close` — not the five a real shutdown
+runs, and `close` receives the same deadlines a shutdown would give it, so a
+server drains what is in flight instead of aborting it.
+
+Those deadlines come from the application's declared budget, and it is worth
+knowing what they cost. With nothing in flight the rollback returns at once: a
+grace period is a ceiling, not a sleep. With something in flight it waits for
+it — that is the point — and with something that **never finishes**, a hung
+upstream or a client that ignores a close frame, it waits out the whole budget
+before forcing. Under the default 30s+5s that turns a failed `start()` that used
+to reject in milliseconds into one that can take 35 seconds to reject.
+
+An application that would rather hear about a broken start immediately says so,
+in the one place both stopping paths read:
+
+```ts
+createApplication({
+  id: 'app',
+  resources,
+  // Applies to `shutdown()` called with no options AND to the rollback of a
+  // failed `start()`, which has no call site of its own to be told.
+  shutdown: { gracePeriodMs: 5_000, forceTimeoutMs: 1_000 },
+})
+```
+
+The budget is a real bound, not just a number handed to each resource: a `close`
+that never returns is abandoned when the budget runs out, reported as a `close`
+failure, and the startup error stays the `cause` of the `AggregateError` that
+`start()` rejects with. Without that, one unresponsive resource could keep a
+failed startup from ever reporting why it failed.
+
 A required long-lived completion that rejects after startup makes readiness
 false and health unhealthy. Stitchkit records the failure but does not restart
 the resource or process.
@@ -4757,36 +4916,64 @@ const realtimeContract = defineRealtimeContract({
 })
 ```
 
-The original `z.ZodError` is retained as `RealtimeRejectedEvent.error.cause`.
-Because event arguments are a tuple, the first payload's `v` path is
-`[0, 'v']` (not `['v']`):
+A frame that fails this check is **refused, and the sender is told so** — when
+the event has an acknowledgement. `request()` rejects with
+`RealtimeRequestRejectedError`, immediately, carrying the peer's own issues:
 
 ```ts
-import type { RealtimeRejectedEvent } from 'stitchkit'
-import { z } from 'zod'
+import { RealtimeRequestRejectedError } from 'stitchkit'
 
-function isProtocolGenerationMismatch(rejected: RealtimeRejectedEvent): boolean {
-  const cause = rejected.error.cause
-  if (!(cause instanceof z.ZodError)) return false
-  const first = cause.issues[0]
-  return first?.code === 'invalid_value'
-    && first.path.length === 2
-    && first.path[0] === 0
-    && first.path[1] === 'v'
+try {
+  await socket.request('replicate', message, { timeoutMs: 5_000 })
+} catch (error) {
+  if (error instanceof RealtimeRequestRejectedError) {
+    // reason: 'invalid-arguments'; issues: [{ path: '0.v', code: 'invalid_value', … }]
+    if (error.issues?.some((issue) => issue.path === '0.v')) schedulePeerUpgrade()
+    else reportMalformedRealtimePayload(error)
+  }
 }
+```
 
-const socket = createRealtimeClient(realtimeContract, {
-  url,
-  onRejected: (rejected) => {
-    if (isProtocolGenerationMismatch(rejected)) schedulePeerUpgrade()
-    else reportMalformedRealtimePayload(rejected)
+`path` is `'0.v'` and not `'v'` because event arguments are a tuple: index `0`
+is the first payload. The issues are already flattened by Stitchkit's own
+normaliser, so telling "wrong generation" from "malformed payload" is one
+comparison rather than an inspection of a `ZodError`'s internals.
+
+The receiving side still reports it locally through `onRejected` — a refusal is
+now visible on **both** ends rather than only where it happened.
+
+**Two limits, both real.** A **fire-and-forget** event has no acknowledgement
+channel, so its refusal stays local: the sender learns nothing, and no
+convention in the payload can change that. And an event the receiver's contract
+does not contain has no listener at all, so there is nothing on that side to
+answer with — adding an event is not a change a generation field can announce.
+
+### Where protocol identity belongs
+
+For a distributed pair whose planes are mostly fire-and-forget, compare
+identity **at the handshake** instead, where a mismatch is refused before the
+first frame is interpreted and both ends see it at once. The typed handshake is
+already the place:
+
+```ts
+const handshake = {
+  schema: z.object({ token: z.string(), protocol: z.string() }),
+  verify: (auth) => {
+    if (auth.protocol !== PROTOCOL_IDENTITY) return null   // refused, with a reason
+    return { subject: verifyToken(auth.token) }
   },
-})
+}
 ```
 
-A generation mismatch means “upgrade the peer”; another schema rejection means
-“fix the producer or payload”. This stays an application convention, not a core
-API: only the application knows which field denotes protocol compatibility.
+The client sends it as `auth`, and a rejection reaches `onConnectError` with
+`terminal: true` — distinguishable in a log from a bad token, so a half-rolled
+deployment reads as a half-rolled deployment and not as an access problem.
+
+What that identity *is* remains the application's decision — a build version, a
+contract hash, a protocol generation. Stitchkit does not compare it for you
+(→ ADR 0002); it gives the place where the comparison happens before any frame
+is interpreted, and it makes the per-frame alternative honest by letting its
+refusals be seen.
 
 ## Server — `createSocketIOServer`
 
@@ -7422,6 +7609,143 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.61.0
+
+Three behaviour changes between versions. None moves an export — the surface is
+strictly additive — and all three change what a running system does, which is
+what this heading is for.
+
+### A failed `start()` now drains before it rejects
+
+The rollback of a failed startup used to close every resource with a zero
+budget: it returned almost at once, by severing requests the server had already
+accepted. It now spends the application's shutdown budget, so a request already
+in flight is answered rather than killed.
+
+**What to check.** Nothing, if a failed startup has nothing in flight — the
+rollback still returns immediately. The case to think about is a request that
+never finishes: a hung upstream, a client ignoring a close frame, a streaming
+subscription. Under the default 30s grace and 5s force, a `start()` that used to
+reject in milliseconds can now take 35 seconds to reject.
+
+If a fast failure matters more than draining — a supervisor waiting to restart,
+a boot check in CI — declare a smaller budget. The same field is the default for
+`shutdown()` with no options, so this is one decision, not two:
+
+```ts
+// before
+createApplication({ id: 'app', resources })
+
+// after
+createApplication({
+  id: 'app',
+  resources,
+  shutdown: { gracePeriodMs: 5_000, forceTimeoutMs: 1_000 },
+})
+```
+
+The budget is a real bound: a `close` that never returns is abandoned when it
+runs out and reported as a `close` failure, and the startup error remains the
+`cause` of the `AggregateError` `start()` rejects with. → ADR 0107
+
+### A refused realtime frame now answers its sender
+
+A frame that fails the receiver's `args` schema used to be dropped where it
+landed. If the event carries an acknowledgement, the receiver now answers it
+with a reserved envelope and the sender's `request()` rejects at once with
+`RealtimeRequestRejectedError`. → ADR 0106
+
+**What to check before you upgrade one half of a distributed pair.** Look at the
+`ack` schemas on the OLDER peer:
+
+```ts
+// safe: a contract-first acknowledgement refuses the envelope, so the older
+// peer raises RealtimeRequestInvalidAcknowledgementError at once instead of
+// waiting out its deadline. Different error, still an error, and sooner.
+ack: z.object({ stored: z.boolean() })
+
+// NOT safe: a schema that validates nothing accepts the refusal AS A VALUE.
+// The older peer reads a refusal as a successful acknowledgement — silently.
+ack: z.unknown()
+ack: z.looseObject({})
+```
+
+If any acknowledgement on the older side is permissive, tighten it before the
+rollout, or upgrade both halves together.
+
+Also: the receiver now invokes the peer's raw acknowledgement callback for a
+refused frame, including when the peer is a plain Socket.IO client. That
+callback previously could not run on a refused frame and now can.
+
+`RealtimeRejectedEvent['reason']` gained `'rejected-by-peer'`. If you `switch`
+over it exhaustively with an `assertNever` default, that stops compiling — add
+the case.
+
+### Two smaller behaviour changes, easy to miss
+
+**`streamSSE`'s `cancel` no longer awaits the generator.** Teardown is now
+unordered relative to request completion. If your generator releases a resource
+in `return()`/`finally` — a temp file, a pooled connection — and anything
+downstream assumed that had finished by the time the response settled, it no
+longer has. Release in the generator's own `finally` and do not depend on the
+ordering.
+
+**A `socket.io-client` peer that cannot load no longer kills the process.** With
+`onConnectError` configured, the failure is delivered there with
+`terminal: true` instead of crashing. If your handler logs and moves on, you now
+have a live process whose client will never connect, where a supervisor used to
+restart it. Treat `terminal: true` as fatal if that is what you want.
+
+### `reportHealth` inside `start` is no longer discarded
+
+Becoming ready assigned `healthy` unconditionally, throwing away whatever a
+resource reported during `start`. It is now kept, and only a resource that
+reported nothing is assumed healthy.
+
+**How to find what this touches:** grep your `start` bodies for **every**
+`reportHealth` call, not only the ones reporting `degraded`. The old
+unconditional assignment was also a repair — a resource that reported
+`'unhealthy'` early in `start` and never corrected itself was quietly fixed up
+on the way to ready.
+
+Two cases, and they need opposite fixes.
+
+**1. A resource that is genuinely expected to start degraded** — up, but still
+dialling something external. `required` defaults to **`true`**, and readiness
+requires every required resource to be healthy, so such a resource now refuses
+the whole startup where before its report vanished. That is the invariant
+working as intended; what changed is that it can be reached. Say what it is:
+
+```ts
+// before: started, and its report was discarded
+defineManagedResource({ id: 'dialling', start: ({ reportHealth }) => reportHealth('degraded') })
+
+// after: says what it is, and does not gate the application
+defineManagedResource({ id: 'dialling', required: false, start: ({ reportHealth }) => reportHealth('degraded') })
+```
+
+**2. A resource that reported `'unhealthy'` early and became healthy later** —
+a pessimistic report before a connection settled. Here `required: false` is the
+**wrong** fix: it would hide a real failure. Report the recovery instead:
+
+```ts
+start: async ({ reportHealth }) => {
+  reportHealth('unhealthy')
+  await connect()
+  reportHealth('healthy')   // ← previously unnecessary; now it is the fix
+}
+```
+
+**Also check your health endpoint.** An **optional** resource reporting
+non-healthy during `start` now moves the application aggregate to `degraded`,
+where before it stayed `healthy`. A readiness probe that maps `degraded` to a
+non-200 will flip on upgrade — and a supervisor that restarts on that will loop.
+
+The refusals now say which of the two happened: a resource that was never
+healthy is told it "is not healthy" and pointed at `required: false`; one that
+was healthy and stopped is told it "lost readiness" and pointed at
+`onResourceFailure`.
+
 ## Released migration: 0.60.0
 
 ### close() says what it achieved
@@ -9131,7 +9455,9 @@ The browser-and-server entrypoint. Re-exports everything from
 | `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
+| `parseNDJSON` | function | parse an NDJSON `Response`; blank keep-alive lines are skipped — [guide](../guide/client.md#ndjson) |
 | `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
+| `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
@@ -9146,6 +9472,12 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
 | `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
 | `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
+| `RealtimeRequestRejectedError` | class | the peer refused the frame against its own contract and said so — `reason`, `issues` — instead of leaving the sender to time out ([ADR 0106](../decisions/0106-a-refused-frame-answers-its-sender.md)) |
+| `REALTIME_REJECTION_KEY` | const | the reserved acknowledgement key a refusal travels under |
+| `RealtimeRejectionEnvelope` | _type_ | the wire shape of a refusal |
+| `RealtimeRejectionReport` | _type_ | what the sender is told: event, reason, message, issues |
+| `RealtimeRejectionIssue` | _type_ | one refused field, already flattened (`path: '0.v'`) |
+| `asRealtimeRejection` | function | recognise a refusal in an acknowledgement value, validating it |
 | `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
 | `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
 | `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
@@ -9159,6 +9491,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
+| `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
 
 ### Trace (client)
 
@@ -9414,6 +9747,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | 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 |
 | `parseSSE` | function | parse an SSE `Response` (also on the root entrypoint) |
 | `MultipartLifecycle` | _type_ | request-scoped rollback ownership for accepted streamed handles |
 | `MultipartResult` | _type_ | what `parseMultipart` returns |
@@ -9449,6 +9786,9 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `RateLimitConfig` | _type_ | config for `createRateLimiter` |
 | `ClientIpOptions` | _type_ | trusted-proxy config for `extractIp` / `resolveSocketIp` |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
+| `StreamingRouteOptions` | _type_ | options for `streamingRoute` / `ndjsonRoute` / `sseRoute` |
+| `StreamingSourceContext` | _type_ | what a streaming source is given, including the cancellation `signal` |
+| `StreamingFormat` | _type_ | `'ndjson' \| 'sse'` |
 
 ### OpenAPI
 
@@ -9479,6 +9819,7 @@ cutovers are covered by the executable
 | `ApplicationResourceFailure` | _type_ | one resource failure with the cause its phase label cannot carry — delivered to `onResourceFailure` |
 | `ApplicationResourcePhase` | _type_ | the phase a managed resource failed in — the vocabulary of `ApplicationResourceShutdown.failures` |
 | `ApplicationShutdownOptionsSchema` / `ApplicationShutdownOptions` | schema / _type_ | the two shutdown budgets and an abort signal — without the HTTP-only `retryAfterSeconds` |
+| `ApplicationShutdownBudgetSchema` / `ApplicationShutdownBudget` | schema / _type_ | the same two budgets without a signal — `ApplicationConfig.shutdown`, the default for `shutdown()` and the only budget a failed startup's rollback can read |
 | `ActivityTokenBrand` | const | the brand symbol `ActivityToken` carries, exported so `ActivityProjection` is implementable |
 | `defineManagedResource` | function | retain the exact typed resource declaration; every invoked start is rollback-eligible |
 | `managedServerResource` | function | adapt an existing managed server without copying its HTTP/WebSocket shutdown machine |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.60.1",
+  "version": "0.61.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",
@@ -212,7 +212,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
-    "ai": "^7.0.78",
+    "ai": "^7.0.79",
     "grammy": "^1.45.1",
     "react": "^19.2.8",
     "react-query-kit": "^3.3.4",