@telorun/http-server 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @telorun/http-server
 
+## 0.1.4
+
+### Patch Changes
+
+- Automated release.
+- Updated dependencies
+  - @telorun/sdk@0.2.5
+
+## 0.1.3
+
+### Patch Changes
+
+- Automated release.
+- Updated dependencies
+  - @telorun/sdk@0.2.4
+
 ## 0.1.2
 
 ### Patch Changes

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

@@ -1,5 +1,5 @@
-import { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { Static } from "@sinclair/typebox";
+import { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { FastifyInstance } from "fastify";
 declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
     routes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
@@ -13,11 +13,7 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
                 headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
             }>>;
         }>;
-        handler: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            kind: import("@sinclair/typebox").TString;
-            name: import("@sinclair/typebox").TString;
-            inputs: 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<{
@@ -43,5 +39,5 @@ export declare class HttpServerApi implements ResourceInstance {
     private registerRoutes;
     private registerRoute;
 }
-export declare function create(resource: HttpApiManifest, ctx: ResourceContext): Promise<HttpServerApi>;
+export declare function create(resource: any, ctx: ResourceContext): Promise<HttpServerApi>;
 export {};

package/dist/http-api-controller.js

@@ -10,11 +10,7 @@ const HttpApiRouteManifest = Type.Object({
             headers: Type.Optional(Type.Any()),
         })),
     }),
-    handler: Type.Optional(Type.Object({
-        kind: Type.String(),
-        name: Type.String(),
-        inputs: 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({
@@ -58,7 +54,10 @@ export class HttpServerApi {
     }
     registerRoute(app, route) {
         const handler = route.handler ? resolveHandlerName(route.handler) : null;
-        const schema = {};
+        const translatedPath = translateOpenApiPath(route.request.path);
+        const schema = {
+            response: {},
+        };
         if (route.request.schema?.query) {
             schema.querystring = route.request.schema?.query;
         }
@@ -74,99 +73,139 @@ export class HttpServerApi {
         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;
+                    acc[status] = statusConfig.schema.body;
                 }
-                if (statusConfig.schema.headers) {
-                    acc[status].headers = statusConfig.schema.headers;
+                else {
+                    acc[status] = {};
                 }
             }
             return acc;
         }, {});
         app.route({
             method: route.request.method,
-            url: route.request.path,
+            url: translatedPath,
             schema,
             handler: async (request, reply) => {
-                // const resolveSchema = createSchemaResolver(ctx);
-                const requestPayload = {
-                    params: request.params,
-                    query: request.query,
-                    body: request.body,
-                    headers: request.headers,
-                    method: request.method,
-                    url: request.url,
-                };
-                // validateRequestSchemas(route.request, requestPayload, resolveSchema);
-                const result = handler
-                    ? await this.ctx.invoke(handler.kind, handler.name, resolveHandlerInputs(route.handler, requestPayload))
-                    : undefined;
-                // Handle response with body/headers mapping
-                const response = route.response;
-                // Set status
-                const status = typeof response.status === "string"
-                    ? this.ctx.expandValue(response.status, { result })
-                    : response.status;
-                if (response.status) {
-                    reply.code(status);
-                }
-                const statusConfig = response.statuses[response.status];
-                if (!statusConfig) {
-                    return reply.code(500).send({ error: "Invalid response status configuration" });
-                }
-                // Map headers if specified
-                if (statusConfig.headers) {
-                    reply.headers(this.ctx.expandValue(statusConfig.headers, { result }));
-                }
-                // Map body if specified
-                if (statusConfig.body !== undefined) {
-                    const mappedBody = this.ctx.expandValue(statusConfig.body, {
-                        result,
-                    });
-                    if (statusConfig.schema && statusConfig.schema.body) {
-                        this.ctx.validateSchema(mappedBody, statusConfig.schema.body);
+                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,
+                    };
+                    // 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);
+                        });
                     }
-                    return reply.send(mappedBody);
+                    // 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);
+                }
+                catch (error) {
+                    // Let the error handler deal with all errors
+                    throw error;
                 }
-                // No body mapping, send result as-is
-                return reply.send(result);
             },
         });
     }
 }
 export async function create(resource, ctx) {
+    // First validate with a permissive schema (handler can be any shape)
     ctx.validateSchema(resource, HttpApiManifest);
-    return new HttpServerApi(ctx, resource);
+    // 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.name === "string" &&
-        typeof handler.kind === "string") {
-        return { name: handler.name, kind: handler.kind };
+    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");
+    throw new Error("Unable to resolve handler - handler must have a 'kind' property");
 }
