alepha 0.20.3 → 0.20.5

package/src/server/core/__tests__/ServerRouterProvider-validationError.spec.ts

@@ -0,0 +1,306 @@
+import { Alepha, t } from "alepha";
+import { describe, it } from "vitest";
+import { $route, ServerProvider } from "../index.ts";
+
+class TestApp {
+  createUser = $route({
+    method: "POST",
+    path: "/users",
+    schema: {
+      body: t.object({
+        name: t.text(),
+        age: t.integer(),
+      }),
+    },
+    handler: () => {},
+  });
+
+  getUser = $route({
+    method: "GET",
+    path: "/users/:id",
+    schema: {
+      params: t.object({
+        id: t.integer(),
+      }),
+    },
+    handler: () => {},
+  });
+
+  searchUsers = $route({
+    method: "GET",
+    path: "/users",
+    schema: {
+      query: t.object({
+        limit: t.integer({ minimum: 1, maximum: 100 }),
+      }),
+    },
+    handler: () => {},
+  });
+
+  protectedRoute = $route({
+    method: "GET",
+    path: "/protected",
+    schema: {
+      headers: t.object({
+        "x-api-version": t.integer(),
+      }),
+    },
+    handler: () => {},
+  });
+}
+
+const fetchAndStop = async (
+  alepha: Alepha,
+  build: (hostname: string) => { url: string; init?: RequestInit },
+) => {
+  await alepha.start();
+  const hostname = alepha.inject(ServerProvider).hostname;
+  const { url, init } = build(hostname);
+  const response = await fetch(url, init);
+  const json = await response.json();
+  await alepha.stop();
+  return { response, json };
+};
+
+describe("ServerRouterProvider - request validation error", () => {
+  describe("body validation", () => {
+    it("should expose a wrong-type rejection (expected integer, got string)", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users`,
+        init: {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "John", age: "not-a-number" }),
+        },
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request body:/);
+      expect(json.message.toLowerCase()).toMatch(/integer|expected/);
+      // path locates the offending field
+      expect(json.details).toBe("/age");
+    });
+
+    it("should expose a missing-field rejection (required property `age`)", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users`,
+        init: {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "John" }),
+        },
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request body:/);
+      // message must name the missing field
+      expect(json.message).toContain("age");
+      expect(json.message.toLowerCase()).toMatch(/required/);
+    });
+
+    it("should behave identically in development mode", async ({ expect }) => {
+      const alepha = Alepha.create().with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users`,
+        init: {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "John" }),
+        },
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request body:/);
+      expect(json.message.toLowerCase()).toMatch(/age|required/);
+    });
+  });
+
+  describe("params validation", () => {
+    it("should expose the rejection reason in production", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users/not-a-number`,
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request params:/);
+      expect(json.message.toLowerCase()).toMatch(/integer|number|expected/);
+    });
+  });
+
+  describe("query validation", () => {
+    it("should expose the rejection reason in production", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/users?limit=9999`,
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request query:/);
+      expect(json.message.toLowerCase()).toMatch(/maximum|less|<=|100/);
+    });
+  });
+
+  describe("header validation", () => {
+    it("should expose the rejection reason in production", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(TestApp);
+
+      const { response, json } = await fetchAndStop(alepha, (host) => ({
+        url: `${host}/protected`,
+        // omit required header
+      }));
+
+      expect(response.status).toBe(400);
+      expect(json.error).toBe("ValidationError");
+      expect(json.message).toMatch(/^Invalid request header:/);
+      expect(json.message.toLowerCase()).toMatch(/x-api-version|required/);
+    });
+
+    it("should coerce string header values to declared schema types", async ({
+      expect,
+    }) => {
+      const seen: { version?: unknown } = {};
+      class CoerceApp {
+        captured = $route({
+          method: "GET",
+          path: "/coerce",
+          schema: {
+            headers: t.object({
+              "x-api-version": t.integer(),
+            }),
+          },
+          handler: ({ headers }) => {
+            seen.version = headers["x-api-version"];
+          },
+        });
+      }
+
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(CoerceApp);
+
+      await alepha.start();
+      const host = alepha.inject(ServerProvider).hostname;
+      const response = await fetch(`${host}/coerce`, {
+        headers: { "x-api-version": "42" },
+      });
+      await alepha.stop();
+
+      expect([200, 204]).toContain(response.status);
+      expect(seen.version).toBe(42);
+      expect(typeof seen.version).toBe("number");
+    });
+
+    it("should preserve undeclared headers (auth, user-agent, ...)", async ({
+      expect,
+    }) => {
+      const seen: { authorization?: string; userAgent?: string } = {};
+      class PreserveApp {
+        check = $route({
+          method: "GET",
+          path: "/preserve",
+          schema: {
+            headers: t.object({
+              "x-api-version": t.integer(),
+            }),
+          },
+          handler: ({ headers }) => {
+            const all = headers as unknown as Record<string, string>;
+            seen.authorization = all.authorization;
+            seen.userAgent = all["user-agent"];
+          },
+        });
+      }
+
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(PreserveApp);
+
+      await alepha.start();
+      const host = alepha.inject(ServerProvider).hostname;
+      const response = await fetch(`${host}/preserve`, {
+        headers: {
+          "x-api-version": "1",
+          authorization: "Bearer abc.def.ghi",
+          "user-agent": "MyClient/1.0",
+        },
+      });
+      await alepha.stop();
+
+      expect([200, 204]).toContain(response.status);
+      expect(seen.authorization).toBe("Bearer abc.def.ghi");
+      expect(seen.userAgent).toBe("MyClient/1.0");
+    });
+
+    it("should accept schema keys regardless of case (lowercase normalization)", async ({
+      expect,
+    }) => {
+      const seen: { version?: unknown } = {};
+      class CaseApp {
+        // Schema declares keys with mixed case — Node lowercases incoming
+        // header names, so the framework must lowercase schema keys when
+        // matching values.
+        check = $route({
+          method: "GET",
+          path: "/case",
+          schema: {
+            headers: t.object({
+              "X-Api-Version": t.integer(),
+            }),
+          },
+          handler: ({ headers }) => {
+            seen.version = (headers as Record<string, unknown>)[
+              "x-api-version"
+            ];
+          },
+        });
+      }
+
+      const alepha = Alepha.create({
+        env: { NODE_ENV: "production", SERVER_PORT: 0 },
+      }).with(CaseApp);
+
+      await alepha.start();
+      const host = alepha.inject(ServerProvider).hostname;
+      const response = await fetch(`${host}/case`, {
+        headers: { "x-api-version": "7" },
+      });
+      await alepha.stop();
+
+      expect([200, 204]).toContain(response.status);
+      expect(seen.version).toBe(7);
+    });
+  });
+});

package/src/server/core/errors/ValidationError.ts

@@ -1,11 +1,23 @@
+import { TypeBoxError } from "alepha";
 import { HttpError } from "./HttpError.ts";
 
 export class ValidationError extends HttpError {
   constructor(message = "Validation has failed", cause?: unknown) {
+    let fullMessage = message;
+    let details: string | undefined;
+
+    if (cause instanceof TypeBoxError) {
+      fullMessage = `${message}: ${cause.cause.message}`;
+      if (cause.cause.instancePath) {
+        details = cause.cause.instancePath;
+      }
+    }
+
     super(
       {
-        message,
+        message: fullMessage,
         status: 400,
+        details,
       },
       cause,
     );

package/src/server/core/primitives/$action.ts

@@ -256,7 +256,7 @@ export class ActionPrimitive<
 
   public get route(): ServerRoute {
     return {
-      ...(this.options as any), // TODO: fix schema.header mapping
+      ...this.options,
       method: this.method,
       path: `${this.prefix}${this.path}`,
       handler: this.handler,
@@ -399,10 +399,21 @@ export class ActionPrimitive<
       }
 
       if (serverActionRequest.headers && this.options.schema?.headers) {
-        serverActionRequest.headers = this.alepha.codec.encode(
-          this.options.schema.headers,
-          serverActionRequest.headers,
-        ) as Record<string, any>;
+        // Per-key encode (matches the server-side decode pattern in
+        // ServerRouterProvider.validateRequest): coerces declared headers via
+        // the schema, leaves undeclared ones untouched. Schema keys are
+        // lowercased to match Node's incoming header convention.
+        const schemaHeaders = this.options.schema.headers;
+        const headers = serverActionRequest.headers as Record<string, unknown>;
+        for (const key of Object.keys(schemaHeaders.properties)) {
+          const lcKey = key.toLowerCase();
+          if (headers[lcKey] !== undefined) {
+            headers[lcKey] = this.alepha.codec.encode(
+              schemaHeaders.properties[key],
+              headers[lcKey],
+            );
+          }
+        }
       }
 
       if (serverActionRequest.body && this.options.schema?.body) {

package/src/server/core/providers/ServerRouterProvider.ts

@@ -484,10 +484,32 @@ export class ServerRouterProvider extends RouterProvider<ServerRouteMatcher> {
 
     if (route.schema?.headers) {
       try {
-        request.headers = this.alepha.codec.validate(
-          route.schema.headers,
-          request.headers,
-        ) as any;
+        const schemaHeaders = route.schema.headers;
+
+        // Per-key decode (mirrors `query` handling): coerces declared header
+        // values from strings to their schema types (int/bool/date). Then
+        // validate the decoded subset against the full schema so TypeBox
+        // produces consistent error messages (missing-required, type
+        // mismatch). Finally merge the decoded values back into
+        // `request.headers` so undeclared headers (auth, cookie, user-agent,
+        // ...) survive the validation step intact.
+        const decoded: Record<string, unknown> = {};
+        for (const key of Object.keys(schemaHeaders.properties)) {
+          const lcKey = key.toLowerCase();
+          const value = request.headers[lcKey];
+          if (value == null) continue;
+          decoded[key] = this.alepha.codec.decode(
+            schemaHeaders.properties[key],
+            value,
+          );
+        }
+
+        this.alepha.codec.validate(schemaHeaders, decoded);
+
+        for (const [key, value] of Object.entries(decoded)) {
+          (request.headers as Record<string, unknown>)[key.toLowerCase()] =
+            value;
+        }
       } catch (error) {
         throw new ValidationError("Invalid request header", error);
       }

package/src/server/swagger/providers/ServerSwaggerProvider.ts

@@ -201,14 +201,12 @@ export class ServerSwaggerProvider {
         hasSecurity = true;
       }
 
-      const g = t.raw;
-
       if (
-        g.IsObject(route.options.schema.body) ||
-        g.IsArray(route.options.schema.body)
+        t.schema.isObject(route.options.schema.body) ||
+        t.schema.isArray(route.options.schema.body)
       ) {
         if (
-          g.IsObject(route.options.schema.body) &&
+          t.schema.isObject(route.options.schema.body) &&
           this.isBodyMultipart(route.options.schema.body)
         ) {
           operation.requestBody = {
@@ -231,7 +229,7 @@ export class ServerSwaggerProvider {
         }
       }
 
-      if (g.IsObject(route.options.schema.query)) {
+      if (t.schema.isObject(route.options.schema.query)) {
         operation.parameters ??= [];
         const requiredKeys: string[] =
           route.options.schema.query.required ?? [];
@@ -250,7 +248,7 @@ export class ServerSwaggerProvider {
         }
       }
 
-      if (g.IsObject(route.options.schema.params)) {
+      if (t.schema.isObject(route.options.schema.params)) {
         operation.parameters ??= [];
         for (const [key, value] of Object.entries(
           route.options.schema.params.properties,

package/src/websocket/providers/NodeWebSocketServerProvider.ts

@@ -6,9 +6,9 @@ import {
   $state,
   Alepha,
   AlephaError,
+  SchemaValidator,
   type Static,
   t,
-  Value,
 } from "alepha";
 import { $logger } from "alepha/logger";
 import { WebSocket, WebSocketServer } from "ws";
@@ -495,6 +495,7 @@ export class NodeWebSocketServerProvider extends WebSocketServerProvider {
 
 export class NodeWebSocketConnection implements WebSocketConnection {
   protected readonly log = $logger();
+  protected readonly schemaValidator = $inject(SchemaValidator);
   public metadata?: Record<string, any>;
 
   constructor(
@@ -556,10 +557,15 @@ export class NodeWebSocketConnection implements WebSocketConnection {
 
       // Validate message against schema (out = client→server)
       const outSchema = this.endpoint.channel.options.schema.out;
-      if (!Value.Check(outSchema, message)) {
-        const errors = Array.from(Value.Errors(outSchema, message));
+      try {
+        this.schemaValidator.validate(outSchema, message, {
+          trim: false,
+          nullToUndefined: false,
+          deleteUndefined: false,
+        });
+      } catch (err) {
         throw new WebSocketValidationError(
-          `Message validation failed: ${errors.map((e: any) => e.message).join(", ")}`,
+          `Message validation failed: ${(err as Error).message}`,
         );
       }
 

package/src/websocket/services/WebSocketClient.ts

@@ -3,9 +3,9 @@ import {
   $inject,
   Alepha,
   AlephaError,
+  SchemaValidator,
   type Static,
   t,
-  Value,
 } from "alepha";
 import { $logger } from "alepha/logger";
 import type { ChannelPrimitive, TWSObject } from "../primitives/$channel.ts";
@@ -50,6 +50,7 @@ export class WebSocketChannelConnection<
   TServer extends TWSObject,
 > {
   protected readonly alepha = $inject(Alepha);
+  protected readonly schemaValidator = $inject(SchemaValidator);
   protected readonly log = $logger();
   protected ws?: WebSocket;
   protected reconnectAttempts = 0;
@@ -346,11 +347,16 @@ export class WebSocketChannelConnection<
 
     // Validate outgoing message against schema
     const outSchema = this.channel.options.schema.out;
-    if (!Value.Check(outSchema, message)) {
-      const errors = Array.from(Value.Errors(outSchema, message));
-      this.log.warn("Message validation failed", { errors });
+    try {
+      this.schemaValidator.validate(outSchema, message, {
+        trim: false,
+        nullToUndefined: false,
+        deleteUndefined: false,
+      });
+    } catch (err) {
+      this.log.warn("Message validation failed", { error: err });
       throw new AlephaError(
-        `Message validation failed: ${errors.map((e) => e.message).join(", ")}`,
+        `Message validation failed: ${(err as Error).message}`,
       );
     }
 

package/src/mcp/transports/SseMcpTransport.ts

@@ -1,182 +0,0 @@
-import { $atom, $inject, $state, t } from "alepha";
-import { $logger } from "alepha/logger";
-import { $route } from "alepha/server";
-import {
-  createErrorResponse,
-  createNotification,
-  createParseError,
-  JsonRpcParseError,
-  parseMessage,
-} from "../helpers/jsonrpc.ts";
-import type { McpContext } from "../interfaces/McpTypes.ts";
-import { McpServerProvider } from "../providers/McpServerProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export const mcpSseOptions = $atom({
-  name: "alepha.mcp.sse.options",
-  description: "Configuration options for the MCP SSE transport.",
-  schema: t.object({
-    /**
-     * Path for the MCP SSE endpoint.
-     */
-    path: t.text({ default: "/mcp" }),
-  }),
-  default: {
-    path: "/mcp",
-  },
-});
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * SSE (Server-Sent Events) transport for MCP communication.
- *
- * This transport uses HTTP with SSE for server-to-client messages
- * and POST requests for client-to-server messages.
- *
- * Endpoints:
- * - GET /mcp - SSE stream for server events
- * - POST /mcp - JSON-RPC request endpoint
- *
- * @example
- * ```ts
- * import { Alepha, run } from "alepha";
- * import { AlephaServer } from "alepha/server";
- * import { AlephaMcp, AlephaMcpSse } from "alepha/mcp";
- *
- * class MyTools {
- *   // ... tool definitions
- * }
- *
- * run(
- *   Alepha.create()
- *     .with(AlephaServer)
- *     .with(AlephaMcp)
- *     .with(AlephaMcpSse)
- *     .with(MyTools)
- * );
- * ```
- */
-export class SseMcpTransport {
-  protected readonly log = $logger();
-  protected readonly options = $state(mcpSseOptions);
-  protected readonly mcpServer = $inject(McpServerProvider);
-
-  /**
-   * SSE endpoint for server-to-client messages.
-   *
-   * Returns a text/event-stream response with server capabilities
-   * and keeps the connection open for notifications.
-   */
-  sse = $route({
-    method: "GET",
-    path: this.options.path,
-    handler: async (request) => {
-      this.log.debug("MCP SSE connection established");
-
-      const encoder = new TextEncoder();
-
-      // Create SSE stream
-      const stream = new ReadableStream({
-        start: (controller) => {
-          // Send initial endpoint info
-          const endpointEvent = this.formatSseEvent(
-            "endpoint",
-            `${this.options.path}`,
-          );
-          controller.enqueue(encoder.encode(endpointEvent));
-
-          // Send capabilities notification
-          const capabilitiesNotification = createNotification(
-            "notifications/capabilities",
-            { capabilities: this.mcpServer.getCapabilities() },
-          );
-          const capabilitiesEvent = this.formatSseEvent(
-            "message",
-            JSON.stringify(capabilitiesNotification),
-          );
-          controller.enqueue(encoder.encode(capabilitiesEvent));
-        },
-        cancel: () => {
-          this.log.debug("MCP SSE connection closed");
-        },
-      });
-
-      request.reply.status = 200;
-      request.reply.headers = {
-        "content-type": "text/event-stream",
-        "cache-control": "no-cache",
-        connection: "keep-alive",
-      };
-      request.reply.body = stream;
-    },
-  });
-
-  /**
-   * POST endpoint for client-to-server JSON-RPC messages.
-   */
-  message = $route({
-    method: "POST",
-    path: this.options.path,
-    schema: {
-      body: t.json(),
-    },
-    handler: async (request) => {
-      try {
-        const body =
-          typeof request.body === "string"
-            ? request.body
-            : JSON.stringify(request.body);
-
-        this.log.debug("MCP request body", {
-          body,
-          bodyType: typeof request.body,
-        });
-
-        const rpcRequest = parseMessage(body);
-
-        // Build context from request headers
-        const headers = { ...request.headers } as Record<
-          string,
-          string | string[] | undefined
-        >;
-
-        const context: McpContext = { headers };
-
-        const response = await this.mcpServer.handleMessage(
-          rpcRequest,
-          context,
-        );
-
-        if (response) {
-          request.reply.headers["content-type"] = "application/json";
-          request.reply.body = JSON.stringify(response);
-        } else {
-          request.reply.status = 204;
-        }
-      } catch (error) {
-        if (error instanceof JsonRpcParseError) {
-          request.reply.status = 400;
-          request.reply.headers["content-type"] = "application/json";
-          request.reply.body = JSON.stringify(
-            createErrorResponse(0, createParseError(error.message)),
-          );
-        } else {
-          this.log.error("Failed to process MCP message", error);
-          request.reply.status = 500;
-          request.reply.body = JSON.stringify({
-            error: (error as Error).message,
-          });
-        }
-      }
-    },
-  });
-
-  /**
-   * Format a message as an SSE event.
-   */
-  protected formatSseEvent(event: string, data: string): string {
-    return `event: ${event}\ndata: ${data}\n\n`;
-  }
-}