@telorun/http-server 0.1.4 → 0.1.6

package/src/http-api-controller.ts

@@ -1,6 +1,15 @@
 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 +24,24 @@ 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"))),
+  inputs: Type.Optional(Type.Record(Type.String(), Type.Any())),
+  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 +50,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 +148,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 +169,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 +187,33 @@ 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 resolvedInputs: Record<string, any> = route.inputs
+            ? ((this.ctx.moduleContext.expandWith(route.inputs, requestContext) as any) ?? {})
+            : requestContext;
+          const invokeInput: Record<string, any> = {
+            ...resolvedInputs,
+            inputs: resolvedInputs,
+          };
+          const result = handler ? await handler.invoke(invokeInput) : 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 +224,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 +246,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,39 @@
+import cors from "@fastify/cors";
 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";
+import { dispatchResponse, HttpServerApi, ResponseEntry } 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;
-  };
+type CorsOptions = {
+  origin?: string | boolean | string[];
+  methods?: string | string[];
+  allowedHeaders?: string | string[];
+  exposedHeaders?: string | string[];
+  credentials?: boolean;
+  maxAge?: number;
+  cacheControl?: number | string;
+  preflightContinue?: boolean;
+  optionsSuccessStatus?: number;
+  preflight?: boolean;
+  strictPreflight?: boolean;
+  hideOptionsRoute?: boolean;
 };
 
 type HttpServerResource = RuntimeResource & {
   host?: string;
   port?: number;
   baseUrl?: string;
+  logger?: boolean;
+  cors?: CorsOptions;
+  contentTypeParsers?: Array<{ contentType: string; parser?: Invocable }>;
   openapi?: {
     info: {
       title: string;
@@ -32,70 +44,97 @@ 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: { customOptions: { useDefaults: true }, 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);
+        });
+      }
+    }
+
+    if (this.resource.cors) {
+      await this.app.register(cors, {
+        origin: this.resource.cors.origin,
+        methods: this.resource.cors.methods,
+        allowedHeaders: this.resource.cors.allowedHeaders,
+        exposedHeaders: this.resource.cors.exposedHeaders,
+        credentials: this.resource.cors.credentials,
+        maxAge: this.resource.cors.maxAge,
+        cacheControl: this.resource.cors.cacheControl,
+        preflightContinue: this.resource.cors.preflightContinue,
+        optionsSuccessStatus: this.resource.cors.optionsSuccessStatus,
+        preflight: this.resource.cors.preflight,
+        strictPreflight: this.resource.cors.strictPreflight,
+        hideOptionsRoute: this.resource.cors.hideOptionsRoute,
+      });
+    }
+
     // Register custom error handler for validation errors
     this.app.setErrorHandler((error, request, reply) => {
       const mappedError = convertFastifyValidationError(error);
@@ -139,13 +178,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 +256,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 } {