@telorun/http-server 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @telorun/http-server
 
+## 0.1.5
+
+### Patch Changes
+
+- Automated release.
+- Updated dependencies
+  - @telorun/sdk@0.2.6
+
 ## 0.1.4
 
 ### Patch Changes

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

@@ -1,6 +1,32 @@
 import { Static } from "@sinclair/typebox";
-import { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
-import { FastifyInstance } from "fastify";
+import { ControllerContext, Invocable, KindRef, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { FastifyInstance, FastifyReply } from "fastify";
+declare const HttpApiRouteManifest: import("@sinclair/typebox").TObject<{
+    request: import("@sinclair/typebox").TObject<{
+        path: import("@sinclair/typebox").TString;
+        method: import("@sinclair/typebox").TString;
+        schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+            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>;
+        }>>;
+    }>;
+    handler: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<KindRef<Invocable<Record<string, any>, any>>>>;
+    response: import("@sinclair/typebox").TArray<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>;
+    }>>;
+}>;
+type HttpApiRouteManifest = Static<typeof HttpApiRouteManifest>;
 declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
     routes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         request: import("@sinclair/typebox").TObject<{
@@ -13,23 +39,27 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
                 headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
             }>>;
         }>;
-        handler: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-        response: import("@sinclair/typebox").TObject<{
-            status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString]>;
-            statuses: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
-                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>>;
+        handler: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<KindRef<Invocable<Record<string, any>, any>>>>;
+        response: import("@sinclair/typebox").TArray<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>;
+        }>>;
     }>>;
 }>;
 type HttpApiManifest = Static<typeof HttpApiManifest>;
-export declare function register(ctx: ControllerContext): Promise<void>;
+export declare function register(_ctx: ControllerContext): Promise<void>;
+export type ResponseEntry = Static<(typeof HttpApiRouteManifest)["properties"]["response"]["items"]>;
+export declare function dispatchResponse(response: ResponseEntry[], result: unknown, requestContext: Record<string, unknown>, moduleContext: {
+    expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
+}, validateSchema: (value: unknown, schema: unknown) => void, reply: FastifyReply): Promise<void>;
 export declare class HttpServerApi implements ResourceInstance {
     private readonly ctx;
     readonly manifest: HttpApiManifest;

package/dist/http-api-controller.js

@@ -1,4 +1,6 @@
 import { Type } from "@sinclair/typebox";
+import { Ref } from "@telorun/sdk";
+import { pipeline } from "stream/promises";
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
         path: Type.String(),
@@ -10,24 +12,72 @@ const HttpApiRouteManifest = Type.Object({
             headers: Type.Optional(Type.Any()),
         })),
     }),
-    handler: Type.Optional(Type.Any()), // Any handler shape is allowed - will be processed in create()
-    response: Type.Object({
-        status: Type.Union([Type.Number({ minimum: 100, maximum: 599 }), Type.String()]),
-        statuses: Type.Record(Type.String(), Type.Object({
-            schema: Type.Optional(Type.Object({
-                query: Type.Optional(Type.Any()),
-                body: Type.Optional(Type.Any()),
-                headers: Type.Optional(Type.Any()),
-            })),
-            headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+    handler: Type.Optional(Type.Unsafe(Ref("kernel#Invocable"))),
+    response: Type.Array(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")])),
+        schema: Type.Optional(Type.Object({
+            query: Type.Optional(Type.Any()),
             body: Type.Optional(Type.Any()),
+            headers: Type.Optional(Type.Any()),
         })),
-    }),
+        headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+        body: Type.Optional(Type.Any()),
+    })),
 });
 const HttpApiManifest = Type.Object({
     routes: Type.Array(HttpApiRouteManifest),
 });
