@telorun/http-server 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @telorun/http-server
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [1a3c226]
+  - @telorun/http-dispatch@0.2.1
+
+## 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 `modules/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

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,44 +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";
-/** 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. */
-declare const ContentEntry: 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>>;
-}>;
-type ContentEntry = Static<typeof ContentEntry>;
-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">]>>;
-    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
-    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>>;
-    }>>>;
-}>;
-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>;
-    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
-    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>>;
-    }>>>;
-}>;
-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<{
@@ -55,7 +18,7 @@ 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">]>>;
             headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
             content: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
@@ -67,12 +30,11 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
         }>>;
         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>;
+            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>>;
             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>>;
             }>>>;
         }>>>;
@@ -80,37 +42,11 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
 }>;
 type HttpApiManifest = Static<typeof HttpApiManifest>;
 export declare function register(_ctx: ControllerContext): Promise<void>;
-export type { ReturnEntry, CatchEntry, ContentEntry };
-type ModuleLikeContext = {
-    expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
-};
-type ValidateSchema = (value: unknown, schema: unknown) => void;
-/** Hook invoked when `pipeline()` rejects after `reply.hijack()` — at that
- *  point headers are flushed, the response is committed, and `catches:`
- *  cannot fire. Surfacing the failure here lets operators observe mid-stream
- *  failures that are otherwise silent. */
-type StreamErrorHook = (err: unknown, ctx: {
-    status: number;
-    mime: string;
-}) => Promise<void> | void;
+export type { CatchEntry, ContentEntry, ReturnEntry };
 type HandlerRef = {
     kind: string;
     name: string;
 };
-export declare function dispatchReturns(returns: ReturnEntry[], result: unknown, requestContext: Record<string, unknown>, acceptHeader: string | undefined, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply, streamError?: StreamErrorHook): 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.
- *
- *  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 declare function dispatchCatches(catches: CatchEntry[] | undefined, error: {
-    code: string;
-    message: string;
-    data?: unknown;
-}, requestContext: Record<string, unknown>, acceptHeader: string | undefined, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply): Promise<void>;
 export declare class HttpServerApi implements ResourceInstance {
     private readonly ctx;
     readonly manifest: HttpApiManifest;
@@ -122,51 +58,3 @@ export declare class HttpServerApi implements ResourceInstance {
     private registerRoute;
 }
 export declare function create(resource: any, ctx: ResourceContext): Promise<HttpServerApi>;
-/** 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 declare function validateNoContentTypeHeader(resource: {
-    routes?: Array<{
-        request?: {
-            path?: string;
-        };
-        returns?: ReturnEntry[];
-        catches?: CatchEntry[];
-    }>;
-}): void;
-/** 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 declare function validateContentEntryShape(resource: {
-    routes?: Array<{
-        request?: {
-            path?: string;
-        };
-        returns?: ReturnEntry[];
-    }>;
-}): void;
-/** 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 declare function validateStreamWhenDoesNotReferenceResult(resource: {
-    routes?: Array<{
-        request?: {
-            path?: string;
-        };
-        returns?: ReturnEntry[];
-    }>;
-}): void;