@telorun/http-server 0.3.1 → 0.3.2

package/dist/http-api-controller.js

@@ -1,35 +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 { Readable } from "stream";
-import { pipeline } from "stream/promises";
-/** Per-MIME content-map entry. Buffer-mode responses use `body` (with optional
- *  `schema` for AJV validation); stream-mode responses use `encoder` (a ref to
- *  any `Codec.Encoder` implementation). The two are mutually exclusive per
- *  value — see dispatch logic. `headers` here merge over the entry-level
- *  `headers` (per-MIME wins on conflict). `Content-Type` is forbidden in
- *  headers — the map key IS the canonical Content-Type. */
-const ContentEntry = Type.Object({
-    body: Type.Optional(Type.Any()),
-    schema: Type.Optional(Type.Any()),
-    encoder: Type.Optional(Type.Unsafe(Ref("std/codec#Encoder"))),
-    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-});
-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")])),
-    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-    content: Type.Optional(Type.Record(Type.String(), ContentEntry)),
-});
-const CatchEntry = Type.Object({
-    status: Type.Integer({ minimum: 100, maximum: 599 }),
-    when: Type.Optional(Type.String()),
-    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-    // Catches are buffer-mode only — no `mode` or `encoder` fields. By the time
-    // a catch fires, the response is committed pre-stream and there's no upstream
-    // iterable to feed an encoder. content[mime] carries body/schema/headers only.
-    content: Type.Optional(Type.Record(Type.String(), ContentEntry)),
-});
+import { fastifyReplySink } from "./fastify-reply-sink.js";
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
         path: Type.String(),