-export async function register(ctx) { }
+export async function register(_ctx) { }
+export async function dispatchResponse(response, result, requestContext, moduleContext, validateSchema, reply) {
+    let matched;
+    let fallback;
+    for (const entry of response) {
+        if (!entry.when) {
+            fallback ??= entry;
+            continue;
+        }
+        const condition = moduleContext.expandWith(entry.when, { result, ...requestContext });
+        if (condition === true) {
+            matched = entry;
+            break;
+        }
+    }
+    const statusEntry = matched ?? fallback;
+    if (!statusEntry) {
+        reply.code(500);
+        reply.send({
+            error: "InternalServerError",
+            message: "No matching response status entry",
+            status: 500,
+        });
+        return;
+    }
+    reply.code(statusEntry.status);
+    if (statusEntry.headers) {
+        const mappedHeaders = moduleContext.expandWith(statusEntry.headers, {
+            result,
+            ...requestContext,
+        });
+        Object.entries(mappedHeaders).forEach(([key, value]) => reply.header(key, value));
+    }
+    if (statusEntry.mode === "stream") {
+        reply.hijack();
+        reply.raw.writeHead(statusEntry.status, reply.getHeaders());
+        await pipeline(result, reply.raw);
+        return;
+    }
+    if (statusEntry.body !== undefined) {
+        const mappedBody = moduleContext.expandWith(statusEntry.body, { result, ...requestContext });
+        if (statusEntry.schema?.body) {
+            validateSchema(mappedBody, statusEntry.schema.body);
+        }
+        reply.send(mappedBody);
+        return;
+    }
+    reply.send(result);
+}
 export class HttpServerApi {
     ctx;
     manifest;
@@ -53,7 +103,8 @@ export class HttpServerApi {
         }
     }
     registerRoute(app, route) {
-        const handler = route.handler ? resolveHandlerName(route.handler) : null;
+        // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
+        const handler = route.handler;
         const translatedPath = translateOpenApiPath(route.request.path);
         const schema = {
             response: {},
@@ -70,15 +121,12 @@ export class HttpServerApi {
         if (route.request.schema?.headers) {
             schema.headers = route.request.schema?.headers;
         }
-        schema.response = Object.keys(route.response.statuses).reduce((acc, status) => {
-            const statusConfig = route.response.statuses[status];
-            if (statusConfig.schema) {
-                if (statusConfig.schema.body) {
-                    acc[status] = statusConfig.schema.body;
-                }
-                else {
-                    acc[status] = {};
-                }
+        schema.response = route.response.reduce((acc, entry) => {
+            if (entry.schema?.body) {
+                acc[entry.status] = entry.schema.body;
+            }
+            else if (entry.schema) {
+                acc[entry.status] = {};
             }
             return acc;
         }, {});
@@ -88,59 +136,18 @@ export class HttpServerApi {
             schema,
             handler: async (request, reply) => {
                 try {
-                    // Normalize headers to lowercase
-                    const normalizedHeaders = normalizeHeaders(request.headers);
-                    // Construct standardized Telo request object
-                    const requestPayload = {
-                        method: request.method,
-                        path: request.url,
-                        params: request.params || {},
-                        query: request.query || {},
-                        headers: normalizedHeaders,
-                        body: request.body,
+                    const requestContext = {
+                        request: {
+                            method: request.method,
+                            path: request.url,
+                            params: request.params || {},
+                            query: request.query || {},
+                            headers: normalizeHeaders(request.headers),
+                            body: request.body,
+                        },
                     };
-                    // Wrap in "request" object as per spec
-                    const teloRequestContext = { request: requestPayload };
-                    const result = handler
-                        ? await this.ctx.invoke(handler.kind, handler.name, resolveHandlerInputs(route.handler, teloRequestContext))
-                        : undefined;
-                    const response = route.response;
-                    // Determine final status code
-                    let statusCode = response.status;
-                    if (typeof statusCode === "string") {
-                        statusCode = this.ctx.expandValue(statusCode, { result });
-                    }
-                    // Convert status to string for lookup
-                    const statusKey = String(statusCode);
-                    const statusConfig = response.statuses[statusKey];
-                    if (!statusConfig) {
-                        reply.code(500);
-                        return reply.send({
-                            error: "InternalServerError",
-                            message: "Response status configuration not found",
-                            status: 500,
-                        });
-                    }
-                    // Set HTTP status code
-                    reply.code(statusCode);
-                    // Map and set response headers if specified
-                    if (statusConfig.headers) {
-                        const mappedHeaders = this.ctx.expandValue(statusConfig.headers, { result });
-                        Object.entries(mappedHeaders).forEach(([key, value]) => {
-                            reply.header(key, value);
-                        });
-                    }
-                    // Map and send response body if specified
-                    if (statusConfig.body !== undefined) {
-                        const mappedBody = this.ctx.expandValue(statusConfig.body, { result });
-                        // Validate response body if schema is specified
-                        if (statusConfig.schema && statusConfig.schema.body) {
-                            this.ctx.validateSchema(mappedBody, statusConfig.schema.body);
-                        }
-                        return reply.send(mappedBody);
-                    }
-                    // No body mapping, send result as-is
-                    return reply.send(result);
+                    const result = handler ? await handler.invoke(requestContext) : undefined;
+                    return dispatchResponse(route.response, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
                 }
                 catch (error) {
                     // Let the error handler deal with all errors
@@ -151,92 +158,8 @@ export class HttpServerApi {
     }
 }
 export async function create(resource, ctx) {
-    // First validate with a permissive schema (handler can be any shape)
     ctx.validateSchema(resource, HttpApiManifest);
-    // Process routes and register unnamed handlers as child resources
-    let handlerCounter = 0;
-    const processedRoutes = (resource.routes || []).map((route) => {
-        if (!route.handler) {
-            return route;
-        }
-        // Check if handler is unnamed (inline handler)
-        if (typeof route.handler === "object" && !route.handler.name) {
-            // Use resolveChildren to register the unnamed handler and get its normalized reference
-            const resolvedHandler = ctx.resolveChildren(route.handler, `__handler_${handlerCounter++}`);
-            // Return route with the resolved handler reference
-            return {
-                ...route,
-                handler: {
-                    kind: resolvedHandler.kind,
-                    name: resolvedHandler.name,
-                    inputs: route.handler.inputs,
-                },
-            };
-        }
-        return route;
-    });
-    // Create the API instance with processed routes
-    const processedResource = {
-        ...resource,
-        routes: processedRoutes,
-    };
-    return new HttpServerApi(ctx, processedResource);
-}
-function resolveHandlerName(handler) {
-    if (typeof handler === "string") {
-        const [kind, name] = handler.split("/");
-        return { kind, name };
-    }
-    if (handler && typeof handler === "object" && typeof handler.kind === "string") {
-        // name should always be present after create() processes the routes
-        // but fallback gracefully if it's not
-        const name = handler.name || `__unnamed_${Math.random().toString(36).slice(2, 9)}`;
-        return { name, kind: handler.kind };
-    }
-    throw new Error("Unable to resolve handler - handler must have a 'kind' property");
-}
-function resolveHandlerInputs(handler, requestContext) {
-    if (typeof handler === "string") {
-        return requestContext;
-    }
-    if (!handler || typeof handler !== "object") {
-        return requestContext;
-    }
-    if (!handler.inputs) {
-        return requestContext;
-    }
-    return resolveTemplateInputs(handler.inputs, requestContext);
-}
-function resolveTemplateInputs(value, context) {
-    if (typeof value === "string") {
-        const match = value.match(/^\s*\$\{\{\s*([^}]+)\s*\}\}\s*$/);
-        if (match) {
-            return resolveTemplatePath(match[1], context);
-        }
-        return value;
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => resolveTemplateInputs(item, context));
-    }
-    if (value && typeof value === "object") {
-        const resolved = {};
-        for (const [key, entry] of Object.entries(value)) {
-            resolved[key] = resolveTemplateInputs(entry, context);
-        }
-        return resolved;
-    }
-    return value;
-}
-function resolveTemplatePath(pathExpression, context) {
-    const parts = pathExpression.trim().split(".").filter(Boolean);
-    let current = context;
-    for (const part of parts) {
-        if (!current || (typeof current !== "object" && typeof current !== "function")) {
-            return undefined;
-        }
-        current = current[part];
-    }
-    return current;
+    return new HttpServerApi(ctx, resource);
 }
 /**
  * Translates OpenAPI path format {paramName} to Fastify format :paramName
@@ -255,53 +178,3 @@ function normalizeHeaders(headers) {
     }
     return normalized;
 }
-/**
- * Legacy function - kept for compatibility but not used
- * Converts framework-specific validation errors to standardized Telo format
- * Returns null if the error is not a validation error
- */
-function convertValidationError(error) {
-    // Check if this is a Fastify/AJV validation error
-    if (!error || typeof error !== "object") {
-        return null;
-    }
-    // Fastify validation errors have a statusCode of 400 and validation array
-    if (error.statusCode === 400 && Array.isArray(error.validation)) {
-        const details = error.validation.map((err) => {
-            const path = err.instancePath ? err.instancePath.replace(/^\//, "").replace(/\//g, ".") : "";
-            // Determine location from keyword/message context
-            let location = "body"; // default
-            if (err.keyword === "required" && err.params?.missingProperty) {
-                location = determinLocationFromContext(err);
-            }
-            else {
-                location = determinLocationFromContext(err);
-            }
-            return {
-                location,
-                path: path || err.params?.missingProperty || "",
-                message: err.message || "Validation failed",
-            };
-        });
-        return {
-            error: "ValidationError",
-            message: "Request validation failed",
-            status: 400,
-            details,
-        };
-    }
-    return null;
-}
-/**
- * Helper to determine the location (body, query, params, headers) from validation error context
- */
-function determinLocationFromContext(err) {
-    // AJV validation errors in Fastify include parent keyword context
-    if (err.parentSchema && err.instancePath) {
-        const path = err.instancePath;
-        // This is a simplified check; in practice, Fastify provides better context
-        // For now, default to "body" for general validation errors
-        return "body";
-    }
-    return "body";
-}

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

@@ -1,8 +1,14 @@
-import type { ResourceContext, ResourceInstance, RuntimeResource } from "@telorun/sdk";
+import type { Invocable, KindRef, ResourceContext, ResourceInstance, RuntimeResource } from "@telorun/sdk";
+import { ResponseEntry } from "./http-api-controller.js";
 type HttpServerResource = RuntimeResource & {
     host?: string;
     port?: number;
     baseUrl?: string;
+    logger?: boolean;
+    contentTypeParsers?: Array<{
+        contentType: string;
+        parser?: Invocable;
+    }>;
     openapi?: {
         info: {
             title: string;
@@ -13,6 +19,10 @@ type HttpServerResource = RuntimeResource & {
         path?: string;
         type?: string;
     }>;
+    notFoundHandler?: {
+        invoke: KindRef<Invocable>;
+        response?: ResponseEntry[];
+    };
 };
-export declare function create(resource: HttpServerResource, ctx: ResourceContext): ResourceInstance | null;
+export declare function create(resource: HttpServerResource, ctx: ResourceContext): Promise<ResourceInstance | null>;
 export {};

package/dist/http-server-controller.js

@@ -2,30 +2,54 @@ import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
 import addFormats from "ajv-formats";
 import Fastify from "fastify";
+import { dispatchResponse } from "./http-api-controller.js";
 class HttpServer {
     releaseHold = null;
+    pluginsInitialized = false;
     app;
     host;
     port;
     baseUrl;
     resource;
     ctx;
-    constructor(resource, ctx) {
+    resolvedNotFoundHandler;
+    constructor(resource, ctx, resolvedNotFoundHandler = null) {
         this.resource = resource;
         this.ctx = ctx;
         this.host = resource.host || "0.0.0.0";
         this.port = Number(resource.port || 0);
         this.baseUrl = resource.baseUrl ?? `http://${this.host}:${this.port}`;
+        this.resolvedNotFoundHandler = resolvedNotFoundHandler;
         if (!this.port) {
             throw new Error("Http.Server port is required");
         }
-        this.app = Fastify({ logger: true, ajv: { plugins: [addFormats.default] } });
+        this.app = Fastify({ logger: resource.logger, ajv: { plugins: [addFormats.default] } });
     }
     async init() {
-        await this.setupPlugins();
+        if (!this.pluginsInitialized) {
+            await this.setupPlugins();
+            this.pluginsInitialized = true;
+        }
         this.setupRoutes();
     }
     async setupPlugins() {
+        for (const { contentType, parser } of this.resource.contentTypeParsers ?? []) {
+            if (parser) {
+                this.app.addContentTypeParser(contentType, { parseAs: "string" }, async (_req, body, done) => {
+                    try {
+                        done(null, await parser.invoke({ body }));
+                    }
+                    catch (err) {
+                        done(err, undefined);
+                    }
+                });
+            }
+            else {
+                this.app.addContentTypeParser(contentType, { parseAs: "string" }, (_req, body, done) => {
+                    done(null, body);
+                });
+            }
+        }
         // Register custom error handler for validation errors
         this.app.setErrorHandler((error, request, reply) => {
             const mappedError = convertFastifyValidationError(error);
@@ -67,12 +91,41 @@ class HttpServer {
             const type = mount.type || "";
             const { kind, name } = parseType(type);
             const prefix = mount.path || "";
-            const api = this.ctx.moduleContext.getInvokable(name);
+            const api = this.ctx.moduleContext.getInvocable(name);
             if (!api) {
                 throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
             }
             api.register(this.app, prefix);
         }
+        if (this.resolvedNotFoundHandler) {
+            const handler = this.resolvedNotFoundHandler;
+            this.app.setNotFoundHandler(async (request, reply) => {
+                const normalizedHeaders = {};
+                for (const [key, value] of Object.entries(request.headers)) {
+                    normalizedHeaders[key.toLowerCase()] = value;
+                }
+                const requestContext = {
+                    request: {
+                        method: request.method,
+                        path: request.url,
+                        params: request.params || {},
+                        query: request.query || {},
+                        headers: normalizedHeaders,
+                        body: request.body,
+                    },
+                };
+                const result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
+                if (handler.response) {
+                    return dispatchResponse(handler.response, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                }
+                const status = result?.status ?? 200;
+                reply.code(status);
+                if (result?.headers) {
+                    Object.entries(result.headers).forEach(([key, value]) => reply.header(key, value));
+                }
+                return reply.send(result?.body ?? result);
+            });
+        }
     }
     async run() {
         this.releaseHold = this.ctx.acquireHold();
@@ -103,8 +156,18 @@ class HttpServer {
         await this.app.close();
     }
 }
-export function create(resource, ctx) {
-    return new HttpServer(resource, ctx);
+export async function create(resource, ctx) {
+    let resolvedNotFoundHandler = null;
+    if (resource.notFoundHandler) {
+        const resolved = ctx.resolveChildren(resource.notFoundHandler.invoke);
+        resolvedNotFoundHandler = {
+            kind: resolved.kind,
+            name: resolved.name,
+            inputs: resource.notFoundHandler.invoke.inputs ?? {},
+            response: resource.notFoundHandler.response,
+        };
+    }
+    return new HttpServer(resource, ctx, resolvedNotFoundHandler);
 }
 function parseType(type) {
     const separator = type.lastIndexOf(".");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,7 +23,7 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@telorun/sdk": "0.2.5"
+    "@telorun/sdk": "0.2.6"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/http-api-controller.ts

@@ -1,6 +1,8 @@
 import { Static, Type } from "@sinclair/typebox";
-import { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { ControllerContext, Invocable, KindRef, Ref, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { type Readable } from "stream";
+import { pipeline } from "stream/promises";
 
 const HttpApiRouteManifest = Type.Object({
   request: Type.Object({
@@ -15,24 +17,23 @@ const HttpApiRouteManifest = Type.Object({
       }),
     ),
   }),
-  handler: Type.Optional(Type.Any()), // Any handler shape is allowed - will be processed in create()
-  response: Type.Object({
-    status: Type.Union([Type.Number({ minimum: 100, maximum: 599 }), Type.String()]),
-    statuses: Type.Record(
-      Type.String(),
-      Type.Object({
-        schema: Type.Optional(
-          Type.Object({
-            query: Type.Optional(Type.Any()),
-            body: Type.Optional(Type.Any()),
-            headers: Type.Optional(Type.Any()),
-          }),
-        ),
-        headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-        body: Type.Optional(Type.Any()),
-      }),
-    ),
-  }),
+  handler: Type.Optional(Type.Unsafe<KindRef<Invocable>>(Ref("kernel#Invocable"))),
+  response: Type.Array(
+    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")])),
+      schema: Type.Optional(
+        Type.Object({
+          query: Type.Optional(Type.Any()),
+          body: Type.Optional(Type.Any()),
+          headers: Type.Optional(Type.Any()),
+        }),
+      ),
+      headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+      body: Type.Optional(Type.Any()),
+    }),
+  ),
 });
 type HttpApiRouteManifest = Static<typeof HttpApiRouteManifest>;
 
@@ -41,7 +42,74 @@ const HttpApiManifest = Type.Object({
 });
 type HttpApiManifest = Static<typeof HttpApiManifest>;
 
-export async function register(ctx: ControllerContext): Promise<void> {}
+export async function register(_ctx: ControllerContext): Promise<void> {}
+
+export type ResponseEntry = Static<
+  (typeof HttpApiRouteManifest)["properties"]["response"]["items"]
+>;
+
+export async function dispatchResponse(
+  response: ResponseEntry[],
+  result: unknown,
+  requestContext: Record<string, unknown>,
+  moduleContext: { expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown },
+  validateSchema: (value: unknown, schema: unknown) => void,
+  reply: FastifyReply,
+): Promise<void> {
+  let matched: ResponseEntry | undefined;
+  let fallback: ResponseEntry | undefined;
+
+  for (const entry of response) {
+    if (!entry.when) {
+      fallback ??= entry;
+      continue;
+    }
+    const condition = moduleContext.expandWith(entry.when, { result, ...requestContext });
+    if (condition === true) {
+      matched = entry;
+      break;
+    }
+  }
+
+  const statusEntry = matched ?? fallback;
+  if (!statusEntry) {
+    reply.code(500);
+    reply.send({
+      error: "InternalServerError",
+      message: "No matching response status entry",
+      status: 500,
+    });
+    return;
+  }
+
+  reply.code(statusEntry.status);
+
+  if (statusEntry.headers) {
+    const mappedHeaders = moduleContext.expandWith(statusEntry.headers, {
+      result,
+      ...requestContext,
+    }) as Record<string, unknown>;
+    Object.entries(mappedHeaders).forEach(([key, value]) => reply.header(key, value as string));
+  }
+
+  if (statusEntry.mode === "stream") {
+    reply.hijack();
+    reply.raw.writeHead(statusEntry.status, reply.getHeaders() as Record<string, string>);
+    await pipeline(result as Readable, reply.raw);
+    return;
+  }
+
+  if (statusEntry.body !== undefined) {
+    const mappedBody = moduleContext.expandWith(statusEntry.body, { result, ...requestContext });
+    if (statusEntry.schema?.body) {
+      validateSchema(mappedBody, statusEntry.schema.body);
+    }
+    reply.send(mappedBody);
+    return;
+  }
+
+  reply.send(result);
+}
 
 export class HttpServerApi implements ResourceInstance {
   constructor(
@@ -72,7 +140,8 @@ export class HttpServerApi implements ResourceInstance {
   }
 
   private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest) {
-    const handler = route.handler ? resolveHandlerName(route.handler) : null;
+    // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
+    const handler = route.handler as unknown as Invocable | undefined;
     const translatedPath = translateOpenApiPath(route.request.path);
 
     const schema: any = {
@@ -92,19 +161,16 @@ export class HttpServerApi implements ResourceInstance {
       schema.headers = route.request.schema?.headers;
     }
 
-    schema.response = Object.keys(route.response.statuses).reduce(
-      (acc, status) => {
-        const statusConfig = route.response.statuses[status];
-        if (statusConfig.schema) {
-          if (statusConfig.schema.body) {
-            acc[status] = statusConfig.schema.body;
-          } else {
-            acc[status] = {};
-          }
+    schema.response = route.response.reduce(
+      (acc, entry) => {
+        if (entry.schema?.body) {
+          acc[entry.status] = entry.schema.body;
+        } else if (entry.schema) {
+          acc[entry.status] = {};
         }
         return acc;
       },
-      {} as Record<string, any>,
+      {} as Record<number, any>,
     );
 
     app.route({
@@ -113,76 +179,26 @@ export class HttpServerApi implements ResourceInstance {
       schema,
       handler: async (request: FastifyRequest, reply: FastifyReply) => {
         try {
-          // Normalize headers to lowercase
-          const normalizedHeaders = normalizeHeaders(request.headers);
-
-          // Construct standardized Telo request object
-          const requestPayload = {
-            method: request.method,
-            path: request.url,
-            params: request.params || {},
-            query: request.query || {},
-            headers: normalizedHeaders,
-            body: request.body,
+          const requestContext = {
+            request: {
+              method: request.method,
+              path: request.url,
+              params: request.params || {},
+              query: request.query || {},
+              headers: normalizeHeaders(request.headers),
+              body: request.body,
+            },
           };
-
-          // Wrap in "request" object as per spec
-          const teloRequestContext = { request: requestPayload };
-
-          const result = handler
-            ? await this.ctx.invoke(
-                handler.kind,
-                handler.name,
-                resolveHandlerInputs(route.handler, teloRequestContext),
-              )
-            : undefined;
-
-          const response = route.response;
-
-          // Determine final status code
-          let statusCode = response.status;
-          if (typeof statusCode === "string") {
-            statusCode = this.ctx.expandValue(statusCode, { result }) as number;
-          }
-
-          // Convert status to string for lookup
-          const statusKey = String(statusCode);
-          const statusConfig = response.statuses[statusKey];
-
-          if (!statusConfig) {
-            reply.code(500);
-            return reply.send({
-              error: "InternalServerError",
-              message: "Response status configuration not found",
-              status: 500,
-            });
-          }
-
-          // Set HTTP status code
-          reply.code(statusCode as number);
-
-          // Map and set response headers if specified
-          if (statusConfig.headers) {
-            const mappedHeaders = this.ctx.expandValue(statusConfig.headers, { result });
-            Object.entries(mappedHeaders).forEach(([key, value]) => {
-              reply.header(key, value as string);
-            });
-          }
-
-          // Map and send response body if specified
-          if (statusConfig.body !== undefined) {
-            const mappedBody = this.ctx.expandValue(statusConfig.body, { result });
-
-            // Validate response body if schema is specified
-            if (statusConfig.schema && statusConfig.schema.body) {
-              this.ctx.validateSchema(mappedBody, statusConfig.schema.body);
-            }
-
-            return reply.send(mappedBody);
-          }
-
-          // No body mapping, send result as-is
-          return reply.send(result);
+          const result = handler ? await handler.invoke(requestContext) : undefined;
+
+          return dispatchResponse(
+            route.response,
+            result,
+            requestContext,
+            this.ctx.moduleContext,
+            this.ctx.validateSchema.bind(this.ctx),
+            reply,
+          );
         } catch (error) {
           // Let the error handler deal with all errors
           throw error;
@@ -193,101 +209,8 @@ export class HttpServerApi implements ResourceInstance {
 }
 
 export async function create(resource: any, ctx: ResourceContext): Promise<HttpServerApi> {
-  // First validate with a permissive schema (handler can be any shape)
   ctx.validateSchema(resource, HttpApiManifest);
-  // Process routes and register unnamed handlers as child resources
-  let handlerCounter = 0;
-  const processedRoutes = (resource.routes || []).map((route: any) => {
-    if (!route.handler) {
-      return route;
-    }
-
-    // Check if handler is unnamed (inline handler)
-    if (typeof route.handler === "object" && !route.handler.name) {
-      // Use resolveChildren to register the unnamed handler and get its normalized reference
-      const resolvedHandler = ctx.resolveChildren(route.handler, `__handler_${handlerCounter++}`);
-
-      // Return route with the resolved handler reference
-      return {
-        ...route,
-        handler: {
-          kind: resolvedHandler.kind,
-          name: resolvedHandler.name,
-          inputs: route.handler.inputs,
-        },
-      };
-    }
-
-    return route;
-  });
-
-  // Create the API instance with processed routes
-  const processedResource: HttpApiManifest = {
-    ...resource,
-    routes: processedRoutes,
-  };
-
-  return new HttpServerApi(ctx, processedResource);
-}
-
-function resolveHandlerName(handler: any): { kind: string; name: string } {
-  if (typeof handler === "string") {
-    const [kind, name] = handler.split("/");
-    return { kind, name };
-  }
-  if (handler && typeof handler === "object" && typeof handler.kind === "string") {
-    // name should always be present after create() processes the routes
-    // but fallback gracefully if it's not
-    const name = handler.name || `__unnamed_${Math.random().toString(36).slice(2, 9)}`;
-    return { name, kind: handler.kind };
-  }
-  throw new Error("Unable to resolve handler - handler must have a 'kind' property");
-}
-
-function resolveHandlerInputs(handler: any, requestContext: Record<string, any>): any {
-  if (typeof handler === "string") {
-    return requestContext;
-  }
-  if (!handler || typeof handler !== "object") {
-    return requestContext;
-  }
-  if (!handler.inputs) {
-    return requestContext;
-  }
-  return resolveTemplateInputs(handler.inputs, requestContext);
-}
-
-function resolveTemplateInputs(value: any, context: Record<string, any>): any {
-  if (typeof value === "string") {
-    const match = value.match(/^\s*\$\{\{\s*([^}]+)\s*\}\}\s*$/);
-    if (match) {
-      return resolveTemplatePath(match[1], context);
-    }
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => resolveTemplateInputs(item, context));
-  }
-  if (value && typeof value === "object") {
-    const resolved: Record<string, any> = {};
-    for (const [key, entry] of Object.entries(value)) {
-      resolved[key] = resolveTemplateInputs(entry, context);
-    }
-    return resolved;
-  }
-  return value;
-}
-
-function resolveTemplatePath(pathExpression: string, context: Record<string, any>): any {
-  const parts = pathExpression.trim().split(".").filter(Boolean);
-  let current: any = context;
-  for (const part of parts) {
-    if (!current || (typeof current !== "object" && typeof current !== "function")) {
-      return undefined;
-    }
-    current = current[part];
-  }
-  return current;
+  return new HttpServerApi(ctx, resource);
 }
 
 /**
@@ -308,59 +231,3 @@ function normalizeHeaders(headers: Record<string, any>): Record<string, any> {
   }
   return normalized;
 }
-
-/**
- * Legacy function - kept for compatibility but not used
- * Converts framework-specific validation errors to standardized Telo format
- * Returns null if the error is not a validation error
- */
-function convertValidationError(error: any): Record<string, any> | null {
-  // Check if this is a Fastify/AJV validation error
-  if (!error || typeof error !== "object") {
-    return null;
-  }
-
-  // Fastify validation errors have a statusCode of 400 and validation array
-  if (error.statusCode === 400 && Array.isArray(error.validation)) {
-    const details = error.validation.map((err: any) => {
-      const path = err.instancePath ? err.instancePath.replace(/^\//, "").replace(/\//g, ".") : "";
-
-      // Determine location from keyword/message context
-      let location = "body"; // default
-      if (err.keyword === "required" && err.params?.missingProperty) {
-        location = determinLocationFromContext(err);
-      } else {
-        location = determinLocationFromContext(err);
-      }
-
-      return {
-        location,
-        path: path || err.params?.missingProperty || "",
-        message: err.message || "Validation failed",
-      };
-    });
-
-    return {
-      error: "ValidationError",
-      message: "Request validation failed",
-      status: 400,
-      details,
-    };
-  }
-
-  return null;
-}
-
-/**
- * Helper to determine the location (body, query, params, headers) from validation error context
- */
-function determinLocationFromContext(err: any): string {
-  // AJV validation errors in Fastify include parent keyword context
-  if (err.parentSchema && err.instancePath) {
-    const path = err.instancePath;
-    // This is a simplified check; in practice, Fastify provides better context
-    // For now, default to "body" for general validation errors
-    return "body";
-  }
-  return "body";
-}

package/src/http-server-controller.ts

@@ -1,27 +1,22 @@
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
-import type { ResourceContext, ResourceInstance, RuntimeResource } from "@telorun/sdk";
+import type {
+  Invocable,
+  KindRef,
+  ResourceContext,
+  ResourceInstance,
+  RuntimeResource,
+} from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify, { FastifyInstance } from "fastify";
-import { HttpServerApi } from "./http-api-controller.js";
-
-type HttpRouteResource = RuntimeResource & {
-  metadata?: { path?: string; method?: string };
-  path?: string;
-  method?: string;
-  handler?: HttpHandlerSpec;
-  request?: HttpRequestSchema;
-  response?: {
-    status?: number;
-    headers?: Record<string, string>;
-    body?: any;
-  };
-};
+import { dispatchResponse, HttpServerApi, ResponseEntry } from "./http-api-controller.js";
 
 type HttpServerResource = RuntimeResource & {
   host?: string;
   port?: number;
   baseUrl?: string;
+  logger?: boolean;
+  contentTypeParsers?: Array<{ contentType: string; parser?: Invocable }>;
   openapi?: {
     info: {
       title: string;
@@ -32,70 +27,73 @@ type HttpServerResource = RuntimeResource & {
     path?: string;
     type?: string;
   }>;
+  notFoundHandler?: {
+    invoke: KindRef<Invocable>;
+    response?: ResponseEntry[];
+  };
 };
 
-type HttpApiResource = RuntimeResource & {
-  routes?: Array<
-    | string
-    | {
-        request?: {
-          path?: string;
-          method?: string;
-          query?: Record<string, any>;
-          body?: Record<string, any>;
-          headers?: Record<string, any>;
-        };
-        handler?: HttpHandlerSpec;
-        response?: {
-          status?: number;
-          headers?: Record<string, string>;
-          body?: any;
-        };
-      }
-  >;
-};
-
-type HttpHandlerSpec =
-  | string
-  | {
-      name?: string;
-      inputs?: Record<string, any>;
-    };
-
-type HttpRequestSchema = {
-  query?: Record<string, any>;
-  body?: Record<string, any>;
-  headers?: Record<string, any>;
+type ResolvedHandler = {
+  kind: string;
+  name: string;
+  inputs: Record<string, any>;
+  response?: ResponseEntry[];
 };
 
 class HttpServer implements ResourceInstance {
   private releaseHold: (() => void) | null = null;
+  private pluginsInitialized = false;
   private readonly app: FastifyInstance;
   private readonly host: string;
   private readonly port: number;
   private readonly baseUrl: string;
   private readonly resource: HttpServerResource;
   private readonly ctx: ResourceContext;
+  private readonly resolvedNotFoundHandler: ResolvedHandler | null;
 
-  constructor(resource: HttpServerResource, ctx: ResourceContext) {
+  constructor(
+    resource: HttpServerResource,
+    ctx: ResourceContext,
+    resolvedNotFoundHandler: ResolvedHandler | null = null,
+  ) {
     this.resource = resource;
     this.ctx = ctx;
     this.host = resource.host || "0.0.0.0";
     this.port = Number(resource.port || 0);
     this.baseUrl = resource.baseUrl ?? `http://${this.host}:${this.port}`;
+    this.resolvedNotFoundHandler = resolvedNotFoundHandler;
 
     if (!this.port) {
       throw new Error("Http.Server port is required");
     }
-    this.app = Fastify({ logger: true, ajv: { plugins: [addFormats.default as any] } });
+    this.app = Fastify({ logger: resource.logger, ajv: { plugins: [addFormats.default as any] } });
   }
 
   async init() {
-    await this.setupPlugins();
+    if (!this.pluginsInitialized) {
+      await this.setupPlugins();
+      this.pluginsInitialized = true;
+    }
     this.setupRoutes();
   }
 
   private async setupPlugins() {
+    for (const { contentType, parser } of this.resource.contentTypeParsers ?? []) {
+      if (parser) {
+        this.app.addContentTypeParser(contentType, { parseAs: "string" }, async (_req, body, done) => {
+          try {
+            done(null, await parser.invoke({ body }));
+          } catch (err) {
+            done(err as Error, undefined);
+          }
+        });
+      } else {
+        this.app.addContentTypeParser(contentType, { parseAs: "string" }, (_req, body, done) => {
+          done(null, body);
+        });
+      }
+    }
+
     // Register custom error handler for validation errors
     this.app.setErrorHandler((error, request, reply) => {
       const mappedError = convertFastifyValidationError(error);
@@ -139,13 +137,52 @@ class HttpServer implements ResourceInstance {
       const { kind, name } = parseType(type);
       const prefix = mount.path || "";
 
-      const api = this.ctx.moduleContext.getInvokable(name) as unknown as HttpServerApi;
+      const api = this.ctx.moduleContext.getInvocable(name) as unknown as HttpServerApi;
 
       if (!api) {
         throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
       }
       api.register(this.app, prefix);
     }
+
+    if (this.resolvedNotFoundHandler) {
+      const handler = this.resolvedNotFoundHandler;
+      this.app.setNotFoundHandler(async (request, reply) => {
+        const normalizedHeaders: Record<string, any> = {};
+        for (const [key, value] of Object.entries(request.headers)) {
+          normalizedHeaders[key.toLowerCase()] = value;
+        }
+        const requestContext = {
+          request: {
+            method: request.method,
+            path: request.url,
+            params: request.params || {},
+            query: request.query || {},
+            headers: normalizedHeaders,
+            body: request.body,
+          },
+        };
+        const result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
+        if (handler.response) {
+          return dispatchResponse(
+            handler.response,
+            result,
+            requestContext,
+            this.ctx.moduleContext,
+            this.ctx.validateSchema.bind(this.ctx),
+            reply,
+          );
+        }
+        const status = result?.status ?? 200;
+        reply.code(status);
+        if (result?.headers) {
+          Object.entries(result.headers).forEach(([key, value]) =>
+            reply.header(key, value as string),
+          );
+        }
+        return reply.send(result?.body ?? result);
+      });
+    }
   }
 
   async run(): Promise<void> {
@@ -178,11 +215,21 @@ class HttpServer implements ResourceInstance {
   }
 }
 
-export function create(
+export async function create(
   resource: HttpServerResource,
   ctx: ResourceContext,
-): ResourceInstance | null {
-  return new HttpServer(resource, ctx);
+): Promise<ResourceInstance | null> {
+  let resolvedNotFoundHandler: ResolvedHandler | null = null;
+  if (resource.notFoundHandler) {
+    const resolved = ctx.resolveChildren(resource.notFoundHandler.invoke);
+    resolvedNotFoundHandler = {
+      kind: resolved.kind,
+      name: resolved.name,
+      inputs: (resource.notFoundHandler.invoke as any).inputs ?? {},
+      response: resource.notFoundHandler.response,
+    };
+  }
+  return new HttpServer(resource, ctx, resolvedNotFoundHandler);
 }
 
 function parseType(type: string): { kind: string; name: string } {