@telorun/http-server 0.2.4 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @telorun/http-server
 
+## 0.3.2
+
+### Patch Changes
+
+- 1662260: Address four review findings against the new transport-neutral dispatch package:
+
+  - **Catch schema omits `encoder`.** `CatchEntry.content[mime]` is now typed as `CatchContentEntry` (a `Type.Omit` of `ContentEntry` that drops `encoder`). Catches are buffer-mode only — by the time a catch fires the response is committed pre-stream and there's no upstream iterable to feed an encoder, and `dispatchCatches` never reads it. Previously the TypeBox `CatchEntry` reused `ContentEntry` verbatim, so an `encoder:` on a catch passed validation and was silently ignored. The runtime check now matches the YAML manifest schema in `modules/http-server/telo.yaml` (which already uses `additionalProperties: false` on catch content entries). New `CatchContentEntry` value/type is exported from the package root.
+  - **`when:` absence check is `=== undefined`, not truthiness.** `matchEntry` previously treated any falsy `entry.when` as "no predicate," which meant a literal `when: false` was registered as the list's catch-all and could be selected when no other entry matched. The check is now explicit-undefined (matching the precaution already taken in `modules/mcp-server/nodejs/src/outcome.ts`). Generic constraint widened from `when?: string` to `when?: unknown` to reflect the post-CEL value shape.
+  - **`when:` schema type is `Unknown`, not `String`.** The TypeBox `ReturnEntry`/`CatchEntry` schemas declared `when` as `Type.Optional(Type.String())`, but the manifest declares `when` as `type: boolean` and the dispatcher receives either a literal boolean (`when: true` / `when: false`) or a CEL `CompiledValue` object (`when: ${{ ... }}`). Both shapes were rejected by the controller's `ctx.validateSchema(resource, HttpApiManifest)` check at load time. Switched to `Type.Optional(Type.Unknown())`; `expandWith` already knows how to evaluate either shape.
+  - **Accept negotiation honors media-range specificity.** `matchAcceptForMime` previously took the maximum q-value across all matching ranges, so `Accept: application/json;q=0, */*;q=1` would still serve `application/json` via the wildcard even though the client explicitly excluded it. The negotiator now picks the most specific matching range per RFC 9110 §12.5.1 (exact `type/subtype` > type-wildcard `type/*` > full-wildcard `*/*`), with q=0 on the most specific match correctly excluding the representation. Ties on specificity are broken by highest q.
+
+  `@telorun/http-server` — adds vitest as a devDependency and a `test` script that runs `fastifyReplySink` through `@telorun/http-dispatch/test-utils`'s shared `runSinkContract` harness against a real listening Fastify server (not `app.inject` — light-my-request rejects on the destroyed-stream path that mid-flight errors take, which would hide whether the partial body actually made it to the wire). Drift between the production transport and the dispatcher's contract now surfaces as a contract-test failure rather than a transport-specific bug discovered downstream. No production-code changes in this package.
+
+- 07c881a: Migrate `Api.routes[].request` to anchor at the shared `HttpDispatch.Request/$defs/Matcher` carrier instead of inlining the matcher schema (`method` / `path` / `query` / `body` / `headers`). Field-level annotations (`x-telo-topology-role: matcher`) stay on the consuming side; only the value-shape moves to the carrier.
+
+  Same pattern as the earlier `Server.notFoundHandler.returns` / `.catches` migration to `HttpDispatch.Outcomes`. Zero behavioural change: the carrier reproduces the inline schema field-for-field, and validation goes through the same AJV path. The win is that `Lambda.HttpApi.routes[].request` (landing next) now shares one structural type-shape with http-server — no duplicated matcher schema across transports.
+
+  `HttpDispatch.Request` is required as a dependency — already in `packages/http-dispatch/telo.yaml`'s exports; the existing `Telo.Import` of `HttpDispatch` at the top of `modules/http-server/telo.yaml` covers it.
+
+  When http-dispatch evolves the matcher (adds segment annotations, content-encoding hooks, etc.), http-server picks the change up automatically.
+
+- 1662260: Extract `returns:` / `catches:` rendering into a transport-neutral package.
+
+  `@telorun/http-dispatch` — new package, initial publish. Ships:
+
+  - `ResponseSink` interface — transport-neutral status / header / send / stream sink that the dispatcher writes through. HTTP-shaped transports (Fastify-backed http-server, AWS Lambda, future fetch-API / native http.Server adapters) implement this interface; the dispatcher does not know which one is underneath.
+  - `dispatchReturns` / `dispatchCatches` — the CEL `when:` matching, status branching, schema validation, per-MIME content negotiation, buffer/stream mode, encoder-ref-driven streaming, header merging, and error-path fall-through previously inlined in `http-api-controller.ts`. Encoder ref injection stays inside the dispatcher: when a `mode: stream` entry matches, the dispatcher calls `encoder.invoke({ input })` itself and hands the resulting `AsyncIterable<Uint8Array>` to the sink. The sink never sees the encoder, the `Invocable`, or any kernel/SDK type — it only ever takes bytes.
+  - TypeBox `ReturnEntry` / `CatchEntry` / `ContentEntry` schemas, re-exportable by any transport that consumes the dispatcher.
+  - Runtime validators `validateNoContentTypeHeader` and `validateStreamWhenDoesNotReferenceResult` — defense-in-depth checks the dispatcher runs against the outcome lists.
+  - `@telorun/http-dispatch/test-utils` — a `runSinkContract(name, factory)` vitest harness that exercises every method on the sink interface through a known sequence (status-only / empty body; buffered JSON; last-write-wins headers; streamed bytes byte-exact; mid-stream failure routed through `onError`; double-send + setStatus-after-send rejection). Both http-server's Fastify adapter and future transport adapters (Lambda, gRPC, …) feed their factory through this harness so drift between transports surfaces as a contract-test failure, not a transport-specific bug discovered downstream.
+
+  `@telorun/http-server` — controller-internal refactor onto the sink via `@telorun/http-dispatch` (added as a new workspace dependency). New `fastifyReplySink` adapter translates `ResponseSink` calls onto `FastifyReply` (`reply.code` / `reply.header` / `reply.send`; `reply.hijack` + `pipeline(Readable.from(...), reply.raw)` for streams). The local `validateContentEntryShape` runtime check is **deleted** — its rule (body/encoder mutual exclusion; stream-mode requires `encoder` everywhere and forbids `body`; stream-mode requires a non-empty `content:`) moves into `modules/http-server/telo.yaml` as a `oneOf`-on-`mode` discriminated union on `Api.routes[].returns[]` and `Server.notFoundHandler.returns[]`. The `mode` field stays optional; the buffer branch matches when `mode` is absent OR `mode: buffer`, so existing manifests without `mode:` continue to validate unchanged (the kernel's shared AJV config at `ctx.validateSchema` does not enable `useDefaults`). `validateNoContentTypeHeader` and `validateStreamWhenDoesNotReferenceResult` move into `@telorun/http-dispatch` as runtime guards; no observable behaviour change for valid manifests.
+
+  `@telorun/sdk` — no change. The dispatcher is not added to the SDK; the SDK retains its zero-runtime-deps posture. HTTP-shaped dispatch code does not belong in the install tree of every non-HTTP module (sql, ai, assert, console, …), and a future Go or Python SDK should not grow a `dispatch` subpath for symmetry — dispatch is a transport-adapter concern, not a module-author concern.
+
+  Polyglot contract: the YAML schema (`status` / `when` / `mode` / `headers` / `content[mime].{body,schema,encoder,headers}` plus the `x-telo-outcome-list` / `x-telo-catches-for` annotations) is what travels across languages, not this TS package. A future Go / Python implementation re-implements the dispatcher against the same schema, duplicated verbatim into each consuming module's manifest (`@telorun/lambda` lands next).
+
+- Updated dependencies [1662260]
+- Updated dependencies [07c881a]
+- Updated dependencies [f1c35bc]
+- Updated dependencies [47f7d83]
+- Updated dependencies [1662260]
+  - @telorun/http-dispatch@0.2.0
+  - @telorun/sdk@0.10.0
+
+## 0.3.1
+
+### Patch Changes
+
+- d3ed5a5: Tighten `Http.Api.routes[].request.headers` to declare `additionalProperties: { type: "string" }`. Header values are matched as strings against the incoming request, so the schema now reflects what the runtime actually accepts. The telo editor renders this field as a key/value map editor instead of the JSON Schema designer.
+
+## 1.0.0
+
+### Major Changes
+
+- b62e535: Streaming-Invocable convention, format-codec packages, and `Http.Api` `content:` map rewrite.
+
+  **Breaking** (`@telorun/http-server`, `@telorun/ai`):
+
+  - `Http.Api.routes[].returns[]` and `routes[].catches[]` (and the equivalent `Http.Server.notFoundHandler` lists) drop top-level `body` / `schema` in favour of a per-MIME `content:` map. Buffer-mode entries use `content[<mime>].body` / `content[<mime>].schema`; stream-mode entries use `content[<mime>].encoder` (ref to any `Codec.Encoder`). The map key is the canonical `Content-Type` — declaring `Content-Type` in `headers:` is rejected at load time. Multi-key `content:` maps are negotiated against the request's `Accept` header (RFC 9110 §12.5.1). Mismatch → `406 Not Acceptable`.
+  - `mode: stream` is forbidden in `catches:` (catches fire pre-stream; no upstream iterable to feed an encoder).
+  - Migration: every existing `returns: [..., body: ..., schema: ..., headers: { Content-Type: ... }]` rewrites mechanically to `returns: [..., content: { <mime>: { body, schema } }]`. In-tree manifests (`apps/registry`, `examples/*`, `tests/*`, `benchmarks/*`) migrated.
+  - `Ai.TextStream`: `format` field removed; controller no longer encodes the wire — it returns `{ output: Stream<StreamPart> }`. Pair with a format-codec encoder (`Ndjson.Encoder`, `Sse.Encoder`, `PlainText.Encoder`) for HTTP responses or other byte transports. `text-stream-drain-controller.ts` removed (replaced by inline source → encoder → decoder steps).
+  - `StreamPart.error` shape changed from native `Error` to `{ message, code?, data? }` so generic encoders can JSON-serialize error frames without bespoke translation.
+
+  **New** (`@telorun/codec`, `@telorun/plain-text-codec`, `@telorun/ndjson-codec`, `@telorun/sse-codec`, `@telorun/octet-codec`):
+
+  - `@telorun/codec` ships the `Encoder` and `Decoder` abstracts (no controllers — pure contracts).
+  - Format-codec packages each carry one or both directions: `PlainText.Encoder/.Decoder` (UTF-8 collect + emit), `Ndjson.Encoder` (one JSON record per line), `Sse.Encoder` (Server-Sent Events frames), `Octet.Encoder/.Decoder` (raw bytes pass-through and collect).
+  - All encoders implement `invoke({input}): Promise<{output: Stream<Uint8Array>}>` per the streaming-Invocable convention.
+
+  **New** (`@telorun/sdk`):
+
+  - `Stream<T>` class wrapping `AsyncIterable<T>`. Producers wrap their iterables in `new Stream(...)` so the value's constructor is recognized by CEL's runtime type-checker (which rejects unrecognized constructors like `AsyncGenerator` and Node `Readable`). The analyzer registers `Stream` as a CEL object type.
+
+  **Annotation** (`@telorun/kernel`, `@telorun/analyzer`):
+
+  - `x-telo-stream: true` schema annotation on input/output properties marks them as carrying a `Stream<T>`. CEL passes the value through by reference; analyzer's chain validator rejects `.field` / `[index]` access past a stream-marked property. Convention: streaming Invocables put the stream on `input` (inputs) and `output` (result).
+  - `Self.<Abstract>` magic alias auto-registered for every Telo.Library/Application — lets concrete kinds in the same library use `extends: Self.<Abstract>` without a self-import that would loop the loader.
+  - Analyzer's `buildReferenceFieldMap`, `resolveFieldValues`, `extractInlinesAtPath`, and `injectAtPath` (Phase 5) now recurse into `additionalProperties` via a `{}` path-segment marker. Required for refs nested inside open-keyed maps like `content[<mime>].encoder`.
+  - `isInlineResource` widened: bare-kind refs (`{kind: X}` with no `name` and no extra config) are now treated as inline-singleton definitions and Phase 2 extracts them as fresh stateless resources. Previously `{kind: X}` raised `INVALID_REFERENCE` (treated as a malformed named ref). This matches the runtime-side `resolveChildren` semantics already documented for `Run.Throw`-style stateless inlines, and lets `encoder: {kind: Ndjson.Encoder}` work without boilerplate. Manifests that had `{kind: X}` with the (broken) intent of resolving to an existing named resource will now silently extract a fresh resource — extremely unlikely in practice (those refs were already failing analysis), but worth flagging for downstream consumers.
+
+  **Behaviour changes worth flagging** (`@telorun/http-server`):
+
+  - **Single-key `content:` maps now do `Accept` negotiation.** A route declaring only `content: { application/json: ... }` returns `406 Not Acceptable` for `Accept: image/png` — RFC 9110 §15.5.7 compliant. Pre-PR, the legacy top-level `body:` shape ignored `Accept` entirely. To preserve "always send" behaviour, declare `*/*` as an explicit key.
+  - **Accept matching ignores media-type parameters** beyond the first `;`. `Accept: text/plain; charset=ascii` matches `content: { 'text/plain; charset=utf-8': ... }`. Q-values are still parsed for ranking; only the matching predicate ignores params. Authors needing parameter-level preference must declare distinct keys per parameter combo.
+  - **Load-time validators reject misconfigured `content:` shapes.** `validateContentEntryShape` rejects `body+encoder` together (mutually exclusive), missing `encoder` under `mode: stream`, `body` under `mode: stream`, and `encoder` under `mode: buffer`. Previously some of these slipped through to runtime where they manifested as 500-on-negotiation.
+  - **Mid-stream `pipeline()` failures emit `Http.Api.streamFailed` events.** Once `reply.hijack()` runs, mid-stream errors (encoder throws, broken pipe) bypass `catches:` by design (response is committed). They now emit a structured event with `path`, `method`, `status`, `mime`, and the error so operators can observe failures that would otherwise be silent.
+
+  **Other** (`@telorun/http-client`, `@telorun/javascript`):
+
+  - `HttpClient.Request` `mode: stream` returns `{ output: Stream<Uint8Array> }` instead of a bare `Readable` — fits the streaming-Invocable convention, pairs with `Octet.Encoder` for HTTP pass-through.
+  - `JS.Script` injects `Stream` into every script's scope (via the second function argument, destructured at the top of the wrapper). User code can `new Stream(asyncGen)` directly.
+
+  **Tests**:
+
+  - New Layer 1 hermetic streaming-contract test (`modules/ai/tests/text-stream-streaming-contract.yaml`) — three sub-targets, byte-exact NDJSON / SSE / PlainText.
+  - New Layer 2 live OpenAI streaming smoke (`modules/ai-openai/tests/openai-live-text-stream.yaml`) — env-gated; exercises `Ai.TextStream → Ndjson.Encoder → PlainText.Decoder` against the real provider.
+  - New http-server integration test (`modules/http-server/tests/text-stream-via-http.yaml`) — exercises three single-format routes plus a four-format negotiated route with five Accept variants.
+
+### Patch Changes
+
+- Updated dependencies [b62e535]
+  - @telorun/sdk@0.7.0
+
 ## 0.2.4
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,3 @@
----
-description: "v1.0 Http.Server and Http.Api spec: routing, normalized request/response I/O, OpenAPI path syntax, framework-agnostic"
----
-
 # Telo HTTP Standard Specification (v1.0 Draft)
 
 ## Overview

package/dist/fastify-reply-sink.d.ts

@@ -0,0 +1,12 @@
+import type { ResponseSink } from "@telorun/http-dispatch";
+import type { FastifyReply } from "fastify";
+/** Adapts a Fastify `FastifyReply` to the transport-neutral `ResponseSink`
+ *  interface from `@telorun/http-dispatch`. Status / header accumulation maps
+ *  directly onto Fastify's setters; buffered bodies go through
+ *  `reply.send(body)` (so Fastify's per-status fast-json-stringify dispatch
+ *  still runs); streamed bodies hijack the reply and pipe through `reply.raw`.
+ *
+ *  The sink owns the rule that `setStatus` / `setHeader` calls after the
+ *  response is committed must throw — Fastify itself would silently no-op
+ *  in some cases, so we enforce the contract here. */
+export declare function fastifyReplySink(reply: FastifyReply): ResponseSink;

package/dist/fastify-reply-sink.js

@@ -0,0 +1,64 @@
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+/** Adapts a Fastify `FastifyReply` to the transport-neutral `ResponseSink`
+ *  interface from `@telorun/http-dispatch`. Status / header accumulation maps
+ *  directly onto Fastify's setters; buffered bodies go through
+ *  `reply.send(body)` (so Fastify's per-status fast-json-stringify dispatch
+ *  still runs); streamed bodies hijack the reply and pipe through `reply.raw`.
+ *
+ *  The sink owns the rule that `setStatus` / `setHeader` calls after the
+ *  response is committed must throw — Fastify itself would silently no-op
+ *  in some cases, so we enforce the contract here. */
+export function fastifyReplySink(reply) {
+    let status = 200;
+    let sent = false;
+    function ensureOpen(method) {
+        if (sent) {
+            throw new Error(`fastifyReplySink: ${method} called after response was sent`);
+        }
+    }
+    return {
+        setStatus(code) {
+            ensureOpen("setStatus");
+            status = code;
+            reply.code(code);
+        },
+        setHeader(name, value) {
+            ensureOpen("setHeader");
+            // Fastify's reply.header is last-write-wins for the same name.
+            reply.header(name, value);
+        },
+        async send(body) {
+            ensureOpen("send");
+            sent = true;
+            if (body === undefined) {
+                reply.send();
+            }
+            else {
+                reply.send(body);
+            }
+        },
+        async stream(iter, onError) {
+            ensureOpen("stream");
+            sent = true;
+            reply.hijack();
+            reply.raw.writeHead(status, reply.getHeaders());
+            try {
+                await pipeline(Readable.from(iter), reply.raw);
+            }
+            catch (err) {
+                if (onError) {
+                    try {
+                        await onError(err);
+                    }
+                    catch {
+                        /* operator hook should never fail the response — swallow */
+                    }
+                }
+                // Headers are flushed at this point; the response is committed and
+                // there's nothing useful to rethrow into Fastify. The socket will
+                // close.
+            }
+        },
+    };
+}

package/dist/http-api-controller.d.ts

@@ -1,30 +1,7 @@
 import { Static } from "@sinclair/typebox";
+import { CatchEntry, ContentEntry, ReturnEntry } from "@telorun/http-dispatch";
 import { ControllerContext, Invocable, KindRef, ResourceContext, ResourceInstance } from "@telorun/sdk";
-import { FastifyInstance, FastifyReply } from "fastify";
-declare const ReturnEntry: import("@sinclair/typebox").TObject<{
-    status: import("@sinclair/typebox").TInteger;
-    when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-    mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"buffer">, import("@sinclair/typebox").TLiteral<"stream">]>>;
-    schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-        body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-        headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-    }>>;
-    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
-    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-}>;
-type ReturnEntry = Static<typeof ReturnEntry>;
-declare const CatchEntry: import("@sinclair/typebox").TObject<{
-    status: import("@sinclair/typebox").TInteger;
-    when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-    schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-        headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-    }>>;
-    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
-    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-}>;
-type CatchEntry = Static<typeof CatchEntry>;
+import { FastifyInstance } from "fastify";
 declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
     routes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         request: import("@sinclair/typebox").TObject<{
@@ -41,48 +18,35 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
         inputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>>;
         returns: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
             status: import("@sinclair/typebox").TInteger;
-            when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
             mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"buffer">, import("@sinclair/typebox").TLiteral<"stream">]>>;
