@webpieces/http-server 0.2.14 → 0.2.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-server",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "WebPieces server with filter chain and dependency injection",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,9 +22,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-meta": "0.2.14",
-    "@webpieces/core-util": "0.2.14",
-    "@webpieces/http-routing": "0.2.14",
-    "@webpieces/http-filters": "0.2.14"
+    "@webpieces/core-util": "0.2.16",
+    "@webpieces/http-routing": "0.2.16",
+    "@webpieces/http-filters": "0.2.16"
   }
 }

package/src/WebpiecesFactory.d.ts

@@ -1,4 +1,5 @@
-import { WebAppMeta } from '@webpieces/core-meta';
+import { ContainerModule } from 'inversify';
+import { WebAppMeta } from '@webpieces/http-routing';
 import { WebpiecesServer } from './WebpiecesServer';
 /**
  * WebpiecesFactory - Factory for creating WebPieces server instances.
@@ -15,10 +16,16 @@ import { WebpiecesServer } from './WebpiecesServer';
  *
  * Usage:
  * ```typescript
+ * // Production
  * const server = WebpiecesFactory.create(new ProdServerMeta());
  * server.start(8080);
- * // ... later
- * server.stop();
+ *
+ * // Testing with overrides
+ * const overrides = new ContainerModule((bind) => {
+ *     bind(TYPES.RemoteApi).toConstantValue(mockRemoteApi);
+ * });
+ * const server = WebpiecesFactory.create(new ProdServerMeta(), overrides);
+ * const api = server.createApiClient(SaveApiPrototype);
  * ```
  *
  * This pattern:
@@ -36,9 +43,21 @@ export declare class WebpiecesFactory {
      * 2. Loads framework bindings via buildProviderModule()
      * 3. Resolves the server implementation from DI
      * 4. Initializes the server with the container and meta
+     * 5. Loads optional override module (for testing)
      *
      * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @param overrides - Optional ContainerModule for test overrides (loaded LAST to override bindings)
      * @returns A fully initialized WebpiecesServer ready to start()
      */
-    static create(meta: WebAppMeta): WebpiecesServer;
+    /**
+     * Create a new WebPieces server instance asynchronously.
+     *
+     * Use this method when you need async operations in your override modules
+     * (e.g., rebind() in new Inversify versions).
+     *
+     * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @param overrides - Optional ContainerModule for test overrides (can use async operations)
+     * @returns Promise of a fully initialized WebpiecesServer ready to start()
+     */
+    static create(meta: WebAppMeta, overrides?: ContainerModule, testMode?: boolean): Promise<WebpiecesServer>;
 }

package/src/WebpiecesFactory.js

@@ -19,10 +19,16 @@ const WebpiecesServerImpl_1 = require("./WebpiecesServerImpl");
  *
  * Usage:
  * ```typescript
+ * // Production
  * const server = WebpiecesFactory.create(new ProdServerMeta());
  * server.start(8080);
- * // ... later
- * server.stop();
+ *
+ * // Testing with overrides
+ * const overrides = new ContainerModule((bind) => {
+ *     bind(TYPES.RemoteApi).toConstantValue(mockRemoteApi);
+ * });
+ * const server = WebpiecesFactory.create(new ProdServerMeta(), overrides);
+ * const api = server.createApiClient(SaveApiPrototype);
  * ```
  *
  * This pattern:
