@telorun/http-server 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @telorun/http-server
 
+## 0.8.0
+
+### Minor Changes
+
+- 5331205: Add cooperative invoke cancellation via an out-of-band `InvokeContext`.
+
+  Every `invoke(inputs, ctx?)` now receives a second argument carrying a read-only
+  cancellation token (`ctx.cancellation`): poll `isCancelled`, subscribe via
+  `onCancelled`, bail with `throwIfCancelled`, or hand its `signal` to a Web API.
+  The SDK exposes the source/token split (`createCancellationSource`,
+  `CancellationSource`/`CancellationToken`), a never-cancellable sentinel, and the
+  `isCancellationError` helper. Deadlines are scheduled cancellation
+  (`source.cancelAt(epochMs)` / `cancelAfter(ms)`).
+
+  The kernel mints one cancellation scope per invocation tree (inherited by nested
+  invokes via a kernel-internal `AsyncLocalStorage`, always passed to controllers
+  as the explicit argument), refuses a not-yet-dispatched invoke whose tree was
+  cancelled with `ERR_INVOKE_CANCELLED`, and emits a scoped `InvokeCancelled`
+  event. `Kernel.invoke(ref, inputs, opts?)` accepts `{ signal, deadlineAt }`.
+  Sources are allocated lazily, so invokes that never touch cancellation pay no
+  extra allocation.
+
+  The boot `targets` run is also cancellable: `Runnable.run(ctx?)` now receives
+  the token, `Kernel.cancel(reason?)` cancels the boot scope, and the CLI's
+  SIGINT/SIGTERM handler calls it so Ctrl-C cooperatively stops honoring targets
+  and in-flight invoke trees (then unblocks graceful exit via `forceIdle`).
+
+  Honoring leaves: `Ai.Text` / `Ai.TextStream` / `Ai.Agent` forward the token's
+  signal into the model (aborting a live LLM stream on cancel); `http-client`
+  merges it with its request timeout. Triggers: `http-server` cancels on client
+  disconnect and returns 499; `lambda` arms cancellation at the AWS deadline.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
+## 0.7.0
+
+### Minor Changes
+
+- 030bfdd: Support binary request bodies. An `Http.Server` `contentTypeParsers` entry may declare `stream: true` to deliver bodies of that content type to the handler as a raw `Stream<Uint8Array>` — no buffering, no parsing. A route opts in by marking its `request.schema.body` with `x-telo-stream: true`, which skips AJV on the body and surfaces `request.body` as a stream in handler CEL (member access past it is a static error). A content type on one server is either streamed or parsed, never both.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -23,16 +23,11 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 ```yaml
 kind: Telo.Application
 metadata: { name: hello-http, version: 1.0.0 }
+imports:
+  Http: pkg:npm/@telorun/http-server@^1.0.0
+  JS: pkg:npm/@telorun/javascript@^1.0.0
 targets: [Server]
 ---
-kind: Telo.Import
-metadata: { name: Http }
-source: pkg:npm/@telorun/http-server@^1.0.0
----
-kind: Telo.Import
-metadata: { name: JS }
-source: pkg:npm/@telorun/javascript@^1.0.0
----
 kind: Http.Server
 metadata: { name: Server }
 port: 8080

package/dist/http-api-controller.js

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { CatchEntry, dispatchCatches, dispatchReturns, ReturnEntry, validateNoContentTypeHeader, validateStreamWhenDoesNotReferenceResult, } from "@telorun/http-dispatch";
-import { isInvokeError, Ref, } from "@telorun/sdk";
+import { InvokeError, isCancellationError, isInvokeError, Ref, Stream, } from "@telorun/sdk";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
@@ -56,11 +56,15 @@ export class HttpServerApi {
         const handlerName = handlerRef?.name ?? "";
         const translatedPath = translateOpenApiPath(route.request.path);
         const schema = { response: {} };
+        // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
+        // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
+        // body-schema registration and wrap the raw request stream in the handler.
+        const streamBody = route.request.schema?.body?.["x-telo-stream"] === true;
         if (route.request.schema?.query)
             schema.querystring = route.request.schema.query;
         if (route.request.schema?.params)
             schema.params = route.request.schema.params;
-        if (route.request.schema?.body)
+        if (route.request.schema?.body && !streamBody)
             schema.body = route.request.schema.body;
         if (route.request.schema?.headers)
             schema.headers = route.request.schema.headers;
@@ -90,7 +94,7 @@ export class HttpServerApi {
                         params: request.params || {},
                         query: request.query || {},
                         headers: normalizeHeaders(request.headers),
-                        body: request.body,
+                        body: streamBody ? toByteStream(request) : request.body,
                     },
                 };
                 const acceptHeader = request.headers["accept"]?.toString();
@@ -102,13 +106,25 @@ export class HttpServerApi {
                     inputs: resolvedInputs,
                 };
                 const sink = fastifyReplySink(reply);
+                // Per-request cancellation: abandon downstream work when the client
+                // disconnects before the response is sent.
+                const cancellation = this.ctx.createCancellationSource();
+                request.raw.on("close", () => {
+                    if (!reply.sent)
+                        cancellation.cancel("client-disconnect");
+                });
                 let result;
                 try {
                     result = handler
-                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput)
+                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput, cancellation.context)
                         : undefined;
                 }
                 catch (err) {
+                    if (isCancellationError(err)) {
+                        if (!reply.sent)
+                            reply.code(499).send();
+                        return;
+                    }
                     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), sink);
@@ -157,6 +173,29 @@ export async function create(resource, ctx) {
 function translateOpenApiPath(openApiPath) {
     return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
 }
+/**
+ * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
+ * stream content-type parser (`contentTypeParsers[].stream`) for the request's
+ * Content-Type — only then is `request.body` the undrained payload stream.
+ * Without one, Fastify has already consumed the socket to build a string/object
+ * body, so `request.raw` is drained; fail fast with an actionable error rather
+ * than yield an empty stream or hang.
+ */
+function toByteStream(request) {
+    const body = request.body;
+    if (!body || typeof body[Symbol.asyncIterator] !== "function") {
+        const contentType = request.headers["content-type"] ?? "(none)";
+        throw new InvokeError("ERR_REQUEST_BODY_NOT_STREAMED", `Route declares an x-telo-stream request body, but the body for content-type ` +
+            `"${contentType}" arrived parsed, not streamed. Register a raw stream parser on ` +
+            `the Http.Server: contentTypeParsers: [{ contentType: "${contentType}", stream: true }].`);
+    }
+    return new Stream(toUint8Chunks(body));
+}
+async function* toUint8Chunks(source) {
+    for await (const chunk of source) {
+        yield chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+    }
+}
 /**
  * Normalizes all header keys to lowercase as per Telo spec
  */

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

@@ -23,6 +23,7 @@ type HttpServerResource = RuntimeResource & {
     contentTypeParsers?: Array<{
         contentType: string;
         parser?: Invocable;
+        stream?: boolean;
     }>;
     openapi?: {
         info: {

package/dist/http-server-controller.js

@@ -39,8 +39,16 @@ class HttpServer {
         this.setupRoutes();
     }
     async setupPlugins() {
-        for (const { contentType, parser } of this.resource.contentTypeParsers ?? []) {
-            if (parser) {
+        for (const { contentType, parser, stream } of this.resource.contentTypeParsers ?? []) {
+            if (stream) {
+                // Raw passthrough: omit `parseAs` so Fastify hands the handler the
+                // undrained request stream. The matching route wraps `request.body`
+                // in a `Stream<Uint8Array>`. No buffering, no AJV — see http-api-controller.
+                this.app.addContentTypeParser(contentType, (_req, payload, done) => {
+                    done(null, payload);
+                });
+            }
+            else if (parser) {
                 this.app.addContentTypeParser(contentType, { parseAs: "string" }, async (_req, body, done) => {
                     try {
                         done(null, await parser.invoke({ body }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -49,7 +49,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.16.0"
+    "@telorun/sdk": "0.19.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -11,11 +11,14 @@ import {
 import {
   ControllerContext,
   Invocable,
+  InvokeError,
+  isCancellationError,
   isInvokeError,
   KindRef,
   Ref,
   ResourceContext,
   ResourceInstance,
+  Stream,
 } from "@telorun/sdk";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
@@ -90,9 +93,14 @@ export class HttpServerApi implements ResourceInstance {
 
     const schema: any = { response: {} };
 
+    // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
+    // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
+    // body-schema registration and wrap the raw request stream in the handler.
+    const streamBody = route.request.schema?.body?.["x-telo-stream"] === true;
+
     if (route.request.schema?.query) schema.querystring = route.request.schema.query;
     if (route.request.schema?.params) schema.params = route.request.schema.params;
-    if (route.request.schema?.body) schema.body = route.request.schema.body;
+    if (route.request.schema?.body && !streamBody) 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
@@ -121,7 +129,7 @@ export class HttpServerApi implements ResourceInstance {
             params: request.params || {},
             query: request.query || {},
             headers: normalizeHeaders(request.headers),
-            body: request.body,
+            body: streamBody ? toByteStream(request) : request.body,
           },
         };
         const acceptHeader = (
@@ -139,12 +147,29 @@ export class HttpServerApi implements ResourceInstance {
 
         const sink = fastifyReplySink(reply);
 
+        // Per-request cancellation: abandon downstream work when the client
+        // disconnects before the response is sent.
+        const cancellation = this.ctx.createCancellationSource();
+        request.raw.on("close", () => {
+          if (!reply.sent) cancellation.cancel("client-disconnect");
+        });
+
         let result: unknown;
         try {
           result = handler
-            ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput)
+            ? await this.ctx.invokeResolved(
+                handlerKind,
+                handlerName,
+                handler,
+                invokeInput,
+                cancellation.context,
+              )
             : undefined;
         } catch (err) {
+          if (isCancellationError(err)) {
+            if (!reply.sent) reply.code(499).send();
+            return;
+          }
           if (!isInvokeError(err)) throw err;
           return dispatchCatches(
             route.catches,
@@ -213,6 +238,36 @@ function translateOpenApiPath(openApiPath: string): string {
   return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
 }
 
+/**
+ * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
+ * stream content-type parser (`contentTypeParsers[].stream`) for the request's
+ * Content-Type — only then is `request.body` the undrained payload stream.
+ * Without one, Fastify has already consumed the socket to build a string/object
+ * body, so `request.raw` is drained; fail fast with an actionable error rather
+ * than yield an empty stream or hang.
+ */
+function toByteStream(request: FastifyRequest): Stream<Uint8Array> {
+  const body = request.body as unknown;
+  if (!body || typeof (body as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] !== "function") {
+    const contentType = (request.headers["content-type"] as string | undefined) ?? "(none)";
+    throw new InvokeError(
+      "ERR_REQUEST_BODY_NOT_STREAMED",
+      `Route declares an x-telo-stream request body, but the body for content-type ` +
+        `"${contentType}" arrived parsed, not streamed. Register a raw stream parser on ` +
+        `the Http.Server: contentTypeParsers: [{ contentType: "${contentType}", stream: true }].`,
+    );
+  }
+  return new Stream(toUint8Chunks(body as AsyncIterable<Uint8Array | Buffer>));
+}
+
+async function* toUint8Chunks(
+  source: AsyncIterable<Uint8Array | Buffer>,
+): AsyncIterable<Uint8Array> {
+  for await (const chunk of source) {
+    yield chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+  }
+}
+
 /**
  * Normalizes all header keys to lowercase as per Telo spec
  */

package/src/http-server-controller.ts

@@ -41,7 +41,7 @@ type HttpServerResource = RuntimeResource & {
   baseUrl?: string;
   logger?: boolean;
   cors?: CorsOptions;
-  contentTypeParsers?: Array<{ contentType: string; parser?: Invocable }>;
+  contentTypeParsers?: Array<{ contentType: string; parser?: Invocable; stream?: boolean }>;
   openapi?: {
     info: {
       title: string;
@@ -109,8 +109,15 @@ class HttpServer implements ResourceInstance {
   }
 
   private async setupPlugins() {
-    for (const { contentType, parser } of this.resource.contentTypeParsers ?? []) {
-      if (parser) {
+    for (const { contentType, parser, stream } of this.resource.contentTypeParsers ?? []) {
+      if (stream) {
+        // Raw passthrough: omit `parseAs` so Fastify hands the handler the
+        // undrained request stream. The matching route wraps `request.body`
+        // in a `Stream<Uint8Array>`. No buffering, no AJV — see http-api-controller.
+        this.app.addContentTypeParser(contentType, (_req, payload, done) => {
+          done(null, payload);
+        });
+      } else if (parser) {
         this.app.addContentTypeParser(
           contentType,
           { parseAs: "string" },