@telorun/http-server 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @telorun/http-server
 
+## 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/dist/http-api-controller.d.ts

@@ -1,28 +1,42 @@
 import { Static } from "@sinclair/typebox";
 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">]>>;
-    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>>;
+    }>>>;
 }>;
 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>;
+    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>;
 declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
@@ -43,46 +57,60 @@ declare const HttpApiManifest: 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>;
+            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>;
-            }>>;
             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>>;
+            }>>>;
         }>>>;
     }>>;
 }>;
 type HttpApiManifest = Static<typeof HttpApiManifest>;
 export declare function register(_ctx: ControllerContext): Promise<void>;
-export type { ReturnEntry, CatchEntry };
+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;
 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>;
+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. */
+ *  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>, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply): Promise<void>;
+}, 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;
@@ -94,3 +122,51 @@ 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;