@@ -40,20 +46,31 @@ class WebpiecesFactory {
      * 2. Loads framework bindings via buildProviderModule()
      * 3. Resolves the server implementation from DI
      * 4. Initializes the server with the container and meta
+     * 5. Loads optional override module (for testing)
      *
      * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @param overrides - Optional ContainerModule for test overrides (loaded LAST to override bindings)
      * @returns A fully initialized WebpiecesServer ready to start()
      */
-    static create(meta) {
+    /**
+     * Create a new WebPieces server instance asynchronously.
+     *
+     * Use this method when you need async operations in your override modules
+     * (e.g., rebind() in new Inversify versions).
+     *
+     * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @param overrides - Optional ContainerModule for test overrides (can use async operations)
+     * @returns Promise of a fully initialized WebpiecesServer ready to start()
+     */
+    static async create(meta, overrides, testMode) {
         // Create WebPieces container for framework-level bindings
         const webpiecesContainer = new inversify_1.Container();
         // Load buildProviderModule to auto-scan for @provideSingleton decorators
-        // This registers framework classes (WebpiecesServerImpl, RouteBuilderImpl)
-        webpiecesContainer.load((0, binding_decorators_1.buildProviderModule)());
-        // Resolve WebpiecesServerImpl from DI container (proper DI - no 'new'!)
+        await webpiecesContainer.load((0, binding_decorators_1.buildProviderModule)());
+        // Resolve WebpiecesServerImpl from DI container
         const serverImpl = webpiecesContainer.get(WebpiecesServerImpl_1.WebpiecesServerImpl);
-        // Initialize the server (loads app DI modules, registers routes)
-        serverImpl.initialize(webpiecesContainer, meta);
+        // Initialize the server asynchronously (loads app DI modules, registers routes)
+        await serverImpl.initialize(webpiecesContainer, meta, overrides);
         // Return as interface to hide initialize() from consumers
         return serverImpl;
     }

package/src/WebpiecesFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesFactory.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesFactory.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AACtC,wEAAsE;AAGtE,+DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAa,gBAAgB;IAC3B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,IAAgB;QAC5B,0DAA0D;QAC1D,MAAM,kBAAkB,GAAG,IAAI,qBAAS,EAAE,CAAC;QAE3C,yEAAyE;QACzE,2EAA2E;QAC3E,kBAAkB,CAAC,IAAI,CAAC,IAAA,wCAAmB,GAAE,CAAC,CAAC;QAE/C,wEAAwE;QACxE,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,yCAAmB,CAAC,CAAC;QAE/D,iEAAiE;QACjE,UAAU,CAAC,UAAU,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QAEhD,0DAA0D;QAC1D,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AA9BD,4CA8BC","sourcesContent":["import { Container } from 'inversify';\nimport { buildProviderModule } from '@inversifyjs/binding-decorators';\nimport { WebAppMeta } from '@webpieces/core-meta';\nimport { WebpiecesServer } from './WebpiecesServer';\nimport { WebpiecesServerImpl } from './WebpiecesServerImpl';\n\n/**\n * WebpiecesFactory - Factory for creating WebPieces server instances.\n *\n * This factory encapsulates the server creation and initialization logic:\n * 1. Creates the WebPieces DI container\n * 2. Loads the provider module for @provideSingleton decorators\n * 3. Resolves WebpiecesServerImpl from DI\n * 4. Calls initialize() with the container and meta\n * 5. Returns the server as the WebpiecesServer interface\n *\n * The returned WebpiecesServer interface only exposes start() and stop(),\n * hiding the internal initialize() method from consumers.\n *\n * Usage:\n * ```typescript\n * const server = WebpiecesFactory.create(new ProdServerMeta());\n * server.start(8080);\n * // ... later\n * server.stop();\n * ```\n *\n * This pattern:\n * - Enforces proper initialization order\n * - Hides implementation details from consumers\n * - Makes the API simpler and harder to misuse\n * - Follows the principle of least privilege\n */\nexport class WebpiecesFactory {\n  /**\n   * Create a new WebPieces server instance.\n   *\n   * This method:\n   * 1. Creates the WebPieces framework DI container\n   * 2. Loads framework bindings via buildProviderModule()\n   * 3. Resolves the server implementation from DI\n   * 4. Initializes the server with the container and meta\n   *\n   * @param meta - User-provided WebAppMeta with DI modules and routes\n   * @returns A fully initialized WebpiecesServer ready to start()\n   */\n  static create(meta: WebAppMeta): WebpiecesServer {\n    // Create WebPieces container for framework-level bindings\n    const webpiecesContainer = new Container();\n\n    // Load buildProviderModule to auto-scan for @provideSingleton decorators\n    // This registers framework classes (WebpiecesServerImpl, RouteBuilderImpl)\n    webpiecesContainer.load(buildProviderModule());\n\n    // Resolve WebpiecesServerImpl from DI container (proper DI - no 'new'!)\n    const serverImpl = webpiecesContainer.get(WebpiecesServerImpl);\n\n    // Initialize the server (loads app DI modules, registers routes)\n    serverImpl.initialize(webpiecesContainer, meta);\n\n    // Return as interface to hide initialize() from consumers\n    return serverImpl;\n  }\n}\n"]}
+{"version":3,"file":"WebpiecesFactory.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesFactory.ts"],"names":[],"mappings":";;;AAAA,yCAAuD;AACvD,wEAAsE;AAGtE,+DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAa,gBAAgB;IACzB;;;;;;;;;;;;;OAaG;IAEH;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CACf,IAAgB,EAChB,SAA2B,EAC3B,QAAkB;QAElB,0DAA0D;QAC1D,MAAM,kBAAkB,GAAG,IAAI,qBAAS,EAAE,CAAC;QAE3C,yEAAyE;QACzE,MAAM,kBAAkB,CAAC,IAAI,CAAC,IAAA,wCAAmB,GAAE,CAAC,CAAC;QAErD,gDAAgD;QAChD,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,yCAAmB,CAAC,CAAC;QAE/D,gFAAgF;QAChF,MAAM,UAAU,CAAC,UAAU,CAAC,kBAAkB,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QAEjE,0DAA0D;QAC1D,OAAO,UAAU,CAAC;IACtB,CAAC;CACJ;AA9CD,4CA8CC","sourcesContent":["import { Container, ContainerModule } from 'inversify';\nimport { buildProviderModule } from '@inversifyjs/binding-decorators';\nimport { WebAppMeta } from '@webpieces/http-routing';\nimport { WebpiecesServer } from './WebpiecesServer';\nimport { WebpiecesServerImpl } from './WebpiecesServerImpl';\n\n/**\n * WebpiecesFactory - Factory for creating WebPieces server instances.\n *\n * This factory encapsulates the server creation and initialization logic:\n * 1. Creates the WebPieces DI container\n * 2. Loads the provider module for @provideSingleton decorators\n * 3. Resolves WebpiecesServerImpl from DI\n * 4. Calls initialize() with the container and meta\n * 5. Returns the server as the WebpiecesServer interface\n *\n * The returned WebpiecesServer interface only exposes start() and stop(),\n * hiding the internal initialize() method from consumers.\n *\n * Usage:\n * ```typescript\n * // Production\n * const server = WebpiecesFactory.create(new ProdServerMeta());\n * server.start(8080);\n *\n * // Testing with overrides\n * const overrides = new ContainerModule((bind) => {\n *     bind(TYPES.RemoteApi).toConstantValue(mockRemoteApi);\n * });\n * const server = WebpiecesFactory.create(new ProdServerMeta(), overrides);\n * const api = server.createApiClient(SaveApiPrototype);\n * ```\n *\n * This pattern:\n * - Enforces proper initialization order\n * - Hides implementation details from consumers\n * - Makes the API simpler and harder to misuse\n * - Follows the principle of least privilege\n */\nexport class WebpiecesFactory {\n    /**\n     * Create a new WebPieces server instance.\n     *\n     * This method:\n     * 1. Creates the WebPieces framework DI container\n     * 2. Loads framework bindings via buildProviderModule()\n     * 3. Resolves the server implementation from DI\n     * 4. Initializes the server with the container and meta\n     * 5. Loads optional override module (for testing)\n     *\n     * @param meta - User-provided WebAppMeta with DI modules and routes\n     * @param overrides - Optional ContainerModule for test overrides (loaded LAST to override bindings)\n     * @returns A fully initialized WebpiecesServer ready to start()\n     */\n\n    /**\n     * Create a new WebPieces server instance asynchronously.\n     *\n     * Use this method when you need async operations in your override modules\n     * (e.g., rebind() in new Inversify versions).\n     *\n     * @param meta - User-provided WebAppMeta with DI modules and routes\n     * @param overrides - Optional ContainerModule for test overrides (can use async operations)\n     * @returns Promise of a fully initialized WebpiecesServer ready to start()\n     */\n    static async create(\n        meta: WebAppMeta,\n        overrides?: ContainerModule,\n        testMode?: boolean\n    ): Promise<WebpiecesServer> {\n        // Create WebPieces container for framework-level bindings\n        const webpiecesContainer = new Container();\n\n        // Load buildProviderModule to auto-scan for @provideSingleton decorators\n        await webpiecesContainer.load(buildProviderModule());\n\n        // Resolve WebpiecesServerImpl from DI container\n        const serverImpl = webpiecesContainer.get(WebpiecesServerImpl);\n\n        // Initialize the server asynchronously (loads app DI modules, registers routes)\n        await serverImpl.initialize(webpiecesContainer, meta, overrides);\n\n        // Return as interface to hide initialize() from consumers\n        return serverImpl;\n    }\n}\n"]}

package/src/WebpiecesMiddleware.d.ts

@@ -0,0 +1,59 @@
+import { Request, Response, NextFunction } from 'express';
+import { MethodMeta } from '@webpieces/http-routing';
+import { RouteMetadata } from '@webpieces/http-api';
+import { Service, WpResponse } from '@webpieces/http-filters';
+export declare class ExpressWrapper {
+    private service;
+    private routeMeta;
+    private jsonSerializer;
+    constructor(service: Service<MethodMeta, WpResponse<unknown>>, routeMeta: RouteMetadata);
+    execute(req: Request, res: Response, next: NextFunction): Promise<void>;
+    /**
+     * Handle errors - translate to JSON ProtocolError.
+     * PUBLIC so wrapExpress can call it for symmetric error handling.
+     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.
+     */
+    handleError(res: Response, error: unknown): void;
+}
+/**
+ * WebpiecesMiddleware - Express middleware for WebPieces server.
+ *
+ * This class contains all Express middleware used by WebpiecesServer:
+ * 1. globalErrorHandler - Outermost error handler, returns HTML 500 page
+ * 2. logNextLayer - Request/response logging
+ * 3. jsonTranslator - JSON Content-Type validation and error translation
+ *
+ * The middleware is injected into WebpiecesServerImpl and registered with Express
+ * in the start() method.
+ *
+ * IMPORTANT: jsonTranslator does NOT dispatch routes - route dispatch happens via
+ * Express's registered route handlers (created by RouteBuilder.createHandler()).
+ * jsonTranslator only validates Content-Type and translates errors to JSON.
+ *
+ * DI Pattern: This class is registered via @provideSingleton() with no dependencies.
+ */
+export declare class WebpiecesMiddleware {
+    /**
+     * Global error handler middleware - catches ALL unhandled errors.
+     * Returns HTML 500 error page for any errors that escape the filter chain.
+     *
+     * This is the outermost safety net - JsonTranslator catches JSON API errors,
+     * this catches everything else.
+     */
+    globalErrorHandler(req: Request, res: Response, next: NextFunction): Promise<void>;
+    /**
+     * Logging middleware - logs request/response flow.
+     * Demonstrates middleware execution order.
+     * IMPORTANT: Must be async and await next() to properly chain with async middleware.
+     */
+    logNextLayer(req: Request, res: Response, next: NextFunction): Promise<void>;
+    /**
+     * Create an ExpressWrapper for a route.
+     * The wrapper handles the full request/response cycle (symmetric design).
+     *
+     * @param service - The service wrapping the filter chain and controller
+     * @param routeMeta - Route metadata for MethodMeta and DTO type
+     * @returns ExpressWrapper instance
+     */
+    createExpressWrapper(service: Service<MethodMeta, WpResponse<unknown>>, routeMeta: RouteMetadata): ExpressWrapper;
+}

package/src/WebpiecesMiddleware.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebpiecesMiddleware = exports.ExpressWrapper = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const http_routing_1 = require("@webpieces/http-routing");
+const http_api_1 = require("@webpieces/http-api");
+const core_util_1 = require("@webpieces/core-util");
+const typescript_json_serializer_1 = require("typescript-json-serializer");
+class ExpressWrapper {
+    constructor(service, routeMeta) {
+        this.service = service;
+        this.routeMeta = routeMeta;
+        this.jsonSerializer = new typescript_json_serializer_1.JsonSerializer();
+    }
+    async execute(req, res, next) {
+        try {
+            // 1. Get request DTO class from routeMeta
+            const requestDtoClass = this.routeMeta.parameterTypes?.[0];
+            if (!requestDtoClass)
+                throw new Error('No request DTO class found for route');
+            // 2. Deserialize req.body → DTO instance
+            const requestDto = this.jsonSerializer.deserializeObject(req.body, requestDtoClass);
+            // 3. Create MethodMeta with deserialized DTO
+            const methodMeta = new http_routing_1.MethodMeta(this.routeMeta, requestDto);
+            // 4. Invoke the service (filter chain + controller)
+            const wpResponse = await this.service.invoke(methodMeta);
+            if (!wpResponse.response)
+                throw new Error(`Route chain(filters & all) is not returning a response.  ${this.routeMeta.controllerClassName}.${this.routeMeta.methodName}`);
+            // 6. Serialize response → plain object
+            const responseDtoStr = this.jsonSerializer.serializeObject(wpResponse.response);
+            // 7. WRITE response as JSON (SYMMETRIC with reading request!)
+            res.status(200);
+            res.setHeader('Content-Type', 'application/json');
+            res.json(responseDtoStr);
+        }
+        catch (err) {
+            // 8. Handle errors (SYMMETRIC - wrapExpress owns error handling!)
+            this.handleError(res, err);
+        }
+    }
+    /**
+     * Handle errors - translate to JSON ProtocolError.
+     * PUBLIC so wrapExpress can call it for symmetric error handling.
+     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.
+     */
+    handleError(res, error) {
+        if (res.headersSent) {
+            return;
+        }
+        const protocolError = new http_api_1.ProtocolError();
+        if (error instanceof http_api_1.HttpError) {
+            protocolError.message = error.message;
+            protocolError.subType = error.subType;
+            protocolError.name = error.name;
+            if (error instanceof http_api_1.HttpBadRequestError) {
+                protocolError.field = error.field;
+                protocolError.guiAlertMessage = error.guiMessage;
+            }
+            if (error instanceof http_api_1.HttpVendorError) {
+                protocolError.waitSeconds = error.waitSeconds;
+            }
+            if (error instanceof http_api_1.HttpUserError) {
+                protocolError.errorCode = error.errorCode;
+            }
+            res.status(error.code).json(protocolError);
+        }
+        else {
+            // Unknown error - 500
+            const err = (0, core_util_1.toError)(error);
+            protocolError.message = 'Internal Server Error';
+            console.error('[JsonTranslator] Unexpected error:', err);
+            res.status(500).json(protocolError);
+        }
+    }
+}
+exports.ExpressWrapper = ExpressWrapper;
+/**
+ * WebpiecesMiddleware - Express middleware for WebPieces server.
+ *
+ * This class contains all Express middleware used by WebpiecesServer:
+ * 1. globalErrorHandler - Outermost error handler, returns HTML 500 page
+ * 2. logNextLayer - Request/response logging
+ * 3. jsonTranslator - JSON Content-Type validation and error translation
+ *
+ * The middleware is injected into WebpiecesServerImpl and registered with Express
+ * in the start() method.
+ *
+ * IMPORTANT: jsonTranslator does NOT dispatch routes - route dispatch happens via
+ * Express's registered route handlers (created by RouteBuilder.createHandler()).
+ * jsonTranslator only validates Content-Type and translates errors to JSON.
+ *
+ * DI Pattern: This class is registered via @provideSingleton() with no dependencies.
+ */
+let WebpiecesMiddleware = class WebpiecesMiddleware {
+    /**
+     * Global error handler middleware - catches ALL unhandled errors.
+     * Returns HTML 500 error page for any errors that escape the filter chain.
+     *
+     * This is the outermost safety net - JsonTranslator catches JSON API errors,
+     * this catches everything else.
+     */
+    async globalErrorHandler(req, res, next) {
+        console.log('🔴 [Layer 1: GlobalErrorHandler] Request START:', req.method, req.path);
+        try {
+            // await next() catches BOTH:
+            // 1. Synchronous throws from next() itself
+            // 2. Rejected promises from downstream async middleware
+            await next();
+            console.log('🔴 [Layer 1: GlobalErrorHandler] Request END (success):', req.method, req.path);
+        }
+        catch (err) {
+            const error = (0, core_util_1.toError)(err);
+            console.error('🔴 [Layer 1: GlobalErrorHandler] Caught unhandled error:', error);
+            if (!res.headersSent) {
+                // Return HTML error page (not JSON - JsonTranslator handles JSON errors)
+                res.status(500).send(`
+          <!DOCTYPE html>
+          <html>
+          <head><title>Server Error</title></head>
+          <body>
+            <h1>You hit a server error</h1>
+            <p>An unexpected error occurred while processing your request.</p>
+            <pre>${error.message}</pre>
+          </body>
+          </html>
+        `);
+            }
+            console.log('🔴 [Layer 1: GlobalErrorHandler] Request END (error):', req.method, req.path);
+        }
+    }
+    /**
+     * Logging middleware - logs request/response flow.
+     * Demonstrates middleware execution order.
+     * IMPORTANT: Must be async and await next() to properly chain with async middleware.
+     */
+    async logNextLayer(req, res, next) {
+        console.log('🟡 [Layer 2: LogNextLayer] Before next() -', req.method, req.path);
+        await next();
+        console.log('🟡 [Layer 2: LogNextLayer] After next() -', req.method, req.path);
+    }
+    /**
+     * Create an ExpressWrapper for a route.
+     * The wrapper handles the full request/response cycle (symmetric design).
+     *
+     * @param service - The service wrapping the filter chain and controller
+     * @param routeMeta - Route metadata for MethodMeta and DTO type
+     * @returns ExpressWrapper instance
+     */
+    createExpressWrapper(service, routeMeta) {
+        return new ExpressWrapper(service, routeMeta);
+    }
+};
+exports.WebpiecesMiddleware = WebpiecesMiddleware;
+exports.WebpiecesMiddleware = WebpiecesMiddleware = tslib_1.__decorate([
+    (0, http_routing_1.provideSingleton)(),
+    (0, inversify_1.injectable)()
+], WebpiecesMiddleware);
+//# sourceMappingURL=WebpiecesMiddleware.js.map

package/src/WebpiecesMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebpiecesMiddleware.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesMiddleware.ts"],"names":[],"mappings":"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","sourcesContent":["import { Request, Response, NextFunction } from 'express';\nimport { injectable } from 'inversify';\nimport { provideSingleton, MethodMeta, ExpressRouteHandler } from '@webpieces/http-routing';\nimport {\n    ProtocolError,\n    HttpError,\n    HttpBadRequestError,\n    HttpVendorError,\n    HttpUserError,\n    RouteMetadata,\n} from '@webpieces/http-api';\nimport { Service, WpResponse } from '@webpieces/http-filters';\nimport { toError } from '@webpieces/core-util';\nimport { JsonSerializer } from 'typescript-json-serializer';\n\nexport class ExpressWrapper {\n    private jsonSerializer = new JsonSerializer();\n\n    constructor(\n        private service: Service<MethodMeta, WpResponse<unknown>>,\n        private routeMeta: RouteMetadata\n    ) {\n    }\n\n    public async execute(req: Request, res: Response, next: NextFunction) {\n        try {\n            // 1. Get request DTO class from routeMeta\n            const requestDtoClass = this.routeMeta.parameterTypes?.[0];\n            if(!requestDtoClass)\n                throw new Error('No request DTO class found for route');\n\n            // 2. Deserialize req.body → DTO instance\n            const requestDto = this.jsonSerializer.deserializeObject(req.body, requestDtoClass);\n            // 3. Create MethodMeta with deserialized DTO\n            const methodMeta = new MethodMeta(this.routeMeta, requestDto);\n            // 4. Invoke the service (filter chain + controller)\n            const wpResponse = await this.service.invoke(methodMeta);\n            if(!wpResponse.response)\n                throw new Error(`Route chain(filters & all) is not returning a response.  ${this.routeMeta.controllerClassName}.${this.routeMeta.methodName}`);\n\n            // 6. Serialize response → plain object\n            const responseDtoStr = this.jsonSerializer.serializeObject(wpResponse.response);\n\n            // 7. WRITE response as JSON (SYMMETRIC with reading request!)\n            res.status(200);\n            res.setHeader('Content-Type', 'application/json');\n            res.json(responseDtoStr);\n        } catch (err: unknown) {\n            // 8. Handle errors (SYMMETRIC - wrapExpress owns error handling!)\n            this.handleError(res, err);\n        }\n    }\n\n    /**\n     * Handle errors - translate to JSON ProtocolError.\n     * PUBLIC so wrapExpress can call it for symmetric error handling.\n     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.\n     */\n    public handleError(res: Response, error: unknown): void {\n        if (res.headersSent) {\n            return;\n        }\n\n        const protocolError = new ProtocolError();\n\n        if (error instanceof HttpError) {\n            protocolError.message = error.message;\n            protocolError.subType = error.subType;\n            protocolError.name = error.name;\n\n            if (error instanceof HttpBadRequestError) {\n                protocolError.field = error.field;\n                protocolError.guiAlertMessage = error.guiMessage;\n            }\n            if (error instanceof HttpVendorError) {\n                protocolError.waitSeconds = error.waitSeconds;\n            }\n            if (error instanceof HttpUserError) {\n                protocolError.errorCode = error.errorCode;\n            }\n\n            res.status(error.code).json(protocolError);\n        } else {\n            // Unknown error - 500\n            const err = toError(error);\n            protocolError.message = 'Internal Server Error';\n            console.error('[JsonTranslator] Unexpected error:', err);\n            res.status(500).json(protocolError);\n        }\n    }\n}\n/**\n * WebpiecesMiddleware - Express middleware for WebPieces server.\n *\n * This class contains all Express middleware used by WebpiecesServer:\n * 1. globalErrorHandler - Outermost error handler, returns HTML 500 page\n * 2. logNextLayer - Request/response logging\n * 3. jsonTranslator - JSON Content-Type validation and error translation\n *\n * The middleware is injected into WebpiecesServerImpl and registered with Express\n * in the start() method.\n *\n * IMPORTANT: jsonTranslator does NOT dispatch routes - route dispatch happens via\n * Express's registered route handlers (created by RouteBuilder.createHandler()).\n * jsonTranslator only validates Content-Type and translates errors to JSON.\n *\n * DI Pattern: This class is registered via @provideSingleton() with no dependencies.\n */\n@provideSingleton()\n@injectable()\nexport class WebpiecesMiddleware {\n\n    /**\n     * Global error handler middleware - catches ALL unhandled errors.\n     * Returns HTML 500 error page for any errors that escape the filter chain.\n     *\n     * This is the outermost safety net - JsonTranslator catches JSON API errors,\n     * this catches everything else.\n     */\n    async globalErrorHandler(\n        req: Request,\n        res: Response,\n        next: NextFunction,\n    ): Promise<void> {\n        console.log('🔴 [Layer 1: GlobalErrorHandler] Request START:', req.method, req.path);\n\n        try {\n            // await next() catches BOTH:\n            // 1. Synchronous throws from next() itself\n            // 2. Rejected promises from downstream async middleware\n            await next();\n            console.log(\n                '🔴 [Layer 1: GlobalErrorHandler] Request END (success):',\n                req.method,\n                req.path,\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            console.error('🔴 [Layer 1: GlobalErrorHandler] Caught unhandled error:', error);\n            if (!res.headersSent) {\n                // Return HTML error page (not JSON - JsonTranslator handles JSON errors)\n                res.status(500).send(`\n          <!DOCTYPE html>\n          <html>\n          <head><title>Server Error</title></head>\n          <body>\n            <h1>You hit a server error</h1>\n            <p>An unexpected error occurred while processing your request.</p>\n            <pre>${error.message}</pre>\n          </body>\n          </html>\n        `);\n            }\n            console.log(\n                '🔴 [Layer 1: GlobalErrorHandler] Request END (error):',\n                req.method,\n                req.path,\n            );\n        }\n    }\n\n    /**\n     * Logging middleware - logs request/response flow.\n     * Demonstrates middleware execution order.\n     * IMPORTANT: Must be async and await next() to properly chain with async middleware.\n     */\n    async logNextLayer(req: Request, res: Response, next: NextFunction): Promise<void> {\n        console.log('🟡 [Layer 2: LogNextLayer] Before next() -', req.method, req.path);\n        await next();\n        console.log('🟡 [Layer 2: LogNextLayer] After next() -', req.method, req.path);\n    }\n\n    /**\n     * Create an ExpressWrapper for a route.\n     * The wrapper handles the full request/response cycle (symmetric design).\n     *\n     * @param service - The service wrapping the filter chain and controller\n     * @param routeMeta - Route metadata for MethodMeta and DTO type\n     * @returns ExpressWrapper instance\n     */\n    createExpressWrapper(\n        service: Service<MethodMeta, WpResponse<unknown>>,\n        routeMeta: RouteMetadata,\n    ): ExpressWrapper {\n        return new ExpressWrapper(service, routeMeta);\n    }\n}\n"]}

package/src/WebpiecesServer.d.ts

@@ -1,20 +1,26 @@
+import { Container } from 'inversify';
 /**
  * WebpiecesServer - Public interface for WebPieces server.
  *
- * This interface exposes only the methods needed by application code:
+ * This interface exposes the methods needed by application code:
  * - start(): Start the HTTP server
  * - stop(): Stop the HTTP server
+ * - createApiClient(): Create API client proxy for testing (no HTTP!)
+ * - getContainer(): Access DI container for verification
  *
  * The initialization logic is hidden inside WebpiecesFactory.create().
  * This provides a clean API and prevents accidental re-initialization.
  *
  * Usage:
  * ```typescript
+ * // Production
  * const server = WebpiecesFactory.create(new ProdServerMeta());
  * await server.start(8080);
- * console.log('Server is now listening!');
- * // ... later
- * server.stop();
+ *
+ * // Testing (no HTTP needed!)
+ * const server = WebpiecesFactory.create(new ProdServerMeta(), overrides);
+ * const api = server.createApiClient(SaveApiPrototype);
+ * const response = await api.save(request);
  * ```
  */
 export interface WebpiecesServer {
@@ -29,6 +35,37 @@ export interface WebpiecesServer {
     start(port?: number): Promise<void>;
     /**
      * Stop the HTTP server.
+     * Returns a Promise that resolves when the server is stopped,
+     * or rejects if there's an error stopping the server.
+     *
+     * @returns Promise that resolves when server is stopped
+     */
+    stop(): Promise<void>;
+    /**
+     * Create an API client proxy for testing.
+     *
+     * This creates a client that routes calls through the full filter chain
+     * and controller, but WITHOUT any HTTP overhead. Perfect for testing!
+     *
+     * The client uses the ApiPrototype class to discover routes via decorators,
+     * then invokes the corresponding controller method through the filter chain.
+     *
+     * @param apiPrototype - The API prototype class with routing decorators (can be abstract)
+     * @returns A proxy that implements the API interface
+     *
+     * Example:
+     * ```typescript
+     * const saveApi = server.createApiClient<SaveApi>(SaveApiPrototype);
+     * const response = await saveApi.save(request);
+     * ```
+     */
+    createApiClient<T>(apiPrototype: abstract new (...args: any[]) => T): T;
+    /**
+     * Get the application DI container.
+     *
+     * Useful for testing to verify state or access services directly.
+     *
+     * @returns The application Container
      */
-    stop(): void;
+    getContainer(): Container;
 }

package/src/WebpiecesServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesServer.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesServer.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * WebpiecesServer - Public interface for WebPieces server.\n *\n * This interface exposes only the methods needed by application code:\n * - start(): Start the HTTP server\n * - stop(): Stop the HTTP server\n *\n * The initialization logic is hidden inside WebpiecesFactory.create().\n * This provides a clean API and prevents accidental re-initialization.\n *\n * Usage:\n * ```typescript\n * const server = WebpiecesFactory.create(new ProdServerMeta());\n * await server.start(8080);\n * console.log('Server is now listening!');\n * // ... later\n * server.stop();\n * ```\n */\nexport interface WebpiecesServer {\n  /**\n   * Start the HTTP server with Express.\n   * Returns a Promise that resolves when the server is listening,\n   * or rejects if the server fails to start.\n   *\n   * @param port - The port to listen on (default: 8080)\n   * @returns Promise that resolves when server is ready\n   */\n  start(port?: number): Promise<void>;\n\n  /**\n   * Stop the HTTP server.\n   */\n  stop(): void;\n}\n"]}
+{"version":3,"file":"WebpiecesServer.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesServer.ts"],"names":[],"mappings":"","sourcesContent":["import { Container } from 'inversify';\n\n/**\n * WebpiecesServer - Public interface for WebPieces server.\n *\n * This interface exposes the methods needed by application code:\n * - start(): Start the HTTP server\n * - stop(): Stop the HTTP server\n * - createApiClient(): Create API client proxy for testing (no HTTP!)\n * - getContainer(): Access DI container for verification\n *\n * The initialization logic is hidden inside WebpiecesFactory.create().\n * This provides a clean API and prevents accidental re-initialization.\n *\n * Usage:\n * ```typescript\n * // Production\n * const server = WebpiecesFactory.create(new ProdServerMeta());\n * await server.start(8080);\n *\n * // Testing (no HTTP needed!)\n * const server = WebpiecesFactory.create(new ProdServerMeta(), overrides);\n * const api = server.createApiClient(SaveApiPrototype);\n * const response = await api.save(request);\n * ```\n */\nexport interface WebpiecesServer {\n    /**\n     * Start the HTTP server with Express.\n     * Returns a Promise that resolves when the server is listening,\n     * or rejects if the server fails to start.\n     *\n     * @param port - The port to listen on (default: 8080)\n     * @returns Promise that resolves when server is ready\n     */\n    start(port?: number): Promise<void>;\n\n    /**\n     * Stop the HTTP server.\n     * Returns a Promise that resolves when the server is stopped,\n     * or rejects if there's an error stopping the server.\n     *\n     * @returns Promise that resolves when server is stopped\n     */\n    stop(): Promise<void>;\n\n    /**\n     * Create an API client proxy for testing.\n     *\n     * This creates a client that routes calls through the full filter chain\n     * and controller, but WITHOUT any HTTP overhead. Perfect for testing!\n     *\n     * The client uses the ApiPrototype class to discover routes via decorators,\n     * then invokes the corresponding controller method through the filter chain.\n     *\n     * @param apiPrototype - The API prototype class with routing decorators (can be abstract)\n     * @returns A proxy that implements the API interface\n     *\n     * Example:\n     * ```typescript\n     * const saveApi = server.createApiClient<SaveApi>(SaveApiPrototype);\n     * const response = await saveApi.save(request);\n     * ```\n     */\n    createApiClient<T>(apiPrototype: abstract new (...args: any[]) => T): T;\n\n    /**\n     * Get the application DI container.\n     *\n     * Useful for testing to verify state or access services directly.\n     *\n     * @returns The application Container\n     */\n    getContainer(): Container;\n}\n"]}

package/src/WebpiecesServerImpl.d.ts

@@ -1,7 +1,7 @@
-import { Container } from 'inversify';
-import { WebAppMeta } from '@webpieces/core-meta';
-import { RouteBuilderImpl } from './RouteBuilderImpl';
+import { Container, ContainerModule } from 'inversify';
+import { ExpressRouteHandler, RouteBuilderImpl, WebAppMeta } from '@webpieces/http-routing';
 import { WebpiecesServer } from './WebpiecesServer';
+import { WebpiecesMiddleware } from './WebpiecesMiddleware';
 /**
  * WebpiecesServerImpl - Internal server implementation.
  *
@@ -28,6 +28,7 @@ import { WebpiecesServer } from './WebpiecesServer';
  */
 export declare class WebpiecesServerImpl implements WebpiecesServer {
     private routeBuilder;
+    private middleware;
     private meta;
     private webpiecesContainer;
     /**
@@ -40,7 +41,7 @@ export declare class WebpiecesServerImpl implements WebpiecesServer {
     private app?;
     private server?;
     private port;
-    constructor(routeBuilder: RouteBuilderImpl);
+    constructor(routeBuilder: RouteBuilderImpl, middleware: WebpiecesMiddleware);
     /**
      * Initialize the server (DI container, routes, filters).
      * This is called by WebpiecesFactory.create() after resolving this class from DI.
@@ -48,8 +49,17 @@ export declare class WebpiecesServerImpl implements WebpiecesServer {
      *
      * @param webpiecesContainer - The framework container
      * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @param overrides - Optional ContainerModule for test overrides (loaded LAST)
      */
-    initialize(webpiecesContainer: Container, meta: WebAppMeta): void;
+    /**
+     * Initialize the server asynchronously.
+     * Use this when overrides module contains async operations (e.g., rebind() in new Inversify).
+     *
+     * @param webpiecesContainer - The framework container
+     * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @param overrides - Optional ContainerModule for test overrides (loaded LAST)
+     */
+    initialize(webpiecesContainer: Container, meta: WebAppMeta, overrides?: ContainerModule): Promise<void>;
     /**
      * Load DI modules from WebAppMeta.
      *
@@ -59,6 +69,8 @@ export declare class WebpiecesServerImpl implements WebpiecesServer {
      * - Application modules -> appContainer
      *
      * For now, everything goes into appContainer which has access to webpiecesContainer.
+     *
+     * @param overrides - Optional ContainerModule for test overrides (loaded LAST to override bindings)
      */
     private loadDIModules;
     /**
@@ -71,19 +83,6 @@ export declare class WebpiecesServerImpl implements WebpiecesServer {
      * - Understanding: Clear class name vs anonymous object
      */
     private registerRoutes;
-    /**
-     * Global error handler middleware - catches ALL unhandled errors.
-     * Returns HTML 500 error page for any errors that escape the filter chain.
-     *
-     * This is the outermost safety net - JsonFilter catches JSON API errors,
-     * this catches everything else.
-     */
-    private globalErrorHandler;
-    /**
-     * Logging middleware - logs request/response flow.
-     * Demonstrates middleware execution order.
-     */
-    private logNextLayer;
     /**
      * Start the HTTP server with Express.
      * Returns a Promise that resolves when the server is listening,
@@ -92,22 +91,52 @@ export declare class WebpiecesServerImpl implements WebpiecesServer {
      * @param port - The port to listen on (default: 8080)
      * @returns Promise that resolves when server is ready
      */
-    start(port?: number): Promise<void>;
+    start(port?: number, testMode?: boolean): Promise<void>;
     /**
-     * Register all routes with Express.
+     * Register Express routes - the SINGLE loop over routes.
+     * For each route: createHandler (sets up filter chain) → wrapExpress → registerHandler.
+     *
+     * @returns Number of routes registered
      */
     private registerExpressRoutes;
+    registerHandler(httpMethod: string, path: string, expressHandler: ExpressRouteHandler): void;
     /**
-     * Setup a single route with Express.
-     * Finds matching filters, creates handler, and registers with Express.
+     * Stop the HTTP server.
+     * Returns a Promise that resolves when the server is stopped,
+     * or rejects if there's an error stopping the server.
      *
-     * @param key - Route key (method:path)
-     * @param routeWithMeta - The route handler paired with its definition
-     * @param filtersWithMeta - All filters with their definitions
+     * @returns Promise that resolves when server is stopped
      */
-    private setupRoute;
+    stop(): Promise<void>;
     /**
-     * Stop the HTTP server.
+     * Get the application DI container.
+     *
+     * Useful for testing to verify state or access services directly.
+     *
+     * @returns The application Container
+     */
+    getContainer(): Container;
+    /**
+     * Create an API client proxy for testing.
+     *
+     * This creates a client that routes calls through the full filter chain
+     * and controller, but WITHOUT any HTTP overhead. Perfect for testing!
+     *
+     * The client uses the ApiPrototype class to discover routes via decorators,
+     * then creates pre-configured invoker functions for each API method.
+     *
+     * IMPORTANT: This loops over the API methods (from decorators), NOT all routes.
+     * For each API method, it sets up the filter chain ONCE during proxy creation,
+     * so subsequent calls reuse the same filter chain (efficient!).
+     *
+     * @param apiPrototype - The API prototype class with routing decorators (can be abstract)
+     * @returns A proxy that implements the API interface
+     *
+     * Example:
+     * ```typescript
+     * const saveApi = server.createApiClient<SaveApi>(SaveApiPrototype);
+     * const response = await saveApi.save(request);
+     * ```
      */
-    stop(): void;
+    createApiClient<T>(apiPrototype: abstract new (...args: any[]) => T): T;
 }