@webpieces/http-server 0.2.15 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-server",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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.15",
-    "@webpieces/core-util": "0.2.15",
-    "@webpieces/http-routing": "0.2.15",
-    "@webpieces/http-filters": "0.2.15"
+    "@webpieces/core-util": "0.2.17",
+    "@webpieces/http-routing": "0.2.17",
+    "@webpieces/http-filters": "0.2.17"
   }
 }

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;IACzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,IAAgB;QAC1B,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;IACtB,CAAC;CACJ;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,75 @@
+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;
+    constructor(service: Service<MethodMeta, WpResponse<unknown>>, routeMeta: RouteMetadata);
+    execute(req: Request, res: Response, next: NextFunction): Promise<void>;
+    /**
+     * Read raw request body as text.
+     * Used to manually parse JSON (instead of express.json() middleware).
+     */
+    private readRequestBody;
+    /**
+     * Handle errors - translate to JSON ProtocolError (SYMMETRIC with ClientErrorTranslator).
+     * PUBLIC so wrapExpress can call it for symmetric error handling.
+     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.
+     *
+     * Maps all HttpError types (must match ClientErrorTranslator.translateError()):
+     * - HttpUserError → 266 (with errorCode)
+     * - HttpBadRequestError → 400 (with field, guiAlertMessage)
+     * - HttpUnauthorizedError → 401
+     * - HttpForbiddenError → 403
+     * - HttpNotFoundError → 404
+     * - HttpTimeoutError → 408
+     * - HttpInternalServerError → 500
+     * - HttpBadGatewayError → 502
+     * - HttpGatewayTimeoutError → 504
+     * - HttpVendorError → 598 (with waitSeconds)
+     */
+    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,218 @@
+"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");
+class ExpressWrapper {
+    constructor(service, routeMeta) {
+        this.service = service;
+        this.routeMeta = routeMeta;
+    }
+    async execute(req, res, next) {
+        try {
+            // 1. Parse JSON request body manually (SYMMETRIC with client's JSON.stringify)
+            let requestDto = {};
+            if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+                // Read raw body as text
+                const bodyText = await this.readRequestBody(req);
+                // Parse JSON
+                requestDto = bodyText ? JSON.parse(bodyText) : {};
+            }
+            // 2. Create MethodMeta with request DTO
+            const methodMeta = new http_routing_1.MethodMeta(this.routeMeta, requestDto);
+            // 3. 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}`);
+            // 4. Serialize response DTO to JSON (SYMMETRIC with client's response.json())
+            const responseJson = JSON.stringify(wpResponse.response);
+            res.status(200).setHeader('Content-Type', 'application/json').send(responseJson);
+        }
+        catch (err) {
+            // 5. Handle errors
+            this.handleError(res, err);
+        }
+    }
+    /**
+     * Read raw request body as text.
+     * Used to manually parse JSON (instead of express.json() middleware).
+     */
+    async readRequestBody(req) {
+        return new Promise((resolve, reject) => {
+            let body = '';
+            req.on('data', (chunk) => {
+                body += chunk.toString();
+            });
+            req.on('end', () => {
+                resolve(body);
+            });
+            req.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Handle errors - translate to JSON ProtocolError (SYMMETRIC with ClientErrorTranslator).
+     * PUBLIC so wrapExpress can call it for symmetric error handling.
+     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.
+     *
+     * Maps all HttpError types (must match ClientErrorTranslator.translateError()):
+     * - HttpUserError → 266 (with errorCode)
+     * - HttpBadRequestError → 400 (with field, guiAlertMessage)
+     * - HttpUnauthorizedError → 401
+     * - HttpForbiddenError → 403
+     * - HttpNotFoundError → 404
+     * - HttpTimeoutError → 408
+     * - HttpInternalServerError → 500
+     * - HttpBadGatewayError → 502
+     * - HttpGatewayTimeoutError → 504
+     * - HttpVendorError → 598 (with waitSeconds)
+     */
+    handleError(res, error) {
+        if (res.headersSent) {
+            return;
+        }
+        const protocolError = new http_api_1.ProtocolError();
+        if (error instanceof http_api_1.HttpError) {
+            // Set common fields for all HttpError types
+            protocolError.message = error.message;
+            protocolError.subType = error.subType;
+            protocolError.name = error.name;
+            // Set type-specific fields (MUST match ClientErrorTranslator)
+            if (error instanceof http_api_1.HttpUserError) {
+                console.log('[ExpressWrapper] User Error:', error.message);
+                protocolError.errorCode = error.errorCode;
+            }
+            else if (error instanceof http_api_1.HttpBadRequestError) {
+                console.log('[ExpressWrapper] Bad Request:', error.message);
+                protocolError.field = error.field;
+                protocolError.guiAlertMessage = error.guiMessage;
+            }
+            else if (error instanceof http_api_1.HttpNotFoundError) {
+                console.log('[ExpressWrapper] Not Found:', error.message);
+            }
+            else if (error instanceof http_api_1.HttpTimeoutError) {
+                console.error('[ExpressWrapper] Timeout Error:', error.message);
+            }
+            else if (error instanceof http_api_1.HttpVendorError) {
+                console.error('[ExpressWrapper] Vendor Error:', error.message);
+                protocolError.waitSeconds = error.waitSeconds;
+            }
+            else if (error instanceof http_api_1.HttpUnauthorizedError) {
+                console.log('[ExpressWrapper] Unauthorized:', error.message);
+            }
+            else if (error instanceof http_api_1.HttpForbiddenError) {
+                console.log('[ExpressWrapper] Forbidden:', error.message);
+            }
+            else if (error instanceof http_api_1.HttpInternalServerError) {
+                console.error('[ExpressWrapper] Internal Server Error:', error.message);
+            }
+            else if (error instanceof http_api_1.HttpBadGatewayError) {
+                console.error('[ExpressWrapper] Bad Gateway:', error.message);
+            }
+            else if (error instanceof http_api_1.HttpGatewayTimeoutError) {
+                console.error('[ExpressWrapper] Gateway Timeout:', error.message);
+            }
+            else {
+                console.log('[ExpressWrapper] Generic HttpError:', error.message);
+            }
+            // Serialize ProtocolError to JSON (SYMMETRIC with client)
+            const responseJson = JSON.stringify(protocolError);
+            res.status(error.code).setHeader('Content-Type', 'application/json').send(responseJson);
+        }
+        else {
+            // Unknown error - 500
+            const err = (0, core_util_1.toError)(error);
+            protocolError.message = 'Internal Server Error';
+            console.error('[ExpressWrapper] Unexpected error:', err);
+            const responseJson = JSON.stringify(protocolError);
+            res.status(500).setHeader('Content-Type', 'application/json').send(responseJson);
+        }
+    }
+}
+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    HttpNotFoundError,\n    HttpTimeoutError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpInternalServerError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    RouteMetadata,\n} from '@webpieces/http-api';\nimport { Service, WpResponse } from '@webpieces/http-filters';\nimport { toError } from '@webpieces/core-util';\n\nexport class ExpressWrapper {\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. Parse JSON request body manually (SYMMETRIC with client's JSON.stringify)\n            let requestDto: unknown = {};\n            if (['POST', 'PUT', 'PATCH'].includes(req.method)) {\n                // Read raw body as text\n                const bodyText = await this.readRequestBody(req);\n                // Parse JSON\n                requestDto = bodyText ? JSON.parse(bodyText) : {};\n            }\n\n            // 2. Create MethodMeta with request DTO\n            const methodMeta = new MethodMeta(this.routeMeta, requestDto);\n\n            // 3. 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            // 4. Serialize response DTO to JSON (SYMMETRIC with client's response.json())\n            const responseJson = JSON.stringify(wpResponse.response);\n            res.status(200).setHeader('Content-Type', 'application/json').send(responseJson);\n        } catch (err: unknown) {\n            // 5. Handle errors\n            this.handleError(res, err);\n        }\n    }\n\n    /**\n     * Read raw request body as text.\n     * Used to manually parse JSON (instead of express.json() middleware).\n     */\n    private async readRequestBody(req: Request): Promise<string> {\n        return new Promise((resolve, reject) => {\n            let body = '';\n            req.on('data', (chunk) => {\n                body += chunk.toString();\n            });\n            req.on('end', () => {\n                resolve(body);\n            });\n            req.on('error', (err) => {\n                reject(err);\n            });\n        });\n    }\n\n    /**\n     * Handle errors - translate to JSON ProtocolError (SYMMETRIC with ClientErrorTranslator).\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     * Maps all HttpError types (must match ClientErrorTranslator.translateError()):\n     * - HttpUserError → 266 (with errorCode)\n     * - HttpBadRequestError → 400 (with field, guiAlertMessage)\n     * - HttpUnauthorizedError → 401\n     * - HttpForbiddenError → 403\n     * - HttpNotFoundError → 404\n     * - HttpTimeoutError → 408\n     * - HttpInternalServerError → 500\n     * - HttpBadGatewayError → 502\n     * - HttpGatewayTimeoutError → 504\n     * - HttpVendorError → 598 (with waitSeconds)\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            // Set common fields for all HttpError types\n            protocolError.message = error.message;\n            protocolError.subType = error.subType;\n            protocolError.name = error.name;\n\n            // Set type-specific fields (MUST match ClientErrorTranslator)\n            if (error instanceof HttpUserError) {\n                console.log('[ExpressWrapper] User Error:', error.message);\n                protocolError.errorCode = error.errorCode;\n            } else if (error instanceof HttpBadRequestError) {\n                console.log('[ExpressWrapper] Bad Request:', error.message);\n                protocolError.field = error.field;\n                protocolError.guiAlertMessage = error.guiMessage;\n            } else if (error instanceof HttpNotFoundError) {\n                console.log('[ExpressWrapper] Not Found:', error.message);\n            } else if (error instanceof HttpTimeoutError) {\n                console.error('[ExpressWrapper] Timeout Error:', error.message);\n            } else if (error instanceof HttpVendorError) {\n                console.error('[ExpressWrapper] Vendor Error:', error.message);\n                protocolError.waitSeconds = error.waitSeconds;\n            } else if (error instanceof HttpUnauthorizedError) {\n                console.log('[ExpressWrapper] Unauthorized:', error.message);\n            } else if (error instanceof HttpForbiddenError) {\n                console.log('[ExpressWrapper] Forbidden:', error.message);\n            } else if (error instanceof HttpInternalServerError) {\n                console.error('[ExpressWrapper] Internal Server Error:', error.message);\n            } else if (error instanceof HttpBadGatewayError) {\n                console.error('[ExpressWrapper] Bad Gateway:', error.message);\n            } else if (error instanceof HttpGatewayTimeoutError) {\n                console.error('[ExpressWrapper] Gateway Timeout:', error.message);\n            } else {\n                console.log('[ExpressWrapper] Generic HttpError:', error.message);\n            }\n\n            // Serialize ProtocolError to JSON (SYMMETRIC with client)\n            const responseJson = JSON.stringify(protocolError);\n            res.status(error.code).setHeader('Content-Type', 'application/json').send(responseJson);\n        } else {\n            // Unknown error - 500\n            const err = toError(error);\n            protocolError.message = 'Internal Server Error';\n            console.error('[ExpressWrapper] Unexpected error:', err);\n            const responseJson = JSON.stringify(protocolError);\n            res.status(500).setHeader('Content-Type', 'application/json').send(responseJson);\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"]}