@webpieces/http-server 0.2.13 → 0.2.14

package/package.json

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

package/src/MethodMeta.d.ts

@@ -3,7 +3,7 @@ import { RouteMetadata2, RouteRequest } from '@webpieces/core-meta';
  * Metadata about the method being invoked.
  * Passed to filters and contains request information.
  *
- * MethodMeta is created by WebpiecesCoreServer when handling a request:
+ * MethodMeta is created by WebpiecesServerImpl when handling a request:
  * - routeMeta: Static route information (httpMethod, path, methodName)
  * - routeRequest: Express Request/Response objects
  * - requestDto: Set by JsonFilter after deserializing the request body

package/src/MethodMeta.js

@@ -5,7 +5,7 @@ exports.MethodMeta = void 0;
  * Metadata about the method being invoked.
  * Passed to filters and contains request information.
  *
- * MethodMeta is created by WebpiecesCoreServer when handling a request:
+ * MethodMeta is created by WebpiecesServerImpl when handling a request:
  * - routeMeta: Static route information (httpMethod, path, methodName)
  * - routeRequest: Express Request/Response objects
  * - requestDto: Set by JsonFilter after deserializing the request body

package/src/MethodMeta.js.map

@@ -1 +1 @@
-{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACH,MAAa,UAAU;IAsBrB,YACE,SAAyB,EACzB,YAA0B,EAC1B,UAAoB,EACpB,QAA+B;QAE/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACnC,CAAC;CACF;AAtDD,gCAsDC","sourcesContent":["import { RouteMetadata2, RouteRequest } from '@webpieces/core-meta';\n\n/**\n * Metadata about the method being invoked.\n * Passed to filters and contains request information.\n *\n * MethodMeta is created by WebpiecesCoreServer when handling a request:\n * - routeMeta: Static route information (httpMethod, path, methodName)\n * - routeRequest: Express Request/Response objects\n * - requestDto: Set by JsonFilter after deserializing the request body\n */\nexport class MethodMeta {\n  /**\n   * Route metadata (httpMethod, path, methodName, parameterTypes)\n   */\n  routeMeta: RouteMetadata2;\n\n  /**\n   * Express Request and Response objects\n   */\n  routeRequest: RouteRequest;\n\n  /**\n   * The deserialized request DTO.\n   * Set by JsonFilter after deserializing the request body.\n   */\n  requestDto?: unknown;\n\n  /**\n   * Additional metadata for storing request-scoped data.\n   */\n  metadata: Map<string, unknown>;\n\n  constructor(\n    routeMeta: RouteMetadata2,\n    routeRequest: RouteRequest,\n    requestDto?: unknown,\n    metadata?: Map<string, unknown>\n  ) {\n    this.routeMeta = routeMeta;\n    this.routeRequest = routeRequest;\n    this.requestDto = requestDto;\n    this.metadata = metadata ?? new Map();\n  }\n\n  /**\n   * Get the HTTP method (convenience accessor).\n   */\n  get httpMethod(): string {\n    return this.routeMeta.httpMethod;\n  }\n\n  /**\n   * Get the request path (convenience accessor).\n   */\n  get path(): string {\n    return this.routeMeta.path;\n  }\n\n  /**\n   * Get the method name (convenience accessor).\n   */\n  get methodName(): string {\n    return this.routeMeta.methodName;\n  }\n}\n"]}
+{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACH,MAAa,UAAU;IAsBrB,YACE,SAAyB,EACzB,YAA0B,EAC1B,UAAoB,EACpB,QAA+B;QAE/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACnC,CAAC;CACF;AAtDD,gCAsDC","sourcesContent":["import { RouteMetadata2, RouteRequest } from '@webpieces/core-meta';\n\n/**\n * Metadata about the method being invoked.\n * Passed to filters and contains request information.\n *\n * MethodMeta is created by WebpiecesServerImpl when handling a request:\n * - routeMeta: Static route information (httpMethod, path, methodName)\n * - routeRequest: Express Request/Response objects\n * - requestDto: Set by JsonFilter after deserializing the request body\n */\nexport class MethodMeta {\n  /**\n   * Route metadata (httpMethod, path, methodName, parameterTypes)\n   */\n  routeMeta: RouteMetadata2;\n\n  /**\n   * Express Request and Response objects\n   */\n  routeRequest: RouteRequest;\n\n  /**\n   * The deserialized request DTO.\n   * Set by JsonFilter after deserializing the request body.\n   */\n  requestDto?: unknown;\n\n  /**\n   * Additional metadata for storing request-scoped data.\n   */\n  metadata: Map<string, unknown>;\n\n  constructor(\n    routeMeta: RouteMetadata2,\n    routeRequest: RouteRequest,\n    requestDto?: unknown,\n    metadata?: Map<string, unknown>\n  ) {\n    this.routeMeta = routeMeta;\n    this.routeRequest = routeRequest;\n    this.requestDto = requestDto;\n    this.metadata = metadata ?? new Map();\n  }\n\n  /**\n   * Get the HTTP method (convenience accessor).\n   */\n  get httpMethod(): string {\n    return this.routeMeta.httpMethod;\n  }\n\n  /**\n   * Get the request path (convenience accessor).\n   */\n  get path(): string {\n    return this.routeMeta.path;\n  }\n\n  /**\n   * Get the method name (convenience accessor).\n   */\n  get methodName(): string {\n    return this.routeMeta.methodName;\n  }\n}\n"]}

package/src/WebpiecesFactory.d.ts

@@ -0,0 +1,44 @@
+import { WebAppMeta } from '@webpieces/core-meta';
+import { WebpiecesServer } from './WebpiecesServer';
+/**
+ * WebpiecesFactory - Factory for creating WebPieces server instances.
+ *
+ * This factory encapsulates the server creation and initialization logic:
+ * 1. Creates the WebPieces DI container
+ * 2. Loads the provider module for @provideSingleton decorators
+ * 3. Resolves WebpiecesServerImpl from DI
+ * 4. Calls initialize() with the container and meta
+ * 5. Returns the server as the WebpiecesServer interface
+ *
+ * The returned WebpiecesServer interface only exposes start() and stop(),
+ * hiding the internal initialize() method from consumers.
+ *
+ * Usage:
+ * ```typescript
+ * const server = WebpiecesFactory.create(new ProdServerMeta());
+ * server.start(8080);
+ * // ... later
+ * server.stop();
+ * ```
+ *
+ * This pattern:
+ * - Enforces proper initialization order
+ * - Hides implementation details from consumers
+ * - Makes the API simpler and harder to misuse
+ * - Follows the principle of least privilege
+ */
+export declare class WebpiecesFactory {
+    /**
+     * Create a new WebPieces server instance.
+     *
+     * This method:
+     * 1. Creates the WebPieces framework DI container
+     * 2. Loads framework bindings via buildProviderModule()
+     * 3. Resolves the server implementation from DI
+     * 4. Initializes the server with the container and meta
+     *
+     * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @returns A fully initialized WebpiecesServer ready to start()
+     */
+    static create(meta: WebAppMeta): WebpiecesServer;
+}

package/src/WebpiecesFactory.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebpiecesFactory = void 0;
+const inversify_1 = require("inversify");
+const binding_decorators_1 = require("@inversifyjs/binding-decorators");
+const WebpiecesServerImpl_1 = require("./WebpiecesServerImpl");
+/**
+ * WebpiecesFactory - Factory for creating WebPieces server instances.
+ *
+ * This factory encapsulates the server creation and initialization logic:
+ * 1. Creates the WebPieces DI container
+ * 2. Loads the provider module for @provideSingleton decorators
+ * 3. Resolves WebpiecesServerImpl from DI
+ * 4. Calls initialize() with the container and meta
+ * 5. Returns the server as the WebpiecesServer interface
+ *
+ * The returned WebpiecesServer interface only exposes start() and stop(),
+ * hiding the internal initialize() method from consumers.
+ *
+ * Usage:
+ * ```typescript
+ * const server = WebpiecesFactory.create(new ProdServerMeta());
+ * server.start(8080);
+ * // ... later
+ * server.stop();
+ * ```
+ *
+ * This pattern:
+ * - Enforces proper initialization order
+ * - Hides implementation details from consumers
+ * - Makes the API simpler and harder to misuse
+ * - Follows the principle of least privilege
+ */
+class WebpiecesFactory {
+    /**
+     * Create a new WebPieces server instance.
+     *
+     * This method:
+     * 1. Creates the WebPieces framework DI container
+     * 2. Loads framework bindings via buildProviderModule()
+     * 3. Resolves the server implementation from DI
+     * 4. Initializes the server with the container and meta
+     *
+     * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @returns A fully initialized WebpiecesServer ready to start()
+     */
+    static create(meta) {
+        // 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'!)
+        const serverImpl = webpiecesContainer.get(WebpiecesServerImpl_1.WebpiecesServerImpl);
+        // Initialize the server (loads app DI modules, registers routes)
+        serverImpl.initialize(webpiecesContainer, meta);
+        // Return as interface to hide initialize() from consumers
+        return serverImpl;
+    }
+}
+exports.WebpiecesFactory = WebpiecesFactory;
+//# sourceMappingURL=WebpiecesFactory.js.map

package/src/WebpiecesFactory.js.map

@@ -0,0 +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"]}

package/src/WebpiecesServer.d.ts

@@ -1,55 +1,32 @@
-import { WebAppMeta } from '@webpieces/core-meta';
 /**
- * WebpiecesServer - Main bootstrap class for WebPieces applications.
+ * WebpiecesServer - Public interface for WebPieces server.
  *
- * This class uses a two-container pattern similar to Java WebPieces:
- * 1. webpiecesContainer: Core WebPieces framework bindings
- * 2. appContainer: User's application bindings (child of webpiecesContainer)
+ * This interface exposes only the methods needed by application code:
+ * - start(): Start the HTTP server
+ * - stop(): Stop the HTTP server
  *
- * This separation allows:
- * - Clean separation of concerns
- * - Better testability
- * - Ability to override framework bindings in tests
+ * The initialization logic is hidden inside WebpiecesFactory.create().
+ * This provides a clean API and prevents accidental re-initialization.
  *
- * The server:
- * 1. Initializes both DI containers from WebAppMeta.getDIModules()
- * 2. Registers routes using explicit RouteBuilderImpl
- * 3. Creates filter chains
- * 4. Supports both HTTP server mode and testing mode (no HTTP)
- *
- * Usage for testing (no HTTP):
- * ```typescript
- * const server = new WebpiecesServer(new ProdServerMeta());
- * server.initialize();
- * const saveApi = server.createApiClient<SaveApi>(SaveApiPrototype);
- * const response = await saveApi.save(request);
- * ```
- *
- * Usage for production (HTTP server):
+ * Usage:
  * ```typescript
- * const server = new WebpiecesServer(new ProdServerMeta());
- * server.start(); // Starts Express server
+ * const server = WebpiecesFactory.create(new ProdServerMeta());
+ * await server.start(8080);
+ * console.log('Server is now listening!');
+ * // ... later
+ * server.stop();
  * ```
  */
-export declare class WebpiecesServer {
-    private meta;
-    /**
-     * WebPieces container: Core WebPieces framework bindings.
-     * This includes framework-level services like filters, routing infrastructure,
-     * logging, metrics, etc. Similar to Java WebPieces platform container.
-     */
-    private webpiecesContainer;
-    private coreService;
-    constructor(meta: WebAppMeta);
-    /**
-     * Initialize the server (DI container, routes, filters).
-     * This is called automatically by start() or can be called manually for testing.
-     */
-    initialize(): void;
+export interface WebpiecesServer {
     /**
      * Start the HTTP server with Express.
+     * Returns a Promise that resolves when the server is listening,
+     * or rejects if the server fails to start.
+     *
+     * @param port - The port to listen on (default: 8080)
+     * @returns Promise that resolves when server is ready
      */
-    start(port?: number): void;
+    start(port?: number): Promise<void>;
     /**
      * Stop the HTTP server.
      */

package/src/WebpiecesServer.js

@@ -1,72 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebpiecesServer = void 0;
-const inversify_1 = require("inversify");
-const binding_decorators_1 = require("@inversifyjs/binding-decorators");
-const WebpiecesCoreServer_1 = require("./WebpiecesCoreServer");
-/**
- * WebpiecesServer - Main bootstrap class for WebPieces applications.
- *
- * This class uses a two-container pattern similar to Java WebPieces:
- * 1. webpiecesContainer: Core WebPieces framework bindings
- * 2. appContainer: User's application bindings (child of webpiecesContainer)
- *
- * This separation allows:
- * - Clean separation of concerns
- * - Better testability
- * - Ability to override framework bindings in tests
- *
- * The server:
- * 1. Initializes both DI containers from WebAppMeta.getDIModules()
- * 2. Registers routes using explicit RouteBuilderImpl
- * 3. Creates filter chains
- * 4. Supports both HTTP server mode and testing mode (no HTTP)
- *
- * Usage for testing (no HTTP):
- * ```typescript
- * const server = new WebpiecesServer(new ProdServerMeta());
- * server.initialize();
- * const saveApi = server.createApiClient<SaveApi>(SaveApiPrototype);
- * const response = await saveApi.save(request);
- * ```
- *
- * Usage for production (HTTP server):
- * ```typescript
- * const server = new WebpiecesServer(new ProdServerMeta());
- * server.start(); // Starts Express server
- * ```
- */
-class WebpiecesServer {
-    constructor(meta) {
-        this.meta = meta;
-        // Create WebPieces container for framework-level bindings
-        this.webpiecesContainer = new inversify_1.Container();
-        // Load buildProviderModule to auto-scan for @provideSingleton decorators
-        // This registers framework classes (WebpiecesCoreServer, RouteBuilderImpl)
-        this.webpiecesContainer.load((0, binding_decorators_1.buildProviderModule)());
-        // Resolve WebpiecesCoreServer from DI container (proper DI - no 'new'!)
-        this.coreService = this.webpiecesContainer.get(WebpiecesCoreServer_1.WebpiecesCoreServer);
-    }
-    /**
-     * Initialize the server (DI container, routes, filters).
-     * This is called automatically by start() or can be called manually for testing.
-     */
-    initialize() {
-        this.coreService.initialize(this.webpiecesContainer, this.meta);
-    }
-    /**
-     * Start the HTTP server with Express.
-     */
-    start(port = 8080) {
-        this.initialize();
-        this.coreService.start(port);
-    }
-    /**
-     * Stop the HTTP server.
-     */
-    stop() {
-        this.coreService.stop();
-    }
-}
-exports.WebpiecesServer = WebpiecesServer;
 //# sourceMappingURL=WebpiecesServer.js.map

package/src/WebpiecesServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesServer.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesServer.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AACtC,wEAAsE;AAEtE,+DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,eAAe;IAY1B,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,0DAA0D;QAC1D,IAAI,CAAC,kBAAkB,GAAG,IAAI,qBAAS,EAAE,CAAC;QAE1C,yEAAyE;QACzE,2EAA2E;QAC3E,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAA,wCAAmB,GAAE,CAAC,CAAC;QAEpD,wEAAwE;QACxE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,yCAAmB,CAAC,CAAC;IACtE,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAe,IAAI;QACvB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CAEF;AAjDD,0CAiDC","sourcesContent":["import { Container } from 'inversify';\nimport { buildProviderModule } from '@inversifyjs/binding-decorators';\nimport { WebAppMeta } from '@webpieces/core-meta';\nimport { WebpiecesCoreServer } from \"./WebpiecesCoreServer\";\n\n/**\n * WebpiecesServer - Main bootstrap class for WebPieces applications.\n *\n * This class uses a two-container pattern similar to Java WebPieces:\n * 1. webpiecesContainer: Core WebPieces framework bindings\n * 2. appContainer: User's application bindings (child of webpiecesContainer)\n *\n * This separation allows:\n * - Clean separation of concerns\n * - Better testability\n * - Ability to override framework bindings in tests\n *\n * The server:\n * 1. Initializes both DI containers from WebAppMeta.getDIModules()\n * 2. Registers routes using explicit RouteBuilderImpl\n * 3. Creates filter chains\n * 4. Supports both HTTP server mode and testing mode (no HTTP)\n *\n * Usage for testing (no HTTP):\n * ```typescript\n * const server = new WebpiecesServer(new ProdServerMeta());\n * server.initialize();\n * const saveApi = server.createApiClient<SaveApi>(SaveApiPrototype);\n * const response = await saveApi.save(request);\n * ```\n *\n * Usage for production (HTTP server):\n * ```typescript\n * const server = new WebpiecesServer(new ProdServerMeta());\n * server.start(); // Starts Express server\n * ```\n */\nexport class WebpiecesServer {\n  private meta: WebAppMeta;\n\n  /**\n   * WebPieces container: Core WebPieces framework bindings.\n   * This includes framework-level services like filters, routing infrastructure,\n   * logging, metrics, etc. Similar to Java WebPieces platform container.\n   */\n  private webpiecesContainer: Container;\n\n  private coreService: WebpiecesCoreServer;\n\n  constructor(meta: WebAppMeta) {\n    this.meta = meta;\n\n    // Create WebPieces container for framework-level bindings\n    this.webpiecesContainer = new Container();\n\n    // Load buildProviderModule to auto-scan for @provideSingleton decorators\n    // This registers framework classes (WebpiecesCoreServer, RouteBuilderImpl)\n    this.webpiecesContainer.load(buildProviderModule());\n\n    // Resolve WebpiecesCoreServer from DI container (proper DI - no 'new'!)\n    this.coreService = this.webpiecesContainer.get(WebpiecesCoreServer);\n  }\n\n  /**\n   * Initialize the server (DI container, routes, filters).\n   * This is called automatically by start() or can be called manually for testing.\n   */\n  initialize(): void {\n    this.coreService.initialize(this.webpiecesContainer, this.meta);\n  }\n\n  /**\n   * Start the HTTP server with Express.\n   */\n  start(port: number = 8080): void {\n    this.initialize();\n    this.coreService.start(port);\n  }\n\n  /**\n   * Stop the HTTP server.\n   */\n  stop(): void {\n    this.coreService.stop();\n  }\n\n}\n"]}
+{"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"]}

package/src/{WebpiecesCoreServer.d.ts → WebpiecesServerImpl.d.ts}

@@ -1,8 +1,12 @@
 import { Container } from 'inversify';
 import { WebAppMeta } from '@webpieces/core-meta';
 import { RouteBuilderImpl } from './RouteBuilderImpl';
+import { WebpiecesServer } from './WebpiecesServer';
 /**
- * WebpiecesCoreServer - Core server implementation with DI.
+ * WebpiecesServerImpl - Internal server implementation.
+ *
+ * This class implements the WebpiecesServer interface and contains
+ * all the actual server logic. It is created by WebpiecesFactory.create().
  *
  * This class uses a two-container pattern similar to Java WebPieces:
  * 1. webpiecesContainer: Core WebPieces framework bindings
@@ -20,9 +24,9 @@ import { RouteBuilderImpl } from './RouteBuilderImpl';
  * 4. Supports both HTTP server mode and testing mode (no HTTP)
  *
  * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()
- * and resolved by WebpiecesServer. It receives RouteBuilder via constructor injection.
+ * and resolved by WebpiecesFactory. It receives RouteBuilder via constructor injection.
  */
-export declare class WebpiecesCoreServer {
+export declare class WebpiecesServerImpl implements WebpiecesServer {
     private routeBuilder;
     private meta;
     private webpiecesContainer;
@@ -39,7 +43,8 @@ export declare class WebpiecesCoreServer {
     constructor(routeBuilder: RouteBuilderImpl);
     /**
      * Initialize the server (DI container, routes, filters).
-     * This is called by WebpiecesServer after resolving this class from DI.
+     * This is called by WebpiecesFactory.create() after resolving this class from DI.
+     * This method is internal and not exposed on the WebpiecesServer interface.
      *
      * @param webpiecesContainer - The framework container
      * @param meta - User-provided WebAppMeta with DI modules and routes
@@ -81,9 +86,13 @@ export declare class WebpiecesCoreServer {
     private logNextLayer;
     /**
      * Start the HTTP server with Express.
-     * Assumes initialize() has already been called by WebpiecesServer.
+     * Returns a Promise that resolves when the server is listening,
+     * or rejects if the server fails to start.
+     *
+     * @param port - The port to listen on (default: 8080)
+     * @returns Promise that resolves when server is ready
      */
-    start(port?: number): void;
+    start(port?: number): Promise<void>;
     /**
      * Register all routes with Express.
      */

package/src/{WebpiecesCoreServer.js → WebpiecesServerImpl.js}

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebpiecesCoreServer = void 0;
+exports.WebpiecesServerImpl = void 0;
 const tslib_1 = require("tslib");
 const express_1 = tslib_1.__importDefault(require("express"));
 const inversify_1 = require("inversify");
@@ -13,7 +13,10 @@ const FilterMatcher_1 = require("./FilterMatcher");
 const core_util_1 = require("@webpieces/core-util");
 const MethodMeta_1 = require("./MethodMeta");
 /**
- * WebpiecesCoreServer - Core server implementation with DI.
+ * WebpiecesServerImpl - Internal server implementation.
+ *
+ * This class implements the WebpiecesServer interface and contains
+ * all the actual server logic. It is created by WebpiecesFactory.create().
  *
  * This class uses a two-container pattern similar to Java WebPieces:
  * 1. webpiecesContainer: Core WebPieces framework bindings
@@ -31,9 +34,9 @@ const MethodMeta_1 = require("./MethodMeta");
  * 4. Supports both HTTP server mode and testing mode (no HTTP)
  *
  * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()
- * and resolved by WebpiecesServer. It receives RouteBuilder via constructor injection.
+ * and resolved by WebpiecesFactory. It receives RouteBuilder via constructor injection.
  */
-let WebpiecesCoreServer = class WebpiecesCoreServer {
+let WebpiecesServerImpl = class WebpiecesServerImpl {
     constructor(routeBuilder) {
         this.routeBuilder = routeBuilder;
         this.initialized = false;
@@ -41,7 +44,8 @@ let WebpiecesCoreServer = class WebpiecesCoreServer {
     }
     /**
      * Initialize the server (DI container, routes, filters).
-     * This is called by WebpiecesServer after resolving this class from DI.
+     * This is called by WebpiecesFactory.create() after resolving this class from DI.
+     * This method is internal and not exposed on the WebpiecesServer interface.
      *
      * @param webpiecesContainer - The framework container
      * @param meta - User-provided WebAppMeta with DI modules and routes
@@ -145,11 +149,15 @@ let WebpiecesCoreServer = class WebpiecesCoreServer {
     }
     /**
      * Start the HTTP server with Express.
-     * Assumes initialize() has already been called by WebpiecesServer.
+     * Returns a Promise that resolves when the server is listening,
+     * or rejects if the server fails to start.
+     *
+     * @param port - The port to listen on (default: 8080)
+     * @returns Promise that resolves when server is ready
      */
     start(port = 8080) {
         if (!this.initialized) {
-            throw new Error('Server not initialized. Call initialize() before start().');
+            return Promise.reject(new Error('Server not initialized. Call initialize() before start().'));
         }
         this.port = port;
         // Create Express app
@@ -164,10 +172,18 @@ let WebpiecesCoreServer = class WebpiecesCoreServer {
         // Register routes (these become the innermost handlers)
         this.registerExpressRoutes();
         const routes = this.routeBuilder.getRoutes();
-        // Start listening
-        this.server = this.app.listen(this.port, () => {
-            console.log(`[WebpiecesServer] Server listening on http://localhost:${this.port}`);
-            console.log(`[WebpiecesServer] Registered ${routes.size} routes`);
+        // Start listening - wrap in Promise
+        return new Promise((resolve, reject) => {
+            this.server = this.app.listen(this.port, (error) => {
+                if (error) {
+                    console.error(`[WebpiecesServer] Failed to start server:`, error);
+                    reject(error);
+                    return;
+                }
+                console.log(`[WebpiecesServer] Server listening on http://localhost:${this.port}`);
+                console.log(`[WebpiecesServer] Registered ${routes.size} routes`);
+                resolve();
+            });
         });
     }
     /**
@@ -266,11 +282,11 @@ let WebpiecesCoreServer = class WebpiecesCoreServer {
         }
     }
 };
-exports.WebpiecesCoreServer = WebpiecesCoreServer;
-exports.WebpiecesCoreServer = WebpiecesCoreServer = tslib_1.__decorate([
+exports.WebpiecesServerImpl = WebpiecesServerImpl;
+exports.WebpiecesServerImpl = WebpiecesServerImpl = tslib_1.__decorate([
     (0, http_routing_1.provideSingleton)(),
     (0, inversify_1.injectable)(),
     tslib_1.__param(0, (0, inversify_1.inject)(RouteBuilderImpl_1.RouteBuilderImpl)),
     tslib_1.__metadata("design:paramtypes", [RouteBuilderImpl_1.RouteBuilderImpl])
-], WebpiecesCoreServer);
-//# sourceMappingURL=WebpiecesCoreServer.js.map
+], WebpiecesServerImpl);
+//# sourceMappingURL=WebpiecesServerImpl.js.map

package/src/WebpiecesServerImpl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebpiecesServerImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesServerImpl.ts"],"names":[],"mappings":"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","sourcesContent":["import express, {Express, NextFunction, Request, Response} from 'express';\nimport {Container, inject, injectable} from 'inversify';\nimport {buildProviderModule} from '@inversifyjs/binding-decorators';\nimport {RouteRequest, WebAppMeta} from '@webpieces/core-meta';\nimport {WpResponse, Service} from '@webpieces/http-filters';\nimport {provideSingleton} from '@webpieces/http-routing';\nimport {RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta} from './RouteBuilderImpl';\nimport {FilterMatcher} from './FilterMatcher';\nimport {toError} from '@webpieces/core-util';\nimport {MethodMeta} from './MethodMeta';\nimport {WebpiecesServer} from './WebpiecesServer';\n\n/**\n * WebpiecesServerImpl - Internal server implementation.\n *\n * This class implements the WebpiecesServer interface and contains\n * all the actual server logic. It is created by WebpiecesFactory.create().\n *\n * This class uses a two-container pattern similar to Java WebPieces:\n * 1. webpiecesContainer: Core WebPieces framework bindings\n * 2. appContainer: User's application bindings (child of webpiecesContainer)\n *\n * This separation allows:\n * - Clean separation of concerns\n * - Better testability\n * - Ability to override framework bindings in tests\n *\n * The server:\n * 1. Initializes both DI containers from WebAppMeta.getDIModules()\n * 2. Registers routes using explicit RouteBuilderImpl\n * 3. Creates filter chains\n * 4. Supports both HTTP server mode and testing mode (no HTTP)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()\n * and resolved by WebpiecesFactory. It receives RouteBuilder via constructor injection.\n */\n@provideSingleton()\n@injectable()\nexport class WebpiecesServerImpl implements WebpiecesServer {\n  private meta!: WebAppMeta;\n  private webpiecesContainer!: Container;\n\n  /**\n   * Application container: User's application bindings.\n   * This is a child container of webpiecesContainer, so it can access\n   * framework bindings while keeping app bindings separate.\n   */\n  private appContainer!: Container;\n\n  private initialized = false;\n  private app?: Express;\n  private server?: ReturnType<Express['listen']>;\n  private port: number = 8080;\n\n  constructor(\n      @inject(RouteBuilderImpl) private routeBuilder: RouteBuilderImpl\n  ) {\n  }\n\n  /**\n   * Initialize the server (DI container, routes, filters).\n   * This is called by WebpiecesFactory.create() after resolving this class from DI.\n   * This method is internal and not exposed on the WebpiecesServer interface.\n   *\n   * @param webpiecesContainer - The framework container\n   * @param meta - User-provided WebAppMeta with DI modules and routes\n   */\n  initialize(webpiecesContainer: Container, meta: WebAppMeta): void {\n    if (this.initialized) {\n      return;\n    }\n\n    this.webpiecesContainer = webpiecesContainer;\n    this.meta = meta;\n\n    // Create application container as child of framework container\n    this.appContainer = new Container({ parent: this.webpiecesContainer });\n\n    // Set container on RouteBuilder (late binding - appContainer didn't exist in constructor)\n    this.routeBuilder.setContainer(this.appContainer);\n\n    // 1. Load DI modules\n    this.loadDIModules();\n\n    // 2. Register routes and filters\n    this.registerRoutes();\n\n    this.initialized = true;\n  }\n\n  /**\n   * Load DI modules from WebAppMeta.\n   *\n   * Currently, all user modules are loaded into the application container.\n   * In the future, we could separate:\n   * - WebPieces framework modules -> webpiecesContainer\n   * - Application modules -> appContainer\n   *\n   * For now, everything goes into appContainer which has access to webpiecesContainer.\n   */\n  private loadDIModules(): void {\n    const modules = this.meta.getDIModules();\n\n    // Load buildProviderModule to auto-scan for @provideSingleton decorators\n    this.appContainer.load(buildProviderModule());\n\n    // Load all modules into application container\n    // (webpiecesContainer is currently empty, reserved for future framework bindings)\n    for (const module of modules) {\n      this.appContainer.load(module);\n    }\n  }\n\n  /**\n   * Register routes from WebAppMeta.\n   *\n   * Creates an explicit RouteBuilderImpl instead of an anonymous object.\n   * This improves:\n   * - Traceability: Can Cmd+Click on addRoute to see implementation\n   * - Debugging: Explicit class shows up in stack traces\n   * - Understanding: Clear class name vs anonymous object\n   */\n  private registerRoutes(): void {\n    const routeConfigs = this.meta.getRoutes();\n\n    // Configure routes using the explicit RouteBuilder\n    for (const routeConfig of routeConfigs) {\n      routeConfig.configure(this.routeBuilder);\n    }\n  }\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 - JsonFilter catches JSON API errors,\n   * this catches everything else.\n   */\n  private 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('🔴 [Layer 1: GlobalErrorHandler] Request END (success):', req.method, req.path);\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 - JsonFilter 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('🔴 [Layer 1: GlobalErrorHandler] Request END (error):', req.method, req.path);\n    }\n  }\n\n  /**\n   * Logging middleware - logs request/response flow.\n   * Demonstrates middleware execution order.\n   */\n  private logNextLayer(req: Request, res: Response, next: NextFunction): void {\n    console.log('🟡 [Layer 2: LogNextLayer] Before next() -', req.method, req.path);\n    next();\n    console.log('🟡 [Layer 2: LogNextLayer] After next() -', req.method, req.path);\n  }\n\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 = 8080): Promise<void> {\n    if (!this.initialized) {\n      return Promise.reject(new Error('Server not initialized. Call initialize() before start().'));\n    }\n\n    this.port = port;\n\n    // Create Express app\n    this.app = express();\n\n    // Parse JSON request bodies\n    this.app.use(express.json());\n\n    // Layer 1: Global Error Handler (OUTERMOST - runs FIRST)\n    // Catches all unhandled errors and returns HTML 500 page\n    this.app.use(this.globalErrorHandler.bind(this));\n\n    // Layer 2: Request/Response Logging\n    this.app.use(this.logNextLayer.bind(this));\n\n    // Register routes (these become the innermost handlers)\n    this.registerExpressRoutes();\n\n    const routes = this.routeBuilder.getRoutes();\n\n    // Start listening - wrap in Promise\n    return new Promise((resolve, reject) => {\n      this.server = this.app!.listen(this.port, (error?: Error) => {\n        if (error) {\n          console.error(`[WebpiecesServer] Failed to start server:`, error);\n          reject(error);\n          return;\n        }\n        console.log(`[WebpiecesServer] Server listening on http://localhost:${this.port}`);\n        console.log(`[WebpiecesServer] Registered ${routes.size} routes`);\n        resolve();\n      });\n    });\n  }\n\n  /**\n   * Register all routes with Express.\n   */\n  private registerExpressRoutes(): void {\n    if (!this.app) {\n      throw new Error('Express app not initialized');\n    }\n\n    const routes = this.routeBuilder.getRoutes();\n    const sortedFilters = this.routeBuilder.getSortedFilters();\n    for (const [key, routeWithMeta] of routes.entries()) {\n      this.setupRoute(key, routeWithMeta, sortedFilters);\n    }\n  }\n\n  /**\n   * Setup a single route with Express.\n   * Finds matching filters, creates handler, and registers with Express.\n   *\n   * @param key - Route key (method:path)\n   * @param routeWithMeta - The route handler paired with its definition\n   * @param filtersWithMeta - All filters with their definitions\n   */\n  private setupRoute(key: string, routeWithMeta: RouteHandlerWithMeta, filtersWithMeta: Array<FilterWithMeta>): void {\n    if (!this.app) {\n      throw new Error('Express app not initialized');\n    }\n\n    const route = routeWithMeta.definition;\n    const routeMeta = route.routeMeta;\n    const method = routeMeta.httpMethod.toLowerCase();\n    const path = routeMeta.path;\n\n    console.log(`[WebpiecesServer] Registering route: ${method.toUpperCase()} ${path}`);\n\n    // Find matching filters for this route - FilterMatcher returns Filter[] not FilterWithMeta[]\n    // So we need to convert our FilterWithMeta[] to what FilterMatcher expects\n    const filterDefinitions = filtersWithMeta.map(fwm => {\n      // Set the filter instance on the definition for FilterMatcher\n      const def = fwm.definition;\n      def.filter = fwm.filter;\n      return def;\n    });\n\n    const matchingFilters = FilterMatcher.findMatchingFilters(\n      route.controllerFilepath,\n      filterDefinitions\n    );\n\n    // Create service that wraps the controller execution\n    const controllerService: Service<MethodMeta, WpResponse> = {\n      invoke: async (meta: MethodMeta): Promise<WpResponse> => {\n        // Invoke the controller method via route handler\n        const result = await routeWithMeta.handler.execute(meta);\n        const responseWrapper = new WpResponse(result);\n        return responseWrapper;\n      }\n    };\n\n    // Chain filters with the controller service (reverse order for correct execution)\n    // IMPORTANT: MUST USE Filter.chain(filter) and Filter.chainService(svc);\n    let filterChain = matchingFilters[matchingFilters.length - 1];\n    for (let i = matchingFilters.length - 2; i >= 0; i--) {\n      filterChain = filterChain.chain(matchingFilters[i]);\n    }\n    const svc = filterChain.chainService(controllerService);\n\n    // Create Express route handler - delegates to filter chain\n    const handler = async (req: Request, res: Response, next: NextFunction) => {\n      // Create RouteRequest with Express Request/Response\n      const routeRequest = new RouteRequest(req, res);\n\n      // Create MethodMeta with route info and Express Request/Response\n      const meta = new MethodMeta(\n        routeMeta,\n        routeRequest\n      );\n\n      // Response is written by JsonFilter - we just await completion\n      await svc.invoke(meta);\n    };\n\n    // Register with Express\n    switch (method) {\n      case 'get':\n        this.app.get(path, handler);\n        break;\n      case 'post':\n        this.app.post(path, handler);\n        break;\n      case 'put':\n        this.app.put(path, handler);\n        break;\n      case 'delete':\n        this.app.delete(path, handler);\n        break;\n      case 'patch':\n        this.app.patch(path, handler);\n        break;\n      default:\n        console.warn(`[WebpiecesServer] Unknown HTTP method: ${method}`);\n    }\n  }\n\n  /**\n   * Stop the HTTP server.\n   */\n  stop(): void {\n    if (this.server) {\n      this.server.close(() => {\n        console.log('[WebpiecesServer] Server stopped');\n      });\n    }\n  }\n}\n"]}

package/src/index.d.ts

@@ -1,6 +1,6 @@
 export { WebpiecesServer } from './WebpiecesServer';
+export { WebpiecesFactory } from './WebpiecesFactory';
 export { RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta, HttpFilter } from './RouteBuilderImpl';
-export { WebpiecesCoreServer } from './WebpiecesCoreServer';
 export { RouteHandler } from './RouteHandler';
 export { MethodMeta } from './MethodMeta';
 export { ContextFilter } from './filters/ContextFilter';

package/src/index.js

@@ -1,14 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpException = exports.ValidationException = exports.FILTER_TYPES = exports.JsonFilterConfig = exports.JsonFilter = exports.ContextFilter = exports.MethodMeta = exports.RouteHandler = exports.WebpiecesCoreServer = exports.FilterWithMeta = exports.RouteHandlerWithMeta = exports.RouteBuilderImpl = exports.WebpiecesServer = void 0;
-var WebpiecesServer_1 = require("./WebpiecesServer");
-Object.defineProperty(exports, "WebpiecesServer", { enumerable: true, get: function () { return WebpiecesServer_1.WebpiecesServer; } });
+exports.HttpException = exports.ValidationException = exports.FILTER_TYPES = exports.JsonFilterConfig = exports.JsonFilter = exports.ContextFilter = exports.MethodMeta = exports.RouteHandler = exports.FilterWithMeta = exports.RouteHandlerWithMeta = exports.RouteBuilderImpl = exports.WebpiecesFactory = void 0;
+var WebpiecesFactory_1 = require("./WebpiecesFactory");
+Object.defineProperty(exports, "WebpiecesFactory", { enumerable: true, get: function () { return WebpiecesFactory_1.WebpiecesFactory; } });
 var RouteBuilderImpl_1 = require("./RouteBuilderImpl");
 Object.defineProperty(exports, "RouteBuilderImpl", { enumerable: true, get: function () { return RouteBuilderImpl_1.RouteBuilderImpl; } });
 Object.defineProperty(exports, "RouteHandlerWithMeta", { enumerable: true, get: function () { return RouteBuilderImpl_1.RouteHandlerWithMeta; } });
 Object.defineProperty(exports, "FilterWithMeta", { enumerable: true, get: function () { return RouteBuilderImpl_1.FilterWithMeta; } });
-var WebpiecesCoreServer_1 = require("./WebpiecesCoreServer");
-Object.defineProperty(exports, "WebpiecesCoreServer", { enumerable: true, get: function () { return WebpiecesCoreServer_1.WebpiecesCoreServer; } });
 var RouteHandler_1 = require("./RouteHandler");
 Object.defineProperty(exports, "RouteHandler", { enumerable: true, get: function () { return RouteHandler_1.RouteHandler; } });
 var MethodMeta_1 = require("./MethodMeta");

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAoD;AAA3C,kHAAA,eAAe,OAAA;AACxB,uDAAwG;AAA/F,oHAAA,gBAAgB,OAAA;AAAE,wHAAA,oBAAoB,OAAA;AAAE,kHAAA,cAAc,OAAA;AAC/D,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAC5B,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AACrB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,yDAAwD;AAA/C,8GAAA,aAAa,OAAA;AACtB,mDAM8B;AAL5B,wGAAA,UAAU,OAAA;AACV,8GAAA,gBAAgB,OAAA;AAChB,0GAAA,YAAY,OAAA;AACZ,iHAAA,mBAAmB,OAAA;AACnB,2GAAA,aAAa,OAAA","sourcesContent":["export { WebpiecesServer } from './WebpiecesServer';\nexport { RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta, HttpFilter } from './RouteBuilderImpl';\nexport { WebpiecesCoreServer } from './WebpiecesCoreServer';\nexport { RouteHandler } from './RouteHandler';\nexport { MethodMeta } from './MethodMeta';\nexport { ContextFilter } from './filters/ContextFilter';\nexport {\n  JsonFilter,\n  JsonFilterConfig,\n  FILTER_TYPES,\n  ValidationException,\n  HttpException,\n} from './filters/JsonFilter';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/index.ts"],"names":[],"mappings":";;;AACA,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AACzB,uDAAwG;AAA/F,oHAAA,gBAAgB,OAAA;AAAE,wHAAA,oBAAoB,OAAA;AAAE,kHAAA,cAAc,OAAA;AAC/D,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AACrB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,yDAAwD;AAA/C,8GAAA,aAAa,OAAA;AACtB,mDAM8B;AAL5B,wGAAA,UAAU,OAAA;AACV,8GAAA,gBAAgB,OAAA;AAChB,0GAAA,YAAY,OAAA;AACZ,iHAAA,mBAAmB,OAAA;AACnB,2GAAA,aAAa,OAAA","sourcesContent":["export { WebpiecesServer } from './WebpiecesServer';\nexport { WebpiecesFactory } from './WebpiecesFactory';\nexport { RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta, HttpFilter } from './RouteBuilderImpl';\nexport { RouteHandler } from './RouteHandler';\nexport { MethodMeta } from './MethodMeta';\nexport { ContextFilter } from './filters/ContextFilter';\nexport {\n  JsonFilter,\n  JsonFilterConfig,\n  FILTER_TYPES,\n  ValidationException,\n  HttpException,\n} from './filters/JsonFilter';\n"]}

package/src/WebpiecesCoreServer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"WebpiecesCoreServer.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesCoreServer.ts"],"names":[],"mappings":";;;;AAAA,8DAA0E;AAC1E,yCAAwD;AACxD,wEAAoE;AACpE,oDAA8D;AAC9D,0DAA4D;AAC5D,0DAAyD;AACzD,yDAA0F;AAC1F,mDAA8C;AAC9C,oDAA6C;AAC7C,6CAAwC;AAExC;;;;;;;;;;;;;;;;;;;;GAoBG;AAGI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAgB9B,YAC8B,YAAsC;QAA9B,iBAAY,GAAZ,YAAY,CAAkB;QAN5D,gBAAW,GAAG,KAAK,CAAC;QAGpB,SAAI,GAAW,IAAI,CAAC;IAK5B,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,kBAA6B,EAAE,IAAgB;QACxD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,+DAA+D;QAC/D,IAAI,CAAC,YAAY,GAAG,IAAI,qBAAS,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;QAEvE,0FAA0F;QAC1F,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAElD,qBAAqB;QACrB,IAAI,CAAC,aAAa,EAAE,CAAC;QAErB,iCAAiC;QACjC,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;;;OASG;IACK,aAAa;QACnB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QAEzC,yEAAyE;QACzE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAA,wCAAmB,GAAE,CAAC,CAAC;QAE9C,8CAA8C;QAC9C,kFAAkF;QAClF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACK,cAAc;QACpB,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QAE3C,mDAAmD;QACnD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,kBAAkB,CAC9B,GAAY,EACZ,GAAa,EACb,IAAkB;QAElB,OAAO,CAAC,GAAG,CAAC,iDAAiD,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAErF,IAAI,CAAC;YACH,6BAA6B;YAC7B,2CAA2C;YAC3C,wDAAwD;YACxD,MAAM,IAAI,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,CAAC,yDAAyD,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/F,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,IAAA,mBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,0DAA0D,EAAE,KAAK,CAAC,CAAC;YACjF,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,qEAAqE;gBACrE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;;;;;;;mBAOV,KAAK,CAAC,OAAO;;;SAGvB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,uDAAuD,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QAClE,OAAO,CAAC,GAAG,CAAC,4CAA4C,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAChF,IAAI,EAAE,CAAC;QACP,OAAO,CAAC,GAAG,CAAC,2CAA2C,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACjF,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAe,IAAI;QACvB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,qBAAqB;QACrB,IAAI,CAAC,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;QAErB,4BAA4B;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAE7B,yDAAyD;QACzD,yDAAyD;QACzD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAEjD,oCAAoC;QACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAE3C,wDAAwD;QACxD,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAE7B,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC;QAE7C,kBAAkB;QAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE;YAC5C,OAAO,CAAC,GAAG,CAAC,0DAA0D,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACnF,OAAO,CAAC,GAAG,CAAC,gCAAgC,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,qBAAqB;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC;QAC7C,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,CAAC;QAC3D,KAAK,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YACpD,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,UAAU,CAAC,GAAW,EAAE,aAAmC,EAAE,eAAsC;QACzG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC;QACvC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QAClC,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;QAE5B,OAAO,CAAC,GAAG,CAAC,wCAAwC,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;QAEpF,6FAA6F;QAC7F,2EAA2E;QAC3E,MAAM,iBAAiB,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YAClD,8DAA8D;YAC9D,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC;YAC3B,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;YACxB,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;QAEH,MAAM,eAAe,GAAG,6BAAa,CAAC,mBAAmB,CACvD,KAAK,CAAC,kBAAkB,EACxB,iBAAiB,CAClB,CAAC;QAEF,qDAAqD;QACrD,MAAM,iBAAiB,GAAoC;YACzD,MAAM,EAAE,KAAK,EAAE,IAAgB,EAAuB,EAAE;gBACtD,iDAAiD;gBACjD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACzD,MAAM,eAAe,GAAG,IAAI,yBAAU,CAAC,MAAM,CAAC,CAAC;gBAC/C,OAAO,eAAe,CAAC;YACzB,CAAC;SACF,CAAC;QAEF,kFAAkF;QAClF,yEAAyE;QACzE,IAAI,WAAW,GAAG,eAAe,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC9D,KAAK,IAAI,CAAC,GAAG,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACrD,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,GAAG,GAAG,WAAW,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;QAExD,2DAA2D;QAC3D,MAAM,OAAO,GAAG,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;YACxE,oDAAoD;YACpD,MAAM,YAAY,GAAG,IAAI,wBAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAEhD,iEAAiE;YACjE,MAAM,IAAI,GAAG,IAAI,uBAAU,CACzB,SAAS,EACT,YAAY,CACb,CAAC;YAEF,+DAA+D;YAC/D,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC;QAEF,wBAAwB;QACxB,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,KAAK;gBACR,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAC5B,MAAM;YACR,KAAK,MAAM;gBACT,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAC7B,MAAM;YACR,KAAK,KAAK;gBACR,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAC5B,MAAM;YACR,KAAK,QAAQ;gBACX,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAC/B,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAC9B,MAAM;YACR;gBACE,OAAO,CAAC,IAAI,CAAC,0CAA0C,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;gBACrB,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF,CAAA;AArSY,kDAAmB;8BAAnB,mBAAmB;IAF/B,IAAA,+BAAgB,GAAE;IAClB,IAAA,sBAAU,GAAE;IAkBN,mBAAA,IAAA,kBAAM,EAAC,mCAAgB,CAAC,CAAA;6CAAuB,mCAAgB;GAjBzD,mBAAmB,CAqS/B","sourcesContent":["import express, {Express, NextFunction, Request, Response} from 'express';\nimport {Container, inject, injectable} from 'inversify';\nimport {buildProviderModule} from '@inversifyjs/binding-decorators';\nimport {RouteRequest, WebAppMeta} from '@webpieces/core-meta';\nimport {WpResponse, Service} from '@webpieces/http-filters';\nimport {provideSingleton} from '@webpieces/http-routing';\nimport {RouteBuilderImpl, RouteHandlerWithMeta, FilterWithMeta} from './RouteBuilderImpl';\nimport {FilterMatcher} from './FilterMatcher';\nimport {toError} from '@webpieces/core-util';\nimport {MethodMeta} from './MethodMeta';\n\n/**\n * WebpiecesCoreServer - Core server implementation with DI.\n *\n * This class uses a two-container pattern similar to Java WebPieces:\n * 1. webpiecesContainer: Core WebPieces framework bindings\n * 2. appContainer: User's application bindings (child of webpiecesContainer)\n *\n * This separation allows:\n * - Clean separation of concerns\n * - Better testability\n * - Ability to override framework bindings in tests\n *\n * The server:\n * 1. Initializes both DI containers from WebAppMeta.getDIModules()\n * 2. Registers routes using explicit RouteBuilderImpl\n * 3. Creates filter chains\n * 4. Supports both HTTP server mode and testing mode (no HTTP)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()\n * and resolved by WebpiecesServer. It receives RouteBuilder via constructor injection.\n */\n@provideSingleton()\n@injectable()\nexport class WebpiecesCoreServer {\n  private meta!: WebAppMeta;\n  private webpiecesContainer!: Container;\n\n  /**\n   * Application container: User's application bindings.\n   * This is a child container of webpiecesContainer, so it can access\n   * framework bindings while keeping app bindings separate.\n   */\n  private appContainer!: Container;\n\n  private initialized = false;\n  private app?: Express;\n  private server?: ReturnType<Express['listen']>;\n  private port: number = 8080;\n\n  constructor(\n      @inject(RouteBuilderImpl) private routeBuilder: RouteBuilderImpl\n  ) {\n  }\n\n  /**\n   * Initialize the server (DI container, routes, filters).\n   * This is called by WebpiecesServer after resolving this class from DI.\n   *\n   * @param webpiecesContainer - The framework container\n   * @param meta - User-provided WebAppMeta with DI modules and routes\n   */\n  initialize(webpiecesContainer: Container, meta: WebAppMeta): void {\n    if (this.initialized) {\n      return;\n    }\n\n    this.webpiecesContainer = webpiecesContainer;\n    this.meta = meta;\n\n    // Create application container as child of framework container\n    this.appContainer = new Container({ parent: this.webpiecesContainer });\n\n    // Set container on RouteBuilder (late binding - appContainer didn't exist in constructor)\n    this.routeBuilder.setContainer(this.appContainer);\n\n    // 1. Load DI modules\n    this.loadDIModules();\n\n    // 2. Register routes and filters\n    this.registerRoutes();\n\n    this.initialized = true;\n  }\n\n  /**\n   * Load DI modules from WebAppMeta.\n   *\n   * Currently, all user modules are loaded into the application container.\n   * In the future, we could separate:\n   * - WebPieces framework modules -> webpiecesContainer\n   * - Application modules -> appContainer\n   *\n   * For now, everything goes into appContainer which has access to webpiecesContainer.\n   */\n  private loadDIModules(): void {\n    const modules = this.meta.getDIModules();\n\n    // Load buildProviderModule to auto-scan for @provideSingleton decorators\n    this.appContainer.load(buildProviderModule());\n\n    // Load all modules into application container\n    // (webpiecesContainer is currently empty, reserved for future framework bindings)\n    for (const module of modules) {\n      this.appContainer.load(module);\n    }\n  }\n\n  /**\n   * Register routes from WebAppMeta.\n   *\n   * Creates an explicit RouteBuilderImpl instead of an anonymous object.\n   * This improves:\n   * - Traceability: Can Cmd+Click on addRoute to see implementation\n   * - Debugging: Explicit class shows up in stack traces\n   * - Understanding: Clear class name vs anonymous object\n   */\n  private registerRoutes(): void {\n    const routeConfigs = this.meta.getRoutes();\n\n    // Configure routes using the explicit RouteBuilder\n    for (const routeConfig of routeConfigs) {\n      routeConfig.configure(this.routeBuilder);\n    }\n  }\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 - JsonFilter catches JSON API errors,\n   * this catches everything else.\n   */\n  private 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('🔴 [Layer 1: GlobalErrorHandler] Request END (success):', req.method, req.path);\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 - JsonFilter 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('🔴 [Layer 1: GlobalErrorHandler] Request END (error):', req.method, req.path);\n    }\n  }\n\n  /**\n   * Logging middleware - logs request/response flow.\n   * Demonstrates middleware execution order.\n   */\n  private logNextLayer(req: Request, res: Response, next: NextFunction): void {\n    console.log('🟡 [Layer 2: LogNextLayer] Before next() -', req.method, req.path);\n    next();\n    console.log('🟡 [Layer 2: LogNextLayer] After next() -', req.method, req.path);\n  }\n\n  /**\n   * Start the HTTP server with Express.\n   * Assumes initialize() has already been called by WebpiecesServer.\n   */\n  start(port: number = 8080): void {\n    if (!this.initialized) {\n      throw new Error('Server not initialized. Call initialize() before start().');\n    }\n\n    this.port = port;\n\n    // Create Express app\n    this.app = express();\n\n    // Parse JSON request bodies\n    this.app.use(express.json());\n\n    // Layer 1: Global Error Handler (OUTERMOST - runs FIRST)\n    // Catches all unhandled errors and returns HTML 500 page\n    this.app.use(this.globalErrorHandler.bind(this));\n\n    // Layer 2: Request/Response Logging\n    this.app.use(this.logNextLayer.bind(this));\n\n    // Register routes (these become the innermost handlers)\n    this.registerExpressRoutes();\n\n    const routes = this.routeBuilder.getRoutes();\n\n    // Start listening\n    this.server = this.app.listen(this.port, () => {\n      console.log(`[WebpiecesServer] Server listening on http://localhost:${this.port}`);\n      console.log(`[WebpiecesServer] Registered ${routes.size} routes`);\n    });\n  }\n\n  /**\n   * Register all routes with Express.\n   */\n  private registerExpressRoutes(): void {\n    if (!this.app) {\n      throw new Error('Express app not initialized');\n    }\n\n    const routes = this.routeBuilder.getRoutes();\n    const sortedFilters = this.routeBuilder.getSortedFilters();\n    for (const [key, routeWithMeta] of routes.entries()) {\n      this.setupRoute(key, routeWithMeta, sortedFilters);\n    }\n  }\n\n  /**\n   * Setup a single route with Express.\n   * Finds matching filters, creates handler, and registers with Express.\n   *\n   * @param key - Route key (method:path)\n   * @param routeWithMeta - The route handler paired with its definition\n   * @param filtersWithMeta - All filters with their definitions\n   */\n  private setupRoute(key: string, routeWithMeta: RouteHandlerWithMeta, filtersWithMeta: Array<FilterWithMeta>): void {\n    if (!this.app) {\n      throw new Error('Express app not initialized');\n    }\n\n    const route = routeWithMeta.definition;\n    const routeMeta = route.routeMeta;\n    const method = routeMeta.httpMethod.toLowerCase();\n    const path = routeMeta.path;\n\n    console.log(`[WebpiecesServer] Registering route: ${method.toUpperCase()} ${path}`);\n\n    // Find matching filters for this route - FilterMatcher returns Filter[] not FilterWithMeta[]\n    // So we need to convert our FilterWithMeta[] to what FilterMatcher expects\n    const filterDefinitions = filtersWithMeta.map(fwm => {\n      // Set the filter instance on the definition for FilterMatcher\n      const def = fwm.definition;\n      def.filter = fwm.filter;\n      return def;\n    });\n\n    const matchingFilters = FilterMatcher.findMatchingFilters(\n      route.controllerFilepath,\n      filterDefinitions\n    );\n\n    // Create service that wraps the controller execution\n    const controllerService: Service<MethodMeta, WpResponse> = {\n      invoke: async (meta: MethodMeta): Promise<WpResponse> => {\n        // Invoke the controller method via route handler\n        const result = await routeWithMeta.handler.execute(meta);\n        const responseWrapper = new WpResponse(result);\n        return responseWrapper;\n      }\n    };\n\n    // Chain filters with the controller service (reverse order for correct execution)\n    // IMPORTANT: MUST USE Filter.chain(filter) and Filter.chainService(svc);\n    let filterChain = matchingFilters[matchingFilters.length - 1];\n    for (let i = matchingFilters.length - 2; i >= 0; i--) {\n      filterChain = filterChain.chain(matchingFilters[i]);\n    }\n    const svc = filterChain.chainService(controllerService);\n\n    // Create Express route handler - delegates to filter chain\n    const handler = async (req: Request, res: Response, next: NextFunction) => {\n      // Create RouteRequest with Express Request/Response\n      const routeRequest = new RouteRequest(req, res);\n\n      // Create MethodMeta with route info and Express Request/Response\n      const meta = new MethodMeta(\n        routeMeta,\n        routeRequest\n      );\n\n      // Response is written by JsonFilter - we just await completion\n      await svc.invoke(meta);\n    };\n\n    // Register with Express\n    switch (method) {\n      case 'get':\n        this.app.get(path, handler);\n        break;\n      case 'post':\n        this.app.post(path, handler);\n        break;\n      case 'put':\n        this.app.put(path, handler);\n        break;\n      case 'delete':\n        this.app.delete(path, handler);\n        break;\n      case 'patch':\n        this.app.patch(path, handler);\n        break;\n      default:\n        console.warn(`[WebpiecesServer] Unknown HTTP method: ${method}`);\n    }\n  }\n\n  /**\n   * Stop the HTTP server.\n   */\n  stop(): void {\n    if (this.server) {\n      this.server.close(() => {\n        console.log('[WebpiecesServer] Server stopped');\n      });\n    }\n  }\n}\n"]}