@@ -50,249 +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;
-}
-/** Parse an `Accept` header into an array of `{type, q}` entries. Missing or
- *  empty headers default to `*\/*; q=1`. */
-function parseAccept(header) {
-    if (!header || !header.trim())
-        return [{ type: "*/*", q: 1 }];
-    return header.split(",").map((part) => {
-        const [mediaType, ...params] = part.trim().split(";").map((s) => s.trim());
-        let q = 1;
-        for (const p of params) {
-            if (p.toLowerCase().startsWith("q=")) {
-                const parsed = parseFloat(p.slice(2));
-                if (!Number.isNaN(parsed))
-                    q = parsed;
-            }
-        }
-        return { type: (mediaType ?? "").toLowerCase(), q };
-    });
-}
-/** Returns the highest q-value an `Accept` entry assigns to `mime`, or
- *  `undefined` if no Accept entry matches (or every match has q=0). Supports
- *  exact (`type/sub`), type-wildcard (`type/*`) and full-wildcard (`*\/*`). */
-function matchAcceptForMime(mime, accepts) {
-    const lc = mime.toLowerCase();
-    const top = lc.split(";")[0];
-    const slash = top.indexOf("/");
-    const major = slash === -1 ? top : top.slice(0, slash);
-    let best;
-    for (const a of accepts) {
-        if (a.q <= 0)
-            continue;
-        if (a.type === top || a.type === `${major}/*` || a.type === "*/*") {
-            if (best === undefined || a.q > best)
-                best = a.q;
-        }
-    }
-    return best;
-}
-/** Pick the best content[mime] key per RFC 9110 §12.5.1 — highest q-value wins,
- *  declaration order breaks ties, q=0 excludes. Returns `undefined` when no
- *  available key matches the Accept header at any positive q-value. */
-function negotiateContent(contentKeys, acceptHeader) {
-    if (contentKeys.length === 0)
-        return undefined;
-    if (contentKeys.length === 1) {
-        // Single-key map: skip negotiation entirely. The author has committed to
-        // one Content-Type; either the client accepts it (any way) or 406 falls
-        // out below.
-        const accepts = parseAccept(acceptHeader);
-        const q = matchAcceptForMime(contentKeys[0], accepts);
-        return q === undefined ? undefined : contentKeys[0];
-    }
-    const accepts = parseAccept(acceptHeader);
-    let best;
-    for (let i = 0; i < contentKeys.length; i++) {
-        const mime = contentKeys[i];
-        const q = matchAcceptForMime(mime, accepts);
-        if (q === undefined)
-            continue;
-        if (!best || q > best.q || (q === best.q && i < best.index)) {
-            best = { mime, q, index: i };
-        }
-    }
-    return best?.mime;
-}
-/** Apply entry-level + per-MIME headers, with per-MIME winning on conflict.
- *  CEL templates in either map are expanded against `celCtx`. */
-function applyHeaders(entryHeaders, contentHeaders, celCtx, moduleContext, reply) {
-    for (const headers of [entryHeaders, contentHeaders]) {
-        if (!headers)
-            continue;
-        const expanded = moduleContext.expandWith(headers, celCtx);
-        for (const [key, value] of Object.entries(expanded)) {
-            reply.header(key, value);
-        }
-    }
-}
-export async function dispatchReturns(returns, result, requestContext, acceptHeader, moduleContext, validateSchema, reply, streamError) {
-    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)");
-    }
-    // Status codes with no body (204, 304, etc.) — entry has no `content:` map.
-    if (!entry.content || Object.keys(entry.content).length === 0) {
-        reply.code(entry.status);
-        applyHeaders(entry.headers, undefined, celCtx, moduleContext, reply);
-        reply.send();
-        return;
-    }
-    const contentKeys = Object.keys(entry.content);
-    const matchedMime = negotiateContent(contentKeys, acceptHeader);
-    if (!matchedMime) {
-        // No Accept-header match at any positive q-value — RFC 9110 §15.5.7.
-        reply.code(406);
-        reply.header("Content-Type", "application/json");
-        reply.send({
-            error: {
-                code: "NOT_ACCEPTABLE",
-                message: "No representation matched the Accept header.",
-                available: contentKeys,
-            },
-        });
-        return;
-    }
-    const contentEntry = entry.content[matchedMime];
-    reply.code(entry.status);
-    reply.header("Content-Type", matchedMime);
-    applyHeaders(entry.headers, contentEntry.headers, celCtx, moduleContext, reply);
-    if (entry.mode === "stream") {
-        if (!contentEntry.encoder) {
-            throw new Error(`Stream-mode return for status ${entry.status} content[${matchedMime}] is missing an encoder.`);
-        }
-        const encoderInstance = contentEntry.encoder;
-        if (typeof encoderInstance.invoke !== "function") {
-            throw new Error(`Encoder ref for status ${entry.status} content[${matchedMime}] is not a live Invocable — Phase 5 injection may have failed.`);
-        }
-        const handlerOutput = result
-            ?.output;
-        if (!handlerOutput || typeof handlerOutput[Symbol.asyncIterator] !== "function") {
-            throw new Error(`Stream-mode handler did not return { output: AsyncIterable<...> } for status ${entry.status} content[${matchedMime}]; got ${typeof handlerOutput}.`);
-        }
-        const encoded = (await encoderInstance.invoke({ input: handlerOutput }));
-        if (!encoded || typeof encoded.output?.[Symbol.asyncIterator] !== "function") {
-            throw new Error(`Encoder for status ${entry.status} content[${matchedMime}] did not return { output: AsyncIterable<Uint8Array> }.`);
-        }
-        reply.hijack();
-        reply.raw.writeHead(entry.status, reply.getHeaders());
-        // Readable.from wraps the AsyncIterable; pipeline() handles backpressure
-        // and propagates client disconnect back through the iterator chain via
-        // .return(), which unwinds the encoder's `for await` and reaches the
-        // source's `.return()` (e.g. cancelling a provider's streamText call).
-        //
-        // Once headers are flushed, mid-stream failures (encoder throw, broken
-        // pipe, etc.) cannot trigger `catches:` — the response is committed.
-        // Surface them via `streamError` so operators can see what's bypassing
-        // the catch chain by design. The socket will close; we don't rethrow
-        // because Fastify can't render anything useful past hijack().
-        try {
-            await pipeline(Readable.from(encoded.output), reply.raw);
-        }
-        catch (err) {
-            if (streamError) {
-                try {
-                    await streamError(err, { status: entry.status, mime: matchedMime });
-                }
-                catch {
-                    /* operator hook should never fail the response — swallow */
-                }
-            }
-        }
-        return;
-    }
-    // Buffer mode (default).
-    if (contentEntry.body !== undefined) {
-        const mappedBody = moduleContext.expandWith(contentEntry.body, celCtx);
-        if (contentEntry.schema)
-            validateSchema(mappedBody, contentEntry.schema);
-        reply.send(mappedBody);
-        return;
-    }
-    // No explicit body — fall through to sending the handler's result as-is.
-    // Preserves the legacy "reply.send(result)" shorthand for routes whose
-    // handler already returns the right shape.
-    if (contentEntry.schema)
-        validateSchema(result, contentEntry.schema);
-    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.
- *
- *  Catches are buffer-mode only by design: by the time a catch fires the
- *  response is committed pre-stream and there's no upstream iterable to feed
- *  an encoder. content[mime] entries carry body/schema/headers; encoder/mode
- *  fields are not part of the catch schema. */
-export async function dispatchCatches(catches, error, requestContext, acceptHeader, moduleContext, validateSchema, reply) {
-    const celCtx = { error, ...requestContext };
-    const entry = catches ? matchEntry(catches, celCtx, moduleContext) : undefined;
-    if (!entry) {
-        reply.code(500);
-        reply.header("Content-Type", "application/json");
-        reply.send({
-            error: { code: error.code, message: error.message, data: error.data },
-        });
-        return;
-    }
-    if (!entry.content || Object.keys(entry.content).length === 0) {
-        reply.code(entry.status);
-        applyHeaders(entry.headers, undefined, celCtx, moduleContext, reply);
-        reply.send();
-        return;
-    }
-    const contentKeys = Object.keys(entry.content);
-    const matchedMime = negotiateContent(contentKeys, acceptHeader);
-    if (!matchedMime) {
-        reply.code(406);
-        reply.header("Content-Type", "application/json");
-        reply.send({
-            error: {
-                code: "NOT_ACCEPTABLE",
-                message: "No catch representation matched the Accept header.",
-                available: contentKeys,
-            },
-        });
-        return;
-    }
-    const contentEntry = entry.content[matchedMime];
-    reply.code(entry.status);
-    reply.header("Content-Type", matchedMime);
-    applyHeaders(entry.headers, contentEntry.headers, celCtx, moduleContext, reply);
-    if (contentEntry.body !== undefined) {
-        const mappedBody = moduleContext.expandWith(contentEntry.body, celCtx);
-        if (contentEntry.schema)
-            validateSchema(mappedBody, contentEntry.schema);
-        reply.send(mappedBody);
-        return;
-    }
-    // Default error envelope when no body is given. The matched MIME may be
-    // text/plain (or any non-JSON shape) — the negotiated Content-Type would
-    // lie about a JSON payload. Override to application/json to keep the
-    // envelope honest. Authors who want the matched MIME on the wire must
-    // provide an explicit `body:` for that content[mime] entry.
-    reply.header("Content-Type", "application/json");
-    reply.send({ error: { code: error.code, message: error.message, data: error.data } });
-}
 export class HttpServerApi {
     ctx;
     manifest;
@@ -372,6 +101,7 @@ export class HttpServerApi {
                     ...resolvedInputs,
                     inputs: resolvedInputs,
                 };
+                const sink = fastifyReplySink(reply);
                 let result;
                 try {
                     result = handler
@@ -381,9 +111,9 @@ export class HttpServerApi {
                 catch (err) {
                     if (!isInvokeError(err))
                         throw err;
-                    return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, acceptHeader, 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, acceptHeader, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply, (err, errCtx) => this.ctx.emitEvent("Http.Api.streamFailed", {
+                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,
@@ -399,7 +129,6 @@ export class HttpServerApi {
 export async function create(resource, ctx) {
     ctx.validateSchema(resource, HttpApiManifest);
     validateNoContentTypeHeader(resource);
-    validateContentEntryShape(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
@@ -421,160 +150,6 @@ export async function create(resource, ctx) {
     }
     return new HttpServerApi(ctx, resource, handlerRefs);
 }
-/** Rejects `Content-Type` (case-insensitive) anywhere in entry-level or
- *  per-MIME `headers:` blocks. The matched `content[mime]` map key IS the
- *  canonical Content-Type — declaring it again in `headers:` would either be
- *  redundant or contradictory. */
-export function validateNoContentTypeHeader(resource) {
-    for (const route of resource.routes ?? []) {
-        const path = route.request?.path ?? "<unknown>";
-        for (const list of [route.returns, route.catches]) {
-            if (!list)
-                continue;
-            for (const entry of list) {
-                rejectContentTypeIn(entry.headers, `${path} entry-level headers`);
-                if (!entry.content)
-                    continue;
-                for (const [mime, c] of Object.entries(entry.content)) {
-                    rejectContentTypeIn(c.headers, `${path} content[${mime}].headers`);
-                }
-            }
-        }
-    }
-}
-function rejectContentTypeIn(headers, where) {
-    if (!headers)
-        return;
-    for (const key of Object.keys(headers)) {
-        if (key.toLowerCase() === "content-type") {
-            throw new Error(`Http.Api: '${where}' declares 'Content-Type' — forbidden. The matched content[mime] map key is the only Content-Type source.`);
-        }
-    }
-}
-/** Enforces per-mode shape rules on every `content[mime]` value:
- *   - `body` and `encoder` are mutually exclusive. Declaring both is rejected
- *     because dispatch would silently pick one based on entry `mode:` and the
- *     other becomes a no-op — a correctness footgun.
- *   - `mode: stream` requires every content[mime] to declare `encoder` (and
- *     forbids `body`). Without this check, an entry with one encoder-bearing
- *     key plus a body-only key would pass at load and only fail at runtime
- *     when the body-only key won negotiation — leaving a half-broken route.
- *   - `mode: buffer` (the default) forbids `encoder` (which would never run). */
-export function validateContentEntryShape(resource) {
-    for (const route of resource.routes ?? []) {
-        const path = route.request?.path ?? "<unknown>";
-        for (const entry of route.returns ?? []) {
-            const isStream = entry.mode === "stream";
-            // Stream mode requires a non-empty content map — without one the
-            // dispatcher would silently send an empty 200, masking the misconfig.
-            // Buffer mode (default) tolerates missing content (e.g. 204/304-style
-            // empty responses); the dispatcher renders status-only in that case.
-            if (isStream && (!entry.content || Object.keys(entry.content).length === 0)) {
-                throw new Error(`Http.Api: '${path}' status ${entry.status} mode: stream is missing 'content:'. ` +
-                    `Stream-mode entries must declare at least one content[mime] with an encoder.`);
-            }
-            if (!entry.content)
-                continue;
-            for (const [mime, c] of Object.entries(entry.content)) {
-                const value = c;
-                const hasBody = value.body !== undefined;
-                const hasEncoder = value.encoder !== undefined;
-                if (hasBody && hasEncoder) {
-                    throw new Error(`Http.Api: '${path}' content[${mime}] declares both 'body' and 'encoder' — forbidden. ` +
-                        `Buffer-mode entries use 'body'; stream-mode entries use 'encoder'.`);
-                }
-                if (isStream && !hasEncoder) {
-                    throw new Error(`Http.Api: '${path}' status ${entry.status} mode: stream content[${mime}] is missing 'encoder'. ` +
-                        `Every content[mime] under a stream-mode return must declare an encoder.`);
-                }
-                if (isStream && hasBody) {
-                    throw new Error(`Http.Api: '${path}' status ${entry.status} mode: stream content[${mime}] declares 'body' — forbidden. ` +
-                        `Stream-mode entries use 'encoder', not 'body'.`);
-                }
-                if (!isStream && hasEncoder) {
-                    throw new Error(`Http.Api: '${path}' status ${entry.status} content[${mime}] declares 'encoder' but mode is 'buffer' (default) — ` +
-                        `the encoder would never run. Set mode: stream, or use 'body' for buffer-mode responses.`);
-                }
-            }
-        }
-    }
-}
-/** Rejects `when:` CEL expressions on stream-mode `returns:` entries that
- *  reference the root `result` identifier. The handler result in stream mode
- *  is an unconsumed `Stream<...>`; iterating it to evaluate the predicate
- *  would either fail or consume the stream before bytes flow to the response.
- *  References to `request.*` are fine — they don't touch the stream.
- *
- *  This is a runtime safety net; the analyzer's static chain validator is
- *  authoritative. The check here is intentionally token-aware (skips string
- *  literals and `.result` member access) so it doesn't false-positive on
- *  benign expressions like `request.headers["x-result"]`. */
-export function validateStreamWhenDoesNotReferenceResult(resource) {
-    for (const route of resource.routes ?? []) {
-        const path = route.request?.path ?? "<unknown>";
-        for (const entry of route.returns ?? []) {
-            if (entry.mode !== "stream" || !entry.when)
-                continue;
-            // `when:` survived precompilation as a CompiledValue (or a raw string
-            // when no template was applied). Inspect the source text via a token
-            // walker — naive `\bresult\b` would false-positive inside string
-            // literals and on `.result` property paths.
-            const source = typeof entry.when === "string"
-                ? entry.when
-                : entry.when?.source ?? "";
-            if (referencesRootIdentifier(source, "result")) {
-                throw new Error(`Http.Api: '${path}' returns entry with mode: stream — 'when:' references the root 'result' identifier. ` +
-                    `The handler result is an unconsumed Stream and cannot be inspected from CEL. ` +
-                    `Reference only request.* in stream-mode 'when:' predicates.`);
-            }
-        }
-    }
-}
-/** True if `source` contains a free-standing CEL identifier `target` —
- *  i.e. it appears as a root identifier (not preceded by `.`, not part of
- *  another word) and not inside a single- or double-quoted string literal.
- *  Token-aware so members like `request.result_count` and string literals
- *  like `'my result'` don't trigger a match. */
-function referencesRootIdentifier(source, target) {
-    let i = 0;
-    let inString = null;
-    while (i < source.length) {
-        const ch = source[i];
-        if (inString) {
-            if (ch === "\\") {
-                i += 2;
-                continue;
-            }
-            if (ch === inString)
-                inString = null;
-            i++;
-            continue;
-        }
-        if (ch === '"' || ch === "'") {
-            inString = ch;
-            i++;
-            continue;
-        }
-        if (/[A-Za-z_]/.test(ch)) {
-            let j = i;
-            while (j < source.length && /[A-Za-z0-9_]/.test(source[j]))
-                j++;
-            const word = source.slice(i, j);
-            // Walk back over whitespace; if the previous non-whitespace char is `.`,
-            // this identifier is a member access, not a root identifier.
-            let k = i - 1;
-            while (k >= 0 && /\s/.test(source[k]))
-                k--;
-            const isMember = k >= 0 && source[k] === ".";
-            if (word === target && !isMember)
-                return true;
-            i = j;
-            continue;
-        }
-        i++;
-    }
-    return false;
-}
 /**
  * Translates OpenAPI path format {paramName} to Fastify format :paramName
  * Example: /api/v1/users/{userId} -> /api/v1/users/:userId

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;
@@ -136,6 +137,7 @@ class HttpServer {
                     },
                 };
                 const acceptHeader = request.headers["accept"]?.toString();
+                const sink = fastifyReplySink(reply);
                 let result;
                 try {
                     result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
@@ -143,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, acceptHeader, 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, acceptHeader, 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.3.1",
+  "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.7.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.
+      }
+    },
+  };
+}