@telorun/http-server 0.1.3 → 0.1.5

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(
@@ -52,17 +120,6 @@ export class HttpServerApi implements ResourceInstance {
   async init() {}
 
   register(app: FastifyInstance, prefix = "") {
-    // Register custom error handler for validation errors
-    app.setErrorHandler((error, request, reply) => {
-      const mappedError = convertFastifyValidationError(error);
-      if (mappedError) {
-        reply.code(400);
-        return reply.send(mappedError);
-      }
-      // Let Fastify handle other errors normally
-      throw error;
-    });
-
     if (prefix) {
       app.register(
         async (scoped) => {
@@ -83,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 = {
@@ -103,24 +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) {
-          acc[status] = {};
-          if (statusConfig.schema.query) {
-            acc[status].querystring = statusConfig.schema.query;
-          }
-          if (statusConfig.schema.body) {
-            acc[status].body = statusConfig.schema.body;
-          }
-          if (statusConfig.schema.headers) {
-            acc[status].headers = statusConfig.schema.headers;
-          }
+    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({
@@ -129,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;
@@ -209,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);
 }
 
 /**
@@ -324,125 +231,3 @@ function normalizeHeaders(headers: Record<string, any>): Record<string, any> {
   }
   return normalized;
 }
-
-/**
- * Converts Fastify validation errors to standardized Telo format
- * Returns null if the error is not a validation error
- */
-function convertFastifyValidationError(error: any): Record<string, any> | null {
-  // Check if this is a Fastify validation error
-  if (!error || typeof error !== "object" || error.code !== "FST_ERR_VALIDATION") {
-    return null;
-  }
-
-  const message = error.message || "";
-  const details = [];
-
-  // Parse Fastify validation error message to extract location and field
-  // Format examples:
-  // "querystring must have required property 'name'"
-  // "body must be object"
-  // "params.userId must be string"
-
-  let location = "body"; // default
-  let fieldPath = "";
-  let validationMessage = "Validation failed";
-
-  // Try to extract location from message
-  if (message.includes("querystring")) {
-    location = "query";
-  } else if (message.includes("params")) {
-    location = "params";
-  } else if (message.includes("headers")) {
-    location = "headers";
-  } else if (message.includes("body")) {
-    location = "body";
-  }
-
-  // Extract field name from "must have required property 'fieldName'" pattern
-  const requiredMatch = message.match(/must have required property '([^']+)'/);
-  if (requiredMatch) {
-    fieldPath = requiredMatch[1];
-    validationMessage = `is a required property`;
-  } else {
-    // Extract field from "fieldName must be" pattern
-    const fieldMatch = message.match(/^(?:querystring|body|params|headers)\.?(\w+)\s/);
-    if (fieldMatch) {
-      fieldPath = fieldMatch[1];
-    }
-    validationMessage = message
-      .replace(/^(?:querystring|body|params|headers)\.?\w*\s/, "")
-      .replace(" must ", " ");
-  }
-
-  if (fieldPath || message) {
-    details.push({
-      location,
-      path: fieldPath,
-      message: validationMessage,
-    });
-  }
-
-  return {
-    error: "ValidationError",
-    message: "Request validation failed",
-    status: 400,
-    details,
-  };
-}
-
-/**
- * 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";
-}