@telorun/http-server 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @telorun/http-server
 
+## 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({
@@ -41,6 +37,16 @@ export class HttpServerApi {
     }
     async init() { }
     register(app, 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) => {
                 this.registerRoutes(scoped);
@@ -58,7 +64,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;
         }
@@ -89,84 +98,128 @@ export class HttpServerApi {
         }, {});
         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 });
                     }
-                    return reply.send(mappedBody);
+                    // 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);
+                }
+                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 +252,132 @@ 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;
+}
+/**
+ * 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,
+    };
+}
+/**
+ * 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/test-validation.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-validation.js

@@ -0,0 +1,36 @@
+// Test file to validate error conversion logic
+import { convertFastifyValidationError } from "./http-api-controller.js";
+function testValidationError() {
+    // Test case 1: Querystring validation error
+    const error1 = {
+        code: "FST_ERR_VALIDATION",
+        message: "querystring must have required property 'name'",
+        statusCode: 400,
+        error: "Bad Request",
+    };
+    const result1 = convertFastifyValidationError(error1);
+    console.log("Test 1 - Querystring required field:", JSON.stringify(result1, null, 2));
+    console.log("✓ Location:", result1?.details[0].location === "query" ? "PASS" : "FAIL");
+    console.log("✓ Path:", result1?.details[0].path === "name" ? "PASS" : "FAIL");
+    console.log("✓ Message:", result1?.details[0].message.includes("required") ? "PASS" : "FAIL");
+    // Test case 2: Body validation error
+    const error2 = {
+        code: "FST_ERR_VALIDATION",
+        message: "body must be object",
+        statusCode: 400,
+    };
+    const result2 = convertFastifyValidationError(error2);
+    console.log("\nTest 2 - Body type error:", JSON.stringify(result2, null, 2));
+    console.log("✓ Location:", result2?.details[0].location === "body" ? "PASS" : "FAIL");
+    // Test case 3: Non-validation error (should return null)
+    const error3 = {
+        code: "ERR_OTHER",
+        message: "Some other error",
+    };
+    const result3 = convertFastifyValidationError(error3);
+    console.log("\nTest 3 - Non-validation error:", result3 === null ? "PASS (null)" : "FAIL (not null)");
+}
+// Only run if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    testValidationError();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,7 +22,7 @@
     "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.4"
   },
   "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(
@@ -56,6 +52,17 @@ 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) => {
@@ -77,7 +84,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,6 +102,7 @@ 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];
@@ -111,72 +124,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 +251,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 +305,144 @@ 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;
+}
+
+/**
+ * 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";
+}