-function resolveHandlerInputs(handler, requestPayload) {
+function resolveHandlerInputs(handler, requestContext) {
     if (typeof handler === "string") {
-        return requestPayload;
+        return requestContext;
     }
     if (!handler || typeof handler !== "object") {
-        return requestPayload;
+        return requestContext;
     }
     if (!handler.inputs) {
-        return requestPayload;
+        return requestContext;
     }
-    const context = { request: requestPayload, ...requestPayload };
-    return resolveTemplateInputs(handler.inputs, context);
+    return resolveTemplateInputs(handler.inputs, requestContext);
 }
 function resolveTemplateInputs(value, context) {
     if (typeof value === "string") {
@@ -199,3 +238,70 @@ function resolveTemplatePath(pathExpression, context) {
     }
     return current;
 }
+/**
+ * Translates OpenAPI path format {paramName} to Fastify format :paramName
+ * Example: /api/v1/users/{userId} -> /api/v1/users/:userId
+ */
+function translateOpenApiPath(openApiPath) {
+    return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
+}
+/**
+ * Normalizes all header keys to lowercase as per Telo spec
+ */
+function normalizeHeaders(headers) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalized[key.toLowerCase()] = value;
+    }
+    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.js

@@ -1,5 +1,6 @@
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
+import addFormats from "ajv-formats";
 import Fastify from "fastify";
 class HttpServer {
     releaseHold = null;
@@ -18,13 +19,23 @@ class HttpServer {
         if (!this.port) {
             throw new Error("Http.Server port is required");
         }
-        this.app = Fastify({ logger: true });
+        this.app = Fastify({ logger: true, ajv: { plugins: [addFormats.default] } });
     }
     async init() {
-        this.setupPlugins();
+        await this.setupPlugins();
         this.setupRoutes();
     }
     async setupPlugins() {
+        // Register custom error handler for validation errors
+        this.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 (this.resource.openapi) {
             const servers = [];
             // const routesByName = new Map<string, HttpRouteResource>();
@@ -56,7 +67,7 @@ class HttpServer {
             const type = mount.type || "";
             const { kind, name } = parseType(type);
             const prefix = mount.path || "";
-            const api = this.ctx.getResourcesByName(kind, name);
+            const api = this.ctx.moduleContext.getInvokable(name);
             if (!api) {
                 throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
             }
@@ -102,3 +113,65 @@ function parseType(type) {
     }
     return { kind: type.slice(0, separator), name: type.slice(separator + 1) };
 }
+/**
+ * Converts Fastify validation errors to standardized Telo format
+ * Returns null if the error is not a validation error
+ */
+function convertFastifyValidationError(error) {
+    // 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,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -17,12 +17,13 @@
     }
   },
   "dependencies": {
+    "@fastify/swagger": "^9.6.1",
+    "@scalar/fastify-api-reference": "^1.44.6",
     "@sinclair/typebox": "^0.34.48",
     "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@fastify/swagger": "^9.6.1",
-    "@scalar/fastify-api-reference": "^1.44.6",
-    "@telorun/sdk": "0.2.3"
+    "@telorun/sdk": "0.2.5"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/http-api-controller.ts

@@ -1,6 +1,6 @@
-import { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { Static, Type } from "@sinclair/typebox";
-import { FastifyInstance } from "fastify";
+import { ControllerContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 
 const HttpApiRouteManifest = Type.Object({
   request: Type.Object({
@@ -15,11 +15,7 @@ const HttpApiRouteManifest = Type.Object({
       }),
     ),
   }),
-  handler: Type.Optional(Type.Object({
-    kind: Type.String(),
-    name: Type.String(),
-    inputs: 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(
@@ -77,7 +73,12 @@ export class HttpServerApi implements ResourceInstance {
 
   private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest) {
     const handler = route.handler ? resolveHandlerName(route.handler) : null;
-    const schema: any = {};
+    const translatedPath = translateOpenApiPath(route.request.path);
+
+    const schema: any = {
+      response: {},
+    };
+
     if (route.request.schema?.query) {
       schema.querystring = route.request.schema?.query;
     }
@@ -90,19 +91,15 @@ export class HttpServerApi implements ResourceInstance {
     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) {
-          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;
+            acc[status] = statusConfig.schema.body;
+          } else {
+            acc[status] = {};
           }
         }
         return acc;
@@ -111,72 +108,126 @@ export class HttpServerApi implements ResourceInstance {
     );
 
     app.route({
-      method: route.request.method,
-      url: route.request.path,
+      method: route.request.method as any,
+      url: translatedPath,
       schema,
-      handler: async (request, reply) => {
-        // const resolveSchema = createSchemaResolver(ctx);
-        const requestPayload = {
-          params: request.params,
-          query: request.query,
-          body: request.body,
-          headers: request.headers,
-          method: request.method,
-          url: request.url,
-        };
-        // validateRequestSchemas(route.request, requestPayload, resolveSchema);
-        const result = handler
-          ? await this.ctx.invoke(
-              handler.kind,
-              handler.name,
-              resolveHandlerInputs(route.handler, requestPayload),
-            )
-          : undefined;
-        // Handle response with body/headers mapping
-
-        const response = route.response;
-
-        // Set status
-        const status =
-          typeof response.status === "string"
-            ? this.ctx.expandValue(response.status, { result })
-            : response.status;
-        if (response.status) {
-          reply.code(status);
-        }
-        const statusConfig = response.statuses[response.status];
-        if (!statusConfig) {
-          return reply.code(500).send({ error: "Invalid response status configuration" });
-        }
-        // Map headers if specified
-        if (statusConfig.headers) {
-          reply.headers(this.ctx.expandValue(statusConfig.headers, { result }));
-        }
+      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,
+          };
+
+          // 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;
 
-        // Map body if specified
-        if (statusConfig.body !== undefined) {
-          const mappedBody = this.ctx.expandValue(statusConfig.body, {
-            result,
-          });
-          if (statusConfig.schema && statusConfig.schema.body) {
-            this.ctx.validateSchema(mappedBody, statusConfig.schema.body);
+          const response = route.response;
+
+          // Determine final status code
+          let statusCode = response.status;
+          if (typeof statusCode === "string") {
+            statusCode = this.ctx.expandValue(statusCode, { result }) as number;
           }
-          return reply.send(mappedBody);
-        }
 
-        // No body mapping, send result as-is
-        return reply.send(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 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);
+        } catch (error) {
+          // Let the error handler deal with all errors
+          throw error;
+        }
       },
     });
   }
 }
 
-export async function create(
-  resource: HttpApiManifest,
-  ctx: ResourceContext,
-): Promise<HttpServerApi> {
+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);
-  return new HttpServerApi(ctx, resource);
+  // 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 } {
@@ -184,29 +235,26 @@ function resolveHandlerName(handler: any): { kind: string; name: string } {
     const [kind, name] = handler.split("/");
     return { kind, name };
   }
-  if (
-    handler &&
-    typeof handler === "object" &&
-    typeof handler.name === "string" &&
-    typeof handler.kind === "string"
-  ) {
-    return { name: handler.name, kind: handler.kind };
+  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");
+  throw new Error("Unable to resolve handler - handler must have a 'kind' property");
 }
 
-function resolveHandlerInputs(handler: any, requestPayload: Record<string, any>): any {
+function resolveHandlerInputs(handler: any, requestContext: Record<string, any>): any {
   if (typeof handler === "string") {
-    return requestPayload;
+    return requestContext;
   }
   if (!handler || typeof handler !== "object") {
-    return requestPayload;
+    return requestContext;
   }
   if (!handler.inputs) {
-    return requestPayload;
+    return requestContext;
   }
-  const context = { request: requestPayload, ...requestPayload };
-  return resolveTemplateInputs(handler.inputs, context);
+  return resolveTemplateInputs(handler.inputs, requestContext);
 }
 
 function resolveTemplateInputs(value: any, context: Record<string, any>): any {
@@ -241,3 +289,78 @@ function resolveTemplatePath(pathExpression: string, context: Record<string, any
   }
   return current;
 }
+
+/**
+ * Translates OpenAPI path format {paramName} to Fastify format :paramName
+ * Example: /api/v1/users/{userId} -> /api/v1/users/:userId
+ */
+function translateOpenApiPath(openApiPath: string): string {
+  return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
+}
+
+/**
+ * Normalizes all header keys to lowercase as per Telo spec
+ */
+function normalizeHeaders(headers: Record<string, any>): Record<string, any> {
+  const normalized: Record<string, any> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    normalized[key.toLowerCase()] = value;
+  }
+  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,6 +1,7 @@
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
 import type { ResourceContext, ResourceInstance, RuntimeResource } from "@telorun/sdk";
+import addFormats from "ajv-formats";
 import Fastify, { FastifyInstance } from "fastify";
 import { HttpServerApi } from "./http-api-controller.js";
 
@@ -86,15 +87,25 @@ class HttpServer implements ResourceInstance {
     if (!this.port) {
       throw new Error("Http.Server port is required");
     }
-    this.app = Fastify({ logger: true });
+    this.app = Fastify({ logger: true, ajv: { plugins: [addFormats.default as any] } });
   }
 
   async init() {
-    this.setupPlugins();
+    await this.setupPlugins();
     this.setupRoutes();
   }
 
   private async setupPlugins() {
+    // Register custom error handler for validation errors
+    this.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 (this.resource.openapi) {
       const servers = [];
       // const routesByName = new Map<string, HttpRouteResource>();
@@ -128,7 +139,7 @@ class HttpServer implements ResourceInstance {
       const { kind, name } = parseType(type);
       const prefix = mount.path || "";
 
-      const api: HttpServerApi = this.ctx.getResourcesByName(kind, name) as any;
+      const api = this.ctx.moduleContext.getInvokable(name) as unknown as HttpServerApi;
 
       if (!api) {
         throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
@@ -181,3 +192,69 @@ function parseType(type: string): { kind: string; name: string } {
   }
   return { kind: type.slice(0, separator), name: type.slice(separator + 1) };
 }
+
+/**
+ * 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,
+  };
+}

package/dist/openapi.js

@@ -1,152 +0,0 @@
-import swagger from '@fastify/swagger';
-import apiReference from '@scalar/fastify-api-reference';
-function getResourceConfig(resource) {
-    return resource;
-}
-export function register(ctx) { }
-export function create(resource, ctx) {
-    const openApiResource = resource;
-    const config = getResourceConfig(openApiResource);
-    const apiRefs = config.apis || [];
-    if (apiRefs.length === 0) {
-        throw new Error(`OpenApi.Spec "${resource.metadata.name}" is missing apis`);
-    }
-    const handler = (payload) => {
-        const serverResource = payload?.resource;
-        const app = payload?.app;
-        if (!serverResource || !app) {
-            throw new Error(`OpenApi.Spec handler missing Http.Server resource or Fastify app`);
-        }
-        const matchedApis = resolveApis(apiRefs, ctx);
-        const mounts = getResourceConfig(serverResource).mounts || [];
-        const servers = buildServers(serverResource, mounts, matchedApis);
-        if (servers.length === 0) {
-            return;
-        }
-        const paths = buildPaths(matchedApis, mounts);
-        const info = config.info && typeof config.info === 'object'
-            ? config.info
-            : {
-                title: resource.metadata.name,
-                version: resource.version || '1.0.0',
-            };
-        const routePrefix = config.path || `/openapi/${resource.metadata.name}`;
-        app.register(swagger, {
-            openapi: {
-                openapi: '3.0.0',
-                info,
-                servers,
-                paths,
-            },
-            routePrefix,
-        });
-        app.register(apiReference, {
-            routePrefix,
-        });
-    };
-    const httpServers = ctx.getResources('Http.Server');
-    return {
-        init: async () => {
-            // Register listeners after all resources are initialized
-            for (const server of httpServers) {
-                ctx.on('Http.Server.Ready', server.metadata.name, handler);
-            }
-        },
-        teardown: () => {
-            for (const server of httpServers) {
-                ctx.offResourceEvent('Http.Server', server.metadata.name, 'Ready', handler);
-            }
-        },
-    };
-}
-function resolveApis(apiRefs, ctx) {
-    const apis = [];
-    for (const ref of apiRefs) {
-        const { kind, name } = parseRef(ref);
-        if (!kind || !name) {
-            throw new Error(`Reference not found: ${ref}`);
-        }
-        if (kind !== 'Http.Api' && kind !== 'Http.Route') {
-            throw new Error(`Reference not supported: ${ref}`);
-        }
-        const resource = ctx.kernel.registry.get(kind)?.get(name);
-        if (!resource) {
-            throw new Error(`Reference not found: ${ref}`);
-        }
-        apis.push(resource);
-    }
-    return apis;
-}
-function buildServers(server, mounts, apis) {
-    const config = getResourceConfig(server);
-    const host = config.host || '0.0.0.0';
-    const port = Number(config.port || 0);
-    if (!port) {
-        return [];
-    }
-    // Server URL should be the base URL without mount paths
-    // Paths will include the mount prefix
-    return [{ url: `http://${host}:${port}` }];
-}
-function buildPaths(apis, mounts) {
-    const paths = {};
-    const mountPrefixByType = new Map();
-    for (const mount of mounts) {
-        if (mount.type) {
-            mountPrefixByType.set(mount.type, mount.path || '');
-        }
-    }
-    for (const api of apis) {
-        const prefix = mountPrefixByType.get(`${api.kind}.${api.metadata.name}`) || '';
-        if (api.kind === 'Http.Route') {
-            const config = getResourceConfig(api);
-            const path = joinPath(prefix, api.metadata?.path || config.path || '');
-            const method = (api.metadata?.method ||
-                config.method ||
-                'GET').toLowerCase();
-            if (!path) {
-                continue;
-            }
-            if (!paths[path]) {
-                paths[path] = {};
-            }
-            paths[path][method] = { responses: { '200': { description: 'OK' } } };
-            continue;
-        }
-        const routes = getResourceConfig(api).routes || [];
-        for (const route of routes) {
-            if (typeof route === 'string') {
-                continue;
-            }
-            const request = route.request || {};
-            const path = joinPath(prefix, request.path || '');
-            const method = (request.method || 'GET').toLowerCase();
-            if (!path) {
-                continue;
-            }
-            if (!paths[path]) {
-                paths[path] = {};
-            }
-            paths[path][method] = { responses: { '200': { description: 'OK' } } };
-        }
-    }
-    return paths;
-}
-function parseRef(ref) {
-    const separator = ref.lastIndexOf('.');
-    if (separator <= 0 || separator === ref.length - 1) {
-        return { kind: '', name: '' };
-    }
-    return { kind: ref.slice(0, separator), name: ref.slice(separator + 1) };
-}
-function joinPath(prefix, path) {
-    if (!prefix) {
-        return path;
-    }
-    if (!path) {
-        return prefix;
-    }
-    const trimmedPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
-    const trimmedPath = path.startsWith('/') ? path : `/${path}`;
-    return `${trimmedPrefix}${trimmedPath}`;
-}