-            schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-                query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-                body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-                headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            }>>;
             headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
-            body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+            content: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+                body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+                schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+                encoder: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<KindRef<Invocable<Record<string, any>, any>>>>;
+                headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+            }>>>;
         }>>;
         catches: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
             status: import("@sinclair/typebox").TInteger;
-            when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-            schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-                body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-                headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            }>>;
+            when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
             headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
-            body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+            content: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+                body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+                schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+                headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+            }>>>;
         }>>>;
     }>>;
 }>;
 type HttpApiManifest = Static<typeof HttpApiManifest>;
 export declare function register(_ctx: ControllerContext): Promise<void>;
-export type { ReturnEntry, CatchEntry };
-type ModuleLikeContext = {
-    expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
-};
-type ValidateSchema = (value: unknown, schema: unknown) => void;
+export type { CatchEntry, ContentEntry, ReturnEntry };
 type HandlerRef = {
     kind: string;
     name: string;
 };
-export declare function dispatchReturns(returns: ReturnEntry[], result: unknown, requestContext: Record<string, unknown>, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply): Promise<void>;
-/** Render an InvokeError through a `catches:` list. Falls back to a structured
- *  500 when no entry matches. Plain (non-InvokeError) throws never reach this
- *  function — the caller re-throws them to Fastify. */
-export declare function dispatchCatches(catches: CatchEntry[] | undefined, error: {
-    code: string;
-    message: string;
-    data?: unknown;
-}, requestContext: Record<string, unknown>, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply): Promise<void>;
 export declare class HttpServerApi implements ResourceInstance {
     private readonly ctx;
     readonly manifest: HttpApiManifest;

package/dist/http-api-controller.js

@@ -1,28 +1,7 @@
 import { Type } from "@sinclair/typebox";
+import { CatchEntry, dispatchCatches, dispatchReturns, ReturnEntry, validateNoContentTypeHeader, validateStreamWhenDoesNotReferenceResult, } from "@telorun/http-dispatch";
 import { isInvokeError, Ref, } from "@telorun/sdk";
-import { pipeline } from "stream/promises";
-const ReturnEntry = Type.Object({
-    status: Type.Integer({ minimum: 100, maximum: 599 }),
-    when: Type.Optional(Type.String()),
-    mode: Type.Optional(Type.Union([Type.Literal("buffer"), Type.Literal("stream")])),
-    schema: Type.Optional(Type.Object({
-        query: Type.Optional(Type.Any()),
-        body: Type.Optional(Type.Any()),
-        headers: Type.Optional(Type.Any()),
-    })),
-    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-    body: Type.Optional(Type.Any()),
-});
-const CatchEntry = Type.Object({
-    status: Type.Integer({ minimum: 100, maximum: 599 }),
-    when: Type.Optional(Type.String()),
-    schema: Type.Optional(Type.Object({
-        body: Type.Optional(Type.Any()),
-        headers: Type.Optional(Type.Any()),
-    })),
-    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-    body: Type.Optional(Type.Any()),
-});
+import { fastifyReplySink } from "./fastify-reply-sink.js";
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
         path: Type.String(),
@@ -43,81 +22,6 @@ const HttpApiManifest = Type.Object({
     routes: Type.Array(HttpApiRouteManifest),
 });
 export async function register(_ctx) { }
-/** Pick the first entry whose `when:` evaluates truthy, falling back to the
- *  first entry with no `when:` (the list's catch-all). */
-function matchEntry(entries, celCtx, moduleContext) {
-    let fallback;
-    for (const entry of entries) {
-        if (!entry.when) {
-            fallback ??= entry;
-            continue;
-        }
-        if (moduleContext.expandWith(entry.when, celCtx) === true)
-            return entry;
-    }
-    return fallback;
-}
-export async function dispatchReturns(returns, result, requestContext, moduleContext, validateSchema, reply) {
-    const celCtx = { result, ...requestContext };
-    const entry = matchEntry(returns, celCtx, moduleContext);
-    if (!entry) {
-        // Unreachable when the analyzer has run — every route's returns: list must
-        // cover its handler's return values (explicit when: or catch-all). Hitting
-        // this at runtime means something bypassed analysis; surface it loudly
-        // via Fastify's error handler rather than quietly render a 500.
-        throw new Error("No matching returns entry for handler result — the route's returns: list must cover every return value (add a catch-all entry or widen a when: clause)");
-    }
-    reply.code(entry.status);
-    if (entry.headers) {
-        const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx);
-        for (const [key, value] of Object.entries(mappedHeaders)) {
-            reply.header(key, value);
-        }
-    }
-    if (entry.mode === "stream") {
-        reply.hijack();
-        reply.raw.writeHead(entry.status, reply.getHeaders());
-        await pipeline(result, reply.raw);
-        return;
-    }
-    if (entry.body !== undefined) {
-        const mappedBody = moduleContext.expandWith(entry.body, celCtx);
-        if (entry.schema?.body)
-            validateSchema(mappedBody, entry.schema.body);
-        reply.send(mappedBody);
-        return;
-    }
-    reply.send(result);
-}
-/** Render an InvokeError through a `catches:` list. Falls back to a structured
- *  500 when no entry matches. Plain (non-InvokeError) throws never reach this
- *  function — the caller re-throws them to Fastify. */
-export async function dispatchCatches(catches, error, requestContext, moduleContext, validateSchema, reply) {
-    const celCtx = { error, ...requestContext };
-    const entry = catches ? matchEntry(catches, celCtx, moduleContext) : undefined;
-    if (!entry) {
-        reply.code(500);
-        reply.send({
-            error: { code: error.code, message: error.message, data: error.data },
-        });
-        return;
-    }
-    reply.code(entry.status);
-    if (entry.headers) {
-        const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx);
-        for (const [key, value] of Object.entries(mappedHeaders)) {
-            reply.header(key, value);
-        }
-    }
-    if (entry.body !== undefined) {
-        const mappedBody = moduleContext.expandWith(entry.body, celCtx);
-        if (entry.schema?.body)
-            validateSchema(mappedBody, entry.schema.body);
-        reply.send(mappedBody);
-        return;
-    }
-    reply.send({ error: { code: error.code, message: error.message, data: error.data } });
-}
 export class HttpServerApi {
     ctx;
     manifest;
@@ -160,11 +64,19 @@ export class HttpServerApi {
             schema.body = route.request.schema.body;
         if (route.request.schema?.headers)
             schema.headers = route.request.schema.headers;
+        // Response schemas: register the FIRST content[mime].schema we find for
+        // each status. Multiple MIMEs per status all get the same response shape
+        // (Fastify's response schema is per-status, not per-MIME); the per-MIME
+        // schema field is for AJV validation in dispatchReturns, separate from
+        // Fastify's per-status response schema registration.
         for (const entry of route.returns) {
-            if (entry.schema?.body)
-                schema.response[entry.status] = entry.schema.body;
-            else if (entry.schema)
-                schema.response[entry.status] = {};
+            if (!entry.content)
+                continue;
+            for (const [, c] of Object.entries(entry.content)) {
+                if (c.schema && schema.response[entry.status] === undefined) {
+                    schema.response[entry.status] = c.schema;
+                }
+            }
         }
         app.route({
             method: route.request.method,
@@ -181,6 +93,7 @@ export class HttpServerApi {
                         body: request.body,
                     },
                 };
+                const acceptHeader = request.headers["accept"]?.toString();
                 const resolvedInputs = route.inputs
                     ? (this.ctx.moduleContext.expandWith(route.inputs, requestContext) ?? {})
                     : requestContext;
@@ -188,6 +101,7 @@ export class HttpServerApi {
                     ...resolvedInputs,
                     inputs: resolvedInputs,
                 };
+                const sink = fastifyReplySink(reply);
                 let result;
                 try {
                     result = handler
@@ -197,15 +111,25 @@ export class HttpServerApi {
                 catch (err) {
                     if (!isInvokeError(err))
                         throw err;
-                    return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                    return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink);
                 }
-                return dispatchReturns(route.returns, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                return dispatchReturns(route.returns, result, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink, (err, errCtx) => this.ctx.emitEvent("Http.Api.streamFailed", {
+                    path: route.request.path,
+                    method: route.request.method,
+                    status: errCtx.status,
+                    mime: errCtx.mime,
+                    error: err instanceof Error
+                        ? { message: err.message, stack: err.stack, code: err.code }
+                        : { message: String(err) },
+                }));
             },
         });
     }
 }
 export async function create(resource, ctx) {
     ctx.validateSchema(resource, HttpApiManifest);
+    validateNoContentTypeHeader(resource);
+    validateStreamWhenDoesNotReferenceResult(resource);
     // Capture handler {kind, name} before Phase 5 injection overwrites the ref
     // with a live Invocable instance. invokeResolved() needs the kind/name to
     // emit properly-scoped Invoked / InvokeRejected events.

package/dist/http-server-controller.d.ts

@@ -1,5 +1,5 @@
+import { CatchEntry, ReturnEntry } from "@telorun/http-dispatch";
 import { type Invocable, type KindRef, type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
-import { CatchEntry, ReturnEntry } from "./http-api-controller.js";
 type CorsOptions = {
     origin?: string | boolean | string[];
     methods?: string | string[];

package/dist/http-server-controller.js

@@ -1,10 +1,11 @@
 import cors from "@fastify/cors";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
+import { dispatchCatches, dispatchReturns, } from "@telorun/http-dispatch";
 import { isInvokeError, } from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify from "fastify";
-import { dispatchCatches, dispatchReturns, } from "./http-api-controller.js";
+import { fastifyReplySink } from "./fastify-reply-sink.js";
 class HttpServer {
     releaseHold = null;
     pluginsInitialized = false;
@@ -135,6 +136,8 @@ class HttpServer {
                         body: request.body,
                     },
                 };
+                const acceptHeader = request.headers["accept"]?.toString();
+                const sink = fastifyReplySink(reply);
                 let result;
                 try {
                     result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
@@ -142,10 +145,10 @@ class HttpServer {
                 catch (err) {
                     if (!isInvokeError(err))
                         throw err;
-                    return dispatchCatches(handler.catches, { code: err.code, message: err.message, data: err.data }, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                    return dispatchCatches(handler.catches, { code: err.code, message: err.message, data: err.data }, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink);
                 }
                 if (handler.returns) {
-                    return dispatchReturns(handler.returns, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                    return dispatchReturns(handler.returns, result, requestContext, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), sink);
                 }
                 const status = result?.status ?? 200;
                 reply.code(status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.2.4",
+  "version": "0.3.2",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,13 +43,17 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@telorun/sdk": "0.6.0"
+    "@telorun/http-dispatch": "0.2.0",
+    "@telorun/sdk": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.lib.json"
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/fastify-reply-sink.ts

@@ -0,0 +1,67 @@
+import type { ResponseSink } from "@telorun/http-dispatch";
+import type { FastifyReply } from "fastify";
+import type { OutgoingHttpHeaders } from "http";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+
+/** Adapts a Fastify `FastifyReply` to the transport-neutral `ResponseSink`
+ *  interface from `@telorun/http-dispatch`. Status / header accumulation maps
+ *  directly onto Fastify's setters; buffered bodies go through
+ *  `reply.send(body)` (so Fastify's per-status fast-json-stringify dispatch
+ *  still runs); streamed bodies hijack the reply and pipe through `reply.raw`.
+ *
+ *  The sink owns the rule that `setStatus` / `setHeader` calls after the
+ *  response is committed must throw — Fastify itself would silently no-op
+ *  in some cases, so we enforce the contract here. */
+export function fastifyReplySink(reply: FastifyReply): ResponseSink {
+  let status = 200;
+  let sent = false;
+
+  function ensureOpen(method: string): void {
+    if (sent) {
+      throw new Error(`fastifyReplySink: ${method} called after response was sent`);
+    }
+  }
+
+  return {
+    setStatus(code) {
+      ensureOpen("setStatus");
+      status = code;
+      reply.code(code);
+    },
+    setHeader(name, value) {
+      ensureOpen("setHeader");
+      // Fastify's reply.header is last-write-wins for the same name.
+      reply.header(name, value);
+    },
+    async send(body) {
+      ensureOpen("send");
+      sent = true;
+      if (body === undefined) {
+        reply.send();
+      } else {
+        reply.send(body);
+      }
+    },
+    async stream(iter, onError) {
+      ensureOpen("stream");
+      sent = true;
+      reply.hijack();
+      reply.raw.writeHead(status, reply.getHeaders() as OutgoingHttpHeaders);
+      try {
+        await pipeline(Readable.from(iter), reply.raw);
+      } catch (err) {
+        if (onError) {
+          try {
+            await onError(err);
+          } catch {
+            /* operator hook should never fail the response — swallow */
+          }
+        }
+        // Headers are flushed at this point; the response is committed and
+        // there's nothing useful to rethrow into Fastify. The socket will
+        // close.
+      }
+    },
+  };
+}

package/src/http-api-controller.ts

@@ -1,4 +1,13 @@
 import { Static, Type } from "@sinclair/typebox";
+import {
+  CatchEntry,
+  ContentEntry,
+  dispatchCatches,
+  dispatchReturns,
+  ReturnEntry,
+  validateNoContentTypeHeader,
+  validateStreamWhenDoesNotReferenceResult,
+} from "@telorun/http-dispatch";
 import {
   ControllerContext,
   Invocable,
@@ -9,38 +18,7 @@ import {
   ResourceInstance,
 } from "@telorun/sdk";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
-import { type Readable } from "stream";
-import { pipeline } from "stream/promises";
-
-const ReturnEntry = Type.Object({
-  status: Type.Integer({ minimum: 100, maximum: 599 }),
-  when: Type.Optional(Type.String()),
-  mode: Type.Optional(Type.Union([Type.Literal("buffer"), Type.Literal("stream")])),
-  schema: Type.Optional(
-    Type.Object({
-      query: Type.Optional(Type.Any()),
-      body: Type.Optional(Type.Any()),
-      headers: Type.Optional(Type.Any()),
-    }),
-  ),
-  headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-  body: Type.Optional(Type.Any()),
-});
-type ReturnEntry = Static<typeof ReturnEntry>;
-
-const CatchEntry = Type.Object({
-  status: Type.Integer({ minimum: 100, maximum: 599 }),
-  when: Type.Optional(Type.String()),
-  schema: Type.Optional(
-    Type.Object({
-      body: Type.Optional(Type.Any()),
-      headers: Type.Optional(Type.Any()),
-    }),
-  ),
-  headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-  body: Type.Optional(Type.Any()),
-});
-type CatchEntry = Static<typeof CatchEntry>;
+import { fastifyReplySink } from "./fastify-reply-sink.js";
 
 const HttpApiRouteManifest = Type.Object({
   request: Type.Object({
@@ -69,128 +47,10 @@ type HttpApiManifest = Static<typeof HttpApiManifest>;
 
 export async function register(_ctx: ControllerContext): Promise<void> {}
 
-export type { ReturnEntry, CatchEntry };
-
-type ModuleLikeContext = {
-  expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
-};
-
-type ValidateSchema = (value: unknown, schema: unknown) => void;
+export type { CatchEntry, ContentEntry, ReturnEntry };
 
 type HandlerRef = { kind: string; name: string };
 
-/** Pick the first entry whose `when:` evaluates truthy, falling back to the
- *  first entry with no `when:` (the list's catch-all). */
-function matchEntry<T extends { when?: string }>(
-  entries: T[],
-  celCtx: Record<string, unknown>,
-  moduleContext: ModuleLikeContext,
-): T | undefined {
-  let fallback: T | undefined;
-  for (const entry of entries) {
-    if (!entry.when) {
-      fallback ??= entry;
-      continue;
-    }
-    if (moduleContext.expandWith(entry.when, celCtx) === true) return entry;
-  }
-  return fallback;
-}
-
-export async function dispatchReturns(
-  returns: ReturnEntry[],
-  result: unknown,
-  requestContext: Record<string, unknown>,
-  moduleContext: ModuleLikeContext,
-  validateSchema: ValidateSchema,
-  reply: FastifyReply,
-): Promise<void> {
-  const celCtx = { result, ...requestContext };
-  const entry = matchEntry(returns, celCtx, moduleContext);
-
-  if (!entry) {
-    // Unreachable when the analyzer has run — every route's returns: list must
-    // cover its handler's return values (explicit when: or catch-all). Hitting
-    // this at runtime means something bypassed analysis; surface it loudly
-    // via Fastify's error handler rather than quietly render a 500.
-    throw new Error(
-      "No matching returns entry for handler result — the route's returns: list must cover every return value (add a catch-all entry or widen a when: clause)",
-    );
-  }
-
-  reply.code(entry.status);
-
-  if (entry.headers) {
-    const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx) as Record<
-      string,
-      unknown
-    >;
-    for (const [key, value] of Object.entries(mappedHeaders)) {
-      reply.header(key, value as string);
-    }
-  }
-
-  if (entry.mode === "stream") {
-    reply.hijack();
-    reply.raw.writeHead(entry.status, reply.getHeaders() as Record<string, string>);
-    await pipeline(result as Readable, reply.raw);
-    return;
-  }
-
-  if (entry.body !== undefined) {
-    const mappedBody = moduleContext.expandWith(entry.body, celCtx);
-    if (entry.schema?.body) validateSchema(mappedBody, entry.schema.body);
-    reply.send(mappedBody);
-    return;
-  }
-
-  reply.send(result);
-}
-
-/** Render an InvokeError through a `catches:` list. Falls back to a structured
- *  500 when no entry matches. Plain (non-InvokeError) throws never reach this
- *  function — the caller re-throws them to Fastify. */
-export async function dispatchCatches(
-  catches: CatchEntry[] | undefined,
-  error: { code: string; message: string; data?: unknown },
-  requestContext: Record<string, unknown>,
-  moduleContext: ModuleLikeContext,
-  validateSchema: ValidateSchema,
-  reply: FastifyReply,
-): Promise<void> {
-  const celCtx = { error, ...requestContext };
-  const entry = catches ? matchEntry(catches, celCtx, moduleContext) : undefined;
-
-  if (!entry) {
-    reply.code(500);
-    reply.send({
-      error: { code: error.code, message: error.message, data: error.data },
-    });
-    return;
-  }
-
-  reply.code(entry.status);
-
-  if (entry.headers) {
-    const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx) as Record<
-      string,
-      unknown
-    >;
-    for (const [key, value] of Object.entries(mappedHeaders)) {
-      reply.header(key, value as string);
-    }
-  }
-
-  if (entry.body !== undefined) {
-    const mappedBody = moduleContext.expandWith(entry.body, celCtx);
-    if (entry.schema?.body) validateSchema(mappedBody, entry.schema.body);
-    reply.send(mappedBody);
-    return;
-  }
-
-  reply.send({ error: { code: error.code, message: error.message, data: error.data } });
-}
-
 export class HttpServerApi implements ResourceInstance {
   constructor(
     private readonly ctx: ResourceContext,
@@ -235,9 +95,18 @@ export class HttpServerApi implements ResourceInstance {
     if (route.request.schema?.body) schema.body = route.request.schema.body;
     if (route.request.schema?.headers) schema.headers = route.request.schema.headers;
 
+    // Response schemas: register the FIRST content[mime].schema we find for
+    // each status. Multiple MIMEs per status all get the same response shape
+    // (Fastify's response schema is per-status, not per-MIME); the per-MIME
+    // schema field is for AJV validation in dispatchReturns, separate from
+    // Fastify's per-status response schema registration.
     for (const entry of route.returns) {
-      if (entry.schema?.body) schema.response[entry.status] = entry.schema.body;
-      else if (entry.schema) schema.response[entry.status] = {};
+      if (!entry.content) continue;
+      for (const [, c] of Object.entries(entry.content)) {
+        if (c.schema && schema.response[entry.status] === undefined) {
+          schema.response[entry.status] = c.schema;
+        }
+      }
     }
 
     app.route({
@@ -255,6 +124,11 @@ export class HttpServerApi implements ResourceInstance {
             body: request.body,
           },
         };
+        const acceptHeader = (
+          (request.headers as Record<string, string | string[] | undefined>)["accept"] as
+            | string
+            | undefined
+        )?.toString();
         const resolvedInputs: Record<string, any> = route.inputs
           ? ((this.ctx.moduleContext.expandWith(route.inputs, requestContext) as any) ?? {})
           : requestContext;
@@ -263,6 +137,8 @@ export class HttpServerApi implements ResourceInstance {
           inputs: resolvedInputs,
         };
 
+        const sink = fastifyReplySink(reply);
+
         let result: unknown;
         try {
           result = handler
@@ -274,9 +150,10 @@ export class HttpServerApi implements ResourceInstance {
             route.catches,
             { code: err.code, message: err.message, data: err.data },
             requestContext,
+            acceptHeader,
             this.ctx.moduleContext,
             this.ctx.validateSchema.bind(this.ctx),
-            reply,
+            sink,
           );
         }
 
@@ -284,9 +161,21 @@ export class HttpServerApi implements ResourceInstance {
           route.returns,
           result,
           requestContext,
+          acceptHeader,
           this.ctx.moduleContext,
           this.ctx.validateSchema.bind(this.ctx),
-          reply,
+          sink,
+          (err, errCtx) =>
+            this.ctx.emitEvent("Http.Api.streamFailed", {
+              path: route.request.path,
+              method: route.request.method,
+              status: errCtx.status,
+              mime: errCtx.mime,
+              error:
+                err instanceof Error
+                  ? { message: err.message, stack: err.stack, code: (err as { code?: string }).code }
+                  : { message: String(err) },
+            }),
         );
       },
     });
@@ -295,6 +184,8 @@ export class HttpServerApi implements ResourceInstance {
 
 export async function create(resource: any, ctx: ResourceContext): Promise<HttpServerApi> {
   ctx.validateSchema(resource, HttpApiManifest);
+  validateNoContentTypeHeader(resource);
+  validateStreamWhenDoesNotReferenceResult(resource);
   // Capture handler {kind, name} before Phase 5 injection overwrites the ref
   // with a live Invocable instance. invokeResolved() needs the kind/name to
   // emit properly-scoped Invoked / InvokeRejected events.

package/src/http-server-controller.ts

@@ -1,6 +1,12 @@
 import cors from "@fastify/cors";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
+import {
+  CatchEntry,
+  dispatchCatches,
+  dispatchReturns,
+  ReturnEntry,
+} from "@telorun/http-dispatch";
 import {
   isInvokeError,
   type Invocable,
@@ -11,13 +17,8 @@ import {
 } from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify, { FastifyInstance } from "fastify";
-import {
-  CatchEntry,
-  dispatchCatches,
-  dispatchReturns,
-  HttpServerApi,
-  ReturnEntry,
-} from "./http-api-controller.js";
+import { fastifyReplySink } from "./fastify-reply-sink.js";
+import { HttpServerApi } from "./http-api-controller.js";
 
 type CorsOptions = {
   origin?: string | boolean | string[];
@@ -212,6 +213,13 @@ class HttpServer implements ResourceInstance {
             body: request.body,
           },
         };
+        const acceptHeader = (
+          (request.headers as Record<string, string | string[] | undefined>)["accept"] as
+            | string
+            | undefined
+        )?.toString();
+
+        const sink = fastifyReplySink(reply);
 
         let result: any;
         try {
@@ -222,9 +230,10 @@ class HttpServer implements ResourceInstance {
             handler.catches,
             { code: err.code, message: err.message, data: err.data },
             requestContext,
+            acceptHeader,
             this.ctx.moduleContext,
             this.ctx.validateSchema.bind(this.ctx),
-            reply,
+            sink,
           );
         }
 
@@ -233,9 +242,10 @@ class HttpServer implements ResourceInstance {
             handler.returns,
             result,
             requestContext,
+            acceptHeader,
             this.ctx.moduleContext,
             this.ctx.validateSchema.bind(this.ctx),
-            reply,
+            sink,
           );
         }
         const status = result?.status ?? 200;

package/tests/fastify-reply-sink-contract.test.ts

@@ -0,0 +1,179 @@
+import { runSinkContract, type SinkHandle } from "@telorun/http-dispatch/test-utils";
+import type { CapturedResponse } from "@telorun/http-dispatch/test-utils";
+import type { ResponseSink } from "@telorun/http-dispatch";
+import Fastify from "fastify";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { fastifyReplySink } from "../src/fastify-reply-sink.js";
+
+/** Drives `fastifyReplySink` through the shared `runSinkContract` harness so
+ *  the production Fastify adapter is held to the same status / header / send /
+ *  stream contract as every other transport adapter.
+ *
+ *  The harness expects `setStatus`/`setHeader` to be callable synchronously the
+ *  moment `makeSink()` returns, but Fastify only hands a real `FastifyReply`
+ *  to a handler after a request lands. The wrapper queues sync calls until
+ *  the route handler runs, then replays them against the real sink — async
+ *  calls (`send` / `stream`) wire their returned promise to the real
+ *  operation's outcome so awaiting code sees the correct success/failure.
+ *
+ *  Uses a real listening server (not `app.inject`): light-my-request rejects
+ *  on the destroyed-stream path that mid-flight errors take, which would
+ *  hide whether the partial body actually made it to the wire — exactly the
+ *  thing the contract's stream-failure case asserts. */
+function makeFastifySink(): SinkHandle {
+  type Op = (real: ResponseSink) => void | Promise<void>;
+  const queue: Op[] = [];
+  let real: ResponseSink | undefined;
+  let usedStream = false;
+
+  let resolveResult!: (r: CapturedResponse) => void;
+  let rejectResult!: (e: unknown) => void;
+  const result = new Promise<CapturedResponse>((res, rej) => {
+    resolveResult = res;
+    rejectResult = rej;
+  });
+
+  async function flush(target: ResponseSink): Promise<void> {
+    while (queue.length > 0) {
+      const op = queue.shift()!;
+      await op(target);
+    }
+  }
+
+  const sink: ResponseSink = {
+    setStatus(code) {
+      if (real) {
+        real.setStatus(code);
+        return;
+      }
+      queue.push((s) => s.setStatus(code));
+    },
+    setHeader(name, value) {
+      if (real) {
+        real.setHeader(name, value);
+        return;
+      }
+      queue.push((s) => s.setHeader(name, value));
+    },
+    async send(body) {
+      if (real) {
+        await real.send(body);
+        return;
+      }
+      await new Promise<void>((res, rej) => {
+        queue.push(async (s) => {
+          try {
+            await s.send(body);
+            res();
+          } catch (e) {
+            rej(e);
+          }
+        });
+      });
+    },
+    async stream(iter, onError) {
+      usedStream = true;
+      if (real) {
+        await real.stream(iter, onError);
+        return;
+      }
+      await new Promise<void>((res, rej) => {
+        queue.push(async (s) => {
+          try {
+            await s.stream(iter, onError);
+            res();
+          } catch (e) {
+            rej(e);
+          }
+        });
+      });
+    },
+  };
+
+  const app = Fastify();
+  app.route({
+    method: "POST",
+    url: "/",
+    handler: async (_req, reply) => {
+      real = fastifyReplySink(reply);
+      await flush(real);
+    },
+  });
+
+  void (async () => {
+    try {
+      await app.listen({ host: "127.0.0.1", port: 0 });
+      const addr = app.server.address() as AddressInfo;
+      await new Promise<void>((settle) => {
+        let settled = false;
+        const finish = (build: () => CapturedResponse) => {
+          if (settled) return;
+          settled = true;
+          try {
+            resolveResult(build());
+          } catch (e) {
+            rejectResult(e);
+          }
+          settle();
+        };
+
+        const req = http.request({
+          host: addr.address,
+          port: addr.port,
+          path: "/",
+          method: "POST",
+        });
+        req.on("error", (e) => {
+          if (settled) return;
+          settled = true;
+          rejectResult(e);
+          settle();
+        });
+        req.on("response", (res) => {
+          const chunks: Buffer[] = [];
+          res.on("data", (c) => chunks.push(c as Buffer));
+          // Both `end` (clean) and `close`/`aborted` (mid-stream destroy) end
+          // the response from the client's perspective. The contract treats
+          // both as terminal: whatever bytes arrived are the captured body,
+          // and `onError` (if provided) was already invoked on the server.
+          const buildCaptured = (): CapturedResponse => {
+            let total = 0;
+            for (const c of chunks) total += c.byteLength;
+            const body = new Uint8Array(total);
+            let off = 0;
+            for (const c of chunks) {
+              body.set(c, off);
+              off += c.byteLength;
+            }
+            const headers: Record<string, string> = {};
+            for (const [k, v] of Object.entries(res.headers)) {
+              if (v == null) continue;
+              headers[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : String(v);
+            }
+            return {
+              status: res.statusCode ?? 0,
+              headers,
+              body,
+              isStream: usedStream,
+            };
+          };
+          res.on("end", () => finish(buildCaptured));
+          res.on("close", () => finish(buildCaptured));
+          res.on("aborted", () => finish(buildCaptured));
+        });
+        req.end();
+      });
+    } catch (e) {
+      rejectResult(e);
+    } finally {
+      await app.close().catch(() => {
+        /* server close after partial-response abort can race; harmless */
+      });
+    }
+  })();
+
+  return { sink, result };
+}
+
+runSinkContract("fastifyReplySink", makeFastifySink);

package/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "extends": "../../../tsconfig.base.json",
   "files": [],
-  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
   "compilerOptions": {
     "strict": true,
     "esModuleInterop": true

package/tsconfig.spec.json

@@ -1,10 +1,10 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "strict": true,
     "esModuleInterop": true,
-    "types": ["node", "jest"]
+    "types": ["node"]
   },
   "files": [],
-  "include": ["test/**/*.ts"]
+  "include": ["tests/**/*.ts"]
 }