@telorun/http-server 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @telorun/http-server
 
+## 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, 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();
@@ -157,6 +161,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.7.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.18.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -11,11 +11,13 @@ import {
 import {
   ControllerContext,
   Invocable,
+  InvokeError,
   isInvokeError,
   KindRef,
   Ref,
   ResourceContext,
   ResourceInstance,
+  Stream,
 } from "@telorun/sdk";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
@@ -90,9 +92,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 +128,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 = (
@@ -213,6 +220,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" },