@catbee/utils 2.0.5 → 2.2.0

package/server/index.mjs

@@ -23,19 +23,21 @@
  */
 
 import express from 'express';
+import http from 'http';
 import https from 'https';
 import { HttpStatusCodes } from '@catbee/utils/http-status-codes';
-import { createFinalErrorResponse, SuccessResponse } from '@catbee/utils/response';
+import { createFinalErrorResponse } from '@catbee/utils/response';
 import { requestId, setupRequestContext, timeout, responseTime, errorHandler } from '@catbee/utils/middleware';
 import { Env } from '@catbee/utils/env';
 import { getLogger } from '@catbee/utils/logger';
-import { ServiceUnavailableException, InternalServerErrorException, NotFoundException } from '@catbee/utils/exception';
+import { ServiceUnavailableException, NotFoundException } from '@catbee/utils/exception';
 import { getCatbeeServerGlobalConfig } from '@catbee/utils/config';
-import { deepObjMerge, isPlainObject, deepClone } from '@catbee/utils/object';
+import { isPlainObject, deepClone, deepObjMerge } from '@catbee/utils/object';
 import { fileExists, readFile, readFileSync } from '@catbee/utils/fs';
 import { isPort, isHostname } from '@catbee/utils/validation';
 import { optionalRequire } from '@catbee/utils/async';
 import { uuid } from '@catbee/utils/id';
+import { HealthzServer } from '@catbee/utils/healthz-server';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -298,36 +300,53 @@ var ServerConfigBuilder = class {
     return this.setEnabled("requestLogging", false);
   }
   /**
-  * Configures server health check endpoint.
+  * Configures the dedicated Healthz probe HTTP server for Kubernetes.
   *
-  * @param opts - Health check configuration options
+  * @param opts - Healthz server configuration options or boolean toggle
   * @returns The builder instance for chaining
-  * @default - { path: '/healthz', detailed: true, withGlobalPrefix: false }
   *
   * @example
   * ```typescript
-  * builder.withHealthCheck({
-  *   path: '/health',
-  *   detailed: true
+  * builder.withHealthzServer({
+  *   port: 8282,
+  *   shutdownDelayMs: 5000,
+  *   readinessChecks: [
+  *     { name: 'db', check: () => checkDb() }
+  *   ]
   * })
   * ```
   */
-  withHealthCheck(opts) {
-    this.mergeConfig("healthCheck", opts);
+  withHealthzServer(opts) {
+    if (typeof opts === "boolean") {
+      this.config.healthzServer = opts;
+    } else {
+      const current = isPlainObject(this.config.healthzServer) ? deepClone(this.config.healthzServer) : {};
+      this.config.healthzServer = deepObjMerge({}, current, {
+        enable: true,
+        ...opts
+      });
+    }
     return this;
   }
   /**
-  * Enables health check endpoint with default or custom settings
-  * @param opts - Optional health check configuration
+  * Enables the dedicated Healthz probe HTTP server.
+  *
+  * @param opts - Optional Healthz server configuration options
   * @returns The builder instance for chaining
+  */
+  enableHealthzServer(opts = {}) {
+    return this.withHealthzServer({
+      ...opts,
+      enable: true
+    });
+  }
+  /**
+  * Disables the dedicated Healthz probe HTTP server.
   *
-  * @example
-  * ```typescript
-  * builder.disableHealthCheck()
-  * ```
+  * @returns The builder instance for chaining
   */
-  disableHealthCheck() {
-    return this.setEnabled("healthCheck", false);
+  disableHealthzServer() {
+    return this.withHealthzServer(false);
   }
   /**
   * Configures OpenAPI/Swagger documentation for the API.
@@ -682,6 +701,15 @@ var DependencyErrors = {
   "cookie-parser": getDependencyErrorMessage("cookie-parser"),
   "@scalar/express-api-reference": getDependencyErrorMessage("@scalar/express-api-reference")
 };
+var SUPPORTED_HTTP_METHODS = /* @__PURE__ */ new Set([
+  "get",
+  "post",
+  "put",
+  "delete",
+  "patch",
+  "options",
+  "head"
+]);
 var ExpressServer = class {
   static {
     __name(this, "ExpressServer");
@@ -694,11 +722,11 @@ var ExpressServer = class {
   hooks;
   /** Global API prefix (from config) */
   globalPrefix;
-  /** Internal fallback router */
+  /** Primary root router mounted to the application */
   rootRouter;
-  /** User-supplied router */
-  externalRouter;
-  /** Internal Express app instance */
+  /** Set of registered sub-routers to prevent duplicate mounting */
+  mountedRouters = /* @__PURE__ */ new Set();
+  /** Express app instance */
   app;
   /** Set of active WebSocket connections */
   connections = /* @__PURE__ */ new Set();
@@ -706,13 +734,18 @@ var ExpressServer = class {
   isShuttingDown = false;
   /** Flag indicating if graceful shutdown handlers are registered */
   gracefulShutdownRegistered = false;
-  /**
-  * Collection of registered health check functions.
-  * These are executed when the health check endpoint is accessed.
-  */
-  healthChecks = [];
+  /** Map of registered signal listeners for clean teardown */
+  signalListeners = /* @__PURE__ */ new Map();
+  /** Running address info for the Healthz probe server */
+  healthzAddress;
+  /** Named checks queued for Healthz liveness probe */
+  healthzChecks = [];
+  /** Named checks queued for Healthz readiness probe */
+  healthzReadinessChecks = [];
   /** Promise that resolves when initialization (middleware + routes) is complete */
   initPromise;
+  /** In-flight start promise to protect against concurrent start() calls */
+  startPromise;
   /**
   * Initializes server with intelligent defaults and security best practices.
   * All settings can be customized via config and hooks.
@@ -743,8 +776,19 @@ var ExpressServer = class {
       getLogger().error(msg);
       throw new Error(msg);
     }
-    if (config?.healthCheck?.checks) {
-      this.healthChecks.push(...config.healthCheck.checks);
+    if (typeof this.config.healthzServer === "boolean") {
+      this.config.healthzServer = {
+        ...HealthzServer.getDefaultConfig(),
+        enable: this.config.healthzServer
+      };
+    }
+    if (this.config.healthzServer && typeof this.config.healthzServer === "object") {
+      if (this.config.healthzServer.checks) {
+        this.healthzChecks.push(...this.config.healthzServer.checks);
+      }
+      if (this.config.healthzServer.readinessChecks) {
+        this.healthzReadinessChecks.push(...this.config.healthzServer.readinessChecks);
+      }
     }
     this.globalPrefix = this.normalizePath(this.config.globalPrefix ?? "", false);
     this.hooks = hooks;
@@ -815,6 +859,7 @@ var ExpressServer = class {
     this.setupBodyParsingMiddleware();
     this.setupCookieParsingMiddleware();
     await this.setupOpenApiMiddleware();
+    this.setupResponseHook();
   }
   /**
   * Set up basic middleware (trust proxy, request ID, context).
@@ -869,10 +914,15 @@ var ExpressServer = class {
   * Set up global headers middleware.
   */
   setupGlobalHeaders() {
+    const hasCustomHeaders = Boolean(this.config.globalHeaders && Object.keys(this.config.globalHeaders).length > 0);
+    const isMicroservice = Boolean(this.config.isMicroservice);
+    const hasServiceVersion = Boolean(this.config.serviceVersion?.enable);
+    if (!hasCustomHeaders && !isMicroservice && !hasServiceVersion) {
+      return;
+    }
     this.app.use((_req, res, next) => {
       if (this.config.globalHeaders) {
-        for (const key in this.config.globalHeaders) {
-          const value = this.config.globalHeaders[key];
+        for (const [key, value] of Object.entries(this.config.globalHeaders)) {
           res.setHeader(key, typeof value === "function" ? value() : value);
         }
       }
@@ -1067,6 +1117,11 @@ var ExpressServer = class {
         }, "Failed to mount OpenAPI docs");
       }
     }
+  }
+  /**
+  * Set up response preprocessing hook (applies global prefix if set).
+  */
+  setupResponseHook() {
     if (this.hooks.onResponse) {
       this.app.use(this.globalPrefix, this.hooks.onResponse);
     }
@@ -1081,12 +1136,7 @@ var ExpressServer = class {
   * 4. Error handler
   */
   async setupRoutes() {
-    const healthCheckPath = this.normalizePath(this.config.healthCheck?.path || "/healthz", this.config.healthCheck?.withGlobalPrefix);
-    this.app.get(healthCheckPath, async (_req, res) => {
-      return this.handleHealthCheckRequest(res);
-    });
-    const routerToUse = this.externalRouter || this.rootRouter;
-    this.app.use(this.globalPrefix, routerToUse);
+    this.app.use(this.globalPrefix, this.rootRouter);
     await this.runHook("afterRoutes", this.app);
     this.app.use((req, res) => {
       const status = HttpStatusCodes.NOT_FOUND;
@@ -1109,60 +1159,25 @@ var ExpressServer = class {
     });
   }
   /**
-  * Execute health check and return response.
+  * Whether the Healthz probe server is enabled.
   */
-  async handleHealthCheckRequest(res) {
-    try {
-      if (!this.healthChecks.length || getCatbeeServerGlobalConfig().skipHealthzChecksValidation) {
-        return res.status(HttpStatusCodes.OK).json(new SuccessResponse("OK"));
-      }
-      const results = await this.executeHealthChecks();
-      const allOk = results.every((r) => r.status);
-      const status = allOk ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;
-      const response = new SuccessResponse(allOk ? "OK" : "Service unavailable");
-      if (!allOk) response.error = true;
-      if (this.config.healthCheck?.detailed) response.data = {
-        checks: results
-      };
-      return res.status(status).json(response);
-    } catch {
-      return res.status(HttpStatusCodes.INTERNAL_SERVER_ERROR).json(new InternalServerErrorException("Health check failed"));
+  isHealthzServerEnabled() {
+    if (typeof this.config.healthzServer === "boolean") {
+      return this.config.healthzServer;
     }
+    return this.config.healthzServer?.enable === true;
   }
   /**
-  * Execute all registered health checks and return results.
+  * Get the graceful shutdown delay in milliseconds configured for HealthzServer.
   */
-  async executeHealthChecks() {
-    const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
-      try {
-        const status = await Promise.resolve(check());
-        return {
-          name,
-          status,
-          error: null
-        };
-      } catch (error) {
-        return {
-          name,
-          status: false,
-          error: error.message
-        };
-      }
-    }));
-    return checkResults.map((result) => {
-      if (result.status === "fulfilled") return result.value;
-      return {
-        name: "unknown",
-        status: false,
-        error: result.reason
-      };
-    });
+  getHealthzShutdownDelay() {
+    return typeof this.config.healthzServer === "object" ? this.config.healthzServer.shutdownDelayMs ?? 0 : 0;
   }
   /**
-  * Register a new health check function for monitoring service dependencies.
+  * Register a new health check function for monitoring service dependencies on the Healthz probe server.
   *
-  * Health checks are executed when the health endpoint is accessed and
-  * help determine if the service is ready to handle requests.
+  * By default, external dependencies (DB, Redis, etc.) are registered as `readiness` checks.
+  * Can also be registered as `liveness` or `both`.
   *
   * Examples:
   * - Database connectivity
@@ -1171,33 +1186,61 @@ var ExpressServer = class {
   * - Memory/CPU usage checks
   *
   * @param name Unique identifier for the check (used in detailed responses)
-  * @param check Function returning boolean or Promise<boolean> indicating health
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @param options Target probe type ('readiness' | 'liveness' | 'both') or options object
   * @returns This instance for method chaining
   */
-  registerHealthCheck(name, check) {
-    this.healthChecks.push({
+  registerHealthCheck(name, check, options) {
+    const probeType = typeof options === "string" ? options : options?.type ?? "readiness";
+    const namedCheck = {
       name,
       check
-    });
+    };
+    if (probeType === "liveness" || probeType === "both") {
+      this.healthzChecks.push(namedCheck);
+    }
+    if (probeType === "readiness" || probeType === "both") {
+      this.healthzReadinessChecks.push(namedCheck);
+    }
+    HealthzServer.registerCheck(namedCheck, probeType);
     return this;
   }
   /**
-  * Run registered health checks and return whether the service is ready.
-  * Useful for readiness probes in deployment tooling.
+  * Mark the service as ready / not-ready for traffic on the Healthz probe server.
   *
-  * @returns Promise resolving to `true` when all checks pass, otherwise `false`.
+  * @param ready Whether the service is ready to receive traffic
+  * @returns This instance for method chaining
   */
-  async ready() {
-    try {
-      if (!this.healthChecks.length || getCatbeeServerGlobalConfig().skipHealthzChecksValidation) return true;
-      const results = await this.executeHealthChecks();
-      return results.every((r) => r.status === true);
-    } catch (err) {
-      getLogger().error({
-        err
-      }, "Error while running readiness checks");
-      return false;
-    }
+  setReady(ready) {
+    HealthzServer.setReady(ready);
+    return this;
+  }
+  /**
+  * Whether the service is currently marked as ready for traffic on the Healthz probe server.
+  */
+  isReady() {
+    return HealthzServer.isReady();
+  }
+  /**
+  * Get the running HealthzServer instance (if started).
+  */
+  getHealthzServer() {
+    return HealthzServer.getInstance();
+  }
+  /**
+  * Get the address info of the running HealthzServer (if started).
+  */
+  getHealthzAddress() {
+    return this.healthzAddress;
+  }
+  /**
+  * Returns whether the service is currently marked as ready for traffic on the Healthz probe server.
+  * Useful for readiness checks in deployment tooling.
+  *
+  * @returns `true` when ready, otherwise `false`.
+  */
+  ready() {
+    return HealthzServer.isReady();
   }
   /**
   * Get the underlying Express application instance.
@@ -1221,11 +1264,15 @@ var ExpressServer = class {
   * Start the HTTP server and begin listening for requests.
   *
   * This method:
+  * - Protects against concurrent start() invocations
+  * - Awaits server initialization (middleware + routes)
   * - Executes beforeStart hooks
+  * - Creates the HTTP/HTTPS server instance
+  * - Sets up error handling and connection tracking BEFORE listening
+  * - Executes onServerCreated hook BEFORE listening
   * - Binds to the configured host/port
-  * - Sets up error handling for startup failures
-  * - Executes afterStart hooks on success
-  * - Logs startup information
+  * - Executes afterStart hooks on successful listen
+  * - Cleans up server reference and listeners on startup failure
   *
   * @returns Promise resolving to the running HTTP server instance
   * @throws Error if server fails to start or port is already in use
@@ -1235,33 +1282,112 @@ var ExpressServer = class {
       getLogger().warn("Server is already running, returning existing instance");
       return this.server;
     }
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+    this.startPromise = this.doStart();
+    try {
+      return await this.startPromise;
+    } finally {
+      this.startPromise = void 0;
+    }
+  }
+  /**
+  * Internal implementation of server startup.
+  */
+  async doStart() {
     await this.initPromise;
     await this.runHook("beforeStart", this.app);
+    const server = this.createServerInstance();
+    this.server = server;
     return new Promise((resolve, reject) => {
-      try {
+      let isListening = false;
+      server.on("error", (err) => {
+        if (!isListening) {
+          getLogger().error({
+            err
+          }, "Server failed to start");
+          try {
+            server.removeAllListeners();
+            server.close();
+            if (HealthzServer.isStarted()) {
+              HealthzServer.stop().catch(() => {
+              });
+            }
+          } catch {
+          }
+          this.server = null;
+          this.connections.clear();
+          reject(err);
+        } else {
+          getLogger().error({
+            err
+          }, "Server runtime error");
+        }
+      });
+      this.setupConnectionTracking();
+      Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
         const onListening = /* @__PURE__ */ __name(async () => {
-          this.logServerStartInfo();
-          if (this.server) await this.runHook("afterStart", this.server);
-          resolve(this.server);
+          try {
+            if (this.isHealthzServerEnabled()) {
+              const healthzConfig = {
+                ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
+                handleSignals: false,
+                checks: [
+                  ...this.healthzChecks
+                ],
+                readinessChecks: [
+                  ...this.healthzReadinessChecks
+                ]
+              };
+              const addr = await HealthzServer.start(healthzConfig);
+              if (!addr) {
+                throw new Error("Healthz probe server failed to start (already running in this process)");
+              }
+              this.healthzAddress = addr;
+            }
+            this.logServerStartInfo();
+            await this.runHook("afterStart", server);
+            if (this.isHealthzServerEnabled()) {
+              HealthzServer.setReady(true);
+            }
+            isListening = true;
+            resolve(server);
+          } catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            getLogger().error({
+              err: error
+            }, "Server startup failed");
+            if (HealthzServer.isStarted()) {
+              await HealthzServer.stop().catch(() => {
+              });
+            }
+            try {
+              server.removeAllListeners();
+              server.close();
+            } catch {
+            }
+            this.server = null;
+            this.healthzAddress = null;
+            this.connections.clear();
+            reject(error);
+          }
         }, "onListening");
-        this.server = this.createServerInstance(onListening);
-        this.runHook("onServerCreated", this.server);
-        this.setupConnectionTracking();
-        this.setupServerErrorHandling(reject);
-      } catch (error) {
-        reject(error);
-      }
+        const listenArgs = [
+          this.config.port,
+          this.config.host,
+          onListening
+        ];
+        server.listen(...listenArgs);
+      }).catch((err) => {
+        server.emit("error", err instanceof Error ? err : new Error(String(err)));
+      });
     });
   }
   /**
-  * Create HTTP or HTTPS server instance.
+  * Create HTTP or HTTPS server instance (without listening).
   */
-  createServerInstance(onListening) {
-    const listenArgs = [
-      this.config.port,
-      this.config.host,
-      onListening
-    ];
+  createServerInstance() {
     if (this.config.https) {
       const httpsOptions = {
         ...this.config.https,
@@ -1274,9 +1400,9 @@ var ExpressServer = class {
       if (this.config.https.passphrase) {
         httpsOptions.passphrase = this.config.https.passphrase;
       }
-      return https.createServer(httpsOptions, this.app).listen(...listenArgs);
+      return https.createServer(httpsOptions, this.app);
     }
-    return this.app.listen(...listenArgs);
+    return http.createServer(this.app);
   }
   /**
   * Set up connection tracking for graceful shutdown.
@@ -1288,17 +1414,6 @@ var ExpressServer = class {
     });
   }
   /**
-  * Set up error handling for server startup.
-  */
-  setupServerErrorHandling(reject) {
-    this.server.on("error", (err) => {
-      getLogger().error({
-        err
-      }, "Server failed to start");
-      reject(err);
-    });
-  }
-  /**
   * Log server startup information.
   */
   logServerStartInfo() {
@@ -1307,8 +1422,8 @@ var ExpressServer = class {
     const host = this.formatHostForUrl(this.config.host || "localhost");
     const url = `${protocol}://${host}:${port}`;
     getLogger().info(`Server running on ${url}`);
-    if (this.config.healthCheck && this.config.healthCheck?.path) {
-      getLogger().info(`Health check available at ${url}${this.normalizePath(this.config.healthCheck.path, this.config.healthCheck.withGlobalPrefix)}`);
+    if (this.healthzAddress) {
+      getLogger().info(`Healthz probe server running on http://${this.healthzAddress.address}:${this.healthzAddress.port}`);
     }
     if (this.config.openApi?.enable) {
       getLogger().info(`API docs available at ${url}${this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)}`);
@@ -1331,7 +1446,7 @@ var ExpressServer = class {
   * - Monitoring systems are notified
   */
   async stop(force = false) {
-    if (!this.server) {
+    if (!this.server && !HealthzServer.isStarted()) {
       getLogger().warn("Stop called but server is not running");
       return;
     }
@@ -1340,10 +1455,26 @@ var ExpressServer = class {
       return;
     }
     this.isShuttingDown = true;
-    await this.runHook("beforeStop", this.server);
+    if (HealthzServer.isStarted()) {
+      HealthzServer.setReady(false);
+    }
+    if (this.server) {
+      await this.runHook("beforeStop", this.server);
+    }
     try {
-      await this.gracefulShutdown(force);
+      const shutdownDelay = this.getHealthzShutdownDelay();
+      if (shutdownDelay > 0 && !force && HealthzServer.isStarted()) {
+        getLogger().info(`Waiting ${shutdownDelay}ms for load balancer to drain traffic...`);
+        await new Promise((resolve) => setTimeout(resolve, shutdownDelay));
+      }
+      if (this.server) {
+        await this.gracefulShutdown(force);
+      }
     } finally {
+      if (HealthzServer.isStarted()) {
+        await HealthzServer.stop();
+        this.healthzAddress = null;
+      }
       this.isShuttingDown = false;
     }
   }
@@ -1360,6 +1491,7 @@ var ExpressServer = class {
       afterStopCalled = true;
       await this.runHook("afterStop");
     }, "runAfterStop");
+    server.closeIdleConnections?.();
     const serverClosePromise = new Promise((resolve, reject) => {
       server.close(async (err) => {
         if (timer) clearTimeout(timer);
@@ -1422,7 +1554,7 @@ var ExpressServer = class {
     }
     let signalHandled = false;
     signals.forEach((signal) => {
-      process.on(signal, async () => {
+      const handler = /* @__PURE__ */ __name(async () => {
         if (signalHandled) {
           getLogger().warn(`Ignoring duplicate ${signal}`);
           return;
@@ -1430,7 +1562,8 @@ var ExpressServer = class {
         signalHandled = true;
         getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
         try {
-          await this.stop(true);
+          this.disableGracefulShutdown();
+          await this.stop(false);
           process.exit(0);
         } catch (err) {
           getLogger().fatal({
@@ -1438,12 +1571,29 @@ var ExpressServer = class {
           }, "Shutdown failed");
           process.exit(1);
         }
-      });
+      }, "handler");
+      this.signalListeners.set(signal, handler);
+      process.on(signal, handler);
     });
     this.gracefulShutdownRegistered = true;
     return this;
   }
   /**
+  * Unregister graceful shutdown signal listeners.
+  * Useful for testing and dynamic server lifecycles to prevent memory and listener leaks.
+  */
+  disableGracefulShutdown() {
+    if (!this.gracefulShutdownRegistered) {
+      return this;
+    }
+    for (const [signal, handler] of this.signalListeners.entries()) {
+      process.removeListener(signal, handler);
+    }
+    this.signalListeners.clear();
+    this.gracefulShutdownRegistered = false;
+    return this;
+  }
+  /**
   * Destroy all active connections (gracefully if possible).
   * If a connection does not close cleanly, it will be force-destroyed.
   */
@@ -1456,32 +1606,56 @@ var ExpressServer = class {
     ];
     await Promise.allSettled(sockets.map((socket) => new Promise((resolve) => {
       socket.end();
-      const timer = setTimeout(() => {
-        socket.destroy();
-        resolve();
-      }, 1e3);
-      socket.once("close", () => {
-        clearTimeout(timer);
+      let timer;
+      const cleanup = /* @__PURE__ */ __name(() => {
+        if (timer) clearTimeout(timer);
+        socket.removeListener("close", onClose);
+        socket.removeListener("error", onError);
         resolve();
-      });
-      socket.once("error", () => {
-        clearTimeout(timer);
+      }, "cleanup");
+      const onClose = /* @__PURE__ */ __name(() => cleanup(), "onClose");
+      const onError = /* @__PURE__ */ __name(() => {
         socket.destroy();
-        resolve();
-      });
+        cleanup();
+      }, "onError");
+      timer = setTimeout(() => {
+        socket.destroy();
+        cleanup();
+      }, 1e3);
+      socket.once("close", onClose);
+      socket.once("error", onError);
     })));
     this.connections.clear();
     getLogger().info(`Closed ${sockets.length} active connection(s)`);
   }
   /**
-  * Set an externally created base router.
-  * This will override the internal rootRouter.
+  * Mount a base router onto the server's root router.
+  *
+  * Note: This attaches the supplied router to the root router pipeline.
+  * Duplicate mounting of the same router instance is ignored.
+  *
+  * @param router The Express router instance to mount
+  * @returns This instance for method chaining
   */
-  setBaseRouter(router) {
-    this.externalRouter = router;
+  addBaseRouter(router) {
+    if (this.mountedRouters.has(router)) {
+      return this;
+    }
+    this.mountedRouters.add(router);
+    this.rootRouter.use(router);
     return this;
   }
   /**
+  * Alias for `addBaseRouter` (maintained for backward compatibility).
+  * Mounts the supplied router onto the server's root router.
+  *
+  * @param router The Express router instance to mount
+  * @returns This instance for method chaining
+  */
+  setBaseRouter(router) {
+    return this.addBaseRouter(router);
+  }
+  /**
   * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).
   */
   createRouter(prefix = "") {
@@ -1501,27 +1675,73 @@ var ExpressServer = class {
   */
   registerRoute(methods, path, ...handlers) {
     const fullPath = this.normalizePath(path, true);
-    const routerToUse = this.externalRouter || this.rootRouter;
-    const methodMap = {
-      get: routerToUse.get.bind(routerToUse),
-      post: routerToUse.post.bind(routerToUse),
-      put: routerToUse.put.bind(routerToUse),
-      delete: routerToUse.delete.bind(routerToUse),
-      patch: routerToUse.patch.bind(routerToUse),
-      options: routerToUse.options.bind(routerToUse),
-      head: routerToUse.head.bind(routerToUse)
-    };
+    const routerToUse = this.rootRouter;
     methods.forEach((m) => {
-      const fn = methodMap[m];
-      if (fn) {
-        fn(fullPath, ...handlers);
-      } else {
+      const method = m.toLowerCase();
+      if (!SUPPORTED_HTTP_METHODS.has(method) || typeof routerToUse[method] !== "function") {
         throw new Error(`Unsupported HTTP method: ${m}`);
       }
+      routerToUse[method](fullPath, ...handlers);
     });
     return this;
   }
   /**
+  * Register a GET route handler.
+  */
+  get(path, ...handlers) {
+    return this.registerRoute([
+      "get"
+    ], path, ...handlers);
+  }
+  /**
+  * Register a POST route handler.
+  */
+  post(path, ...handlers) {
+    return this.registerRoute([
+      "post"
+    ], path, ...handlers);
+  }
+  /**
+  * Register a PUT route handler.
+  */
+  put(path, ...handlers) {
+    return this.registerRoute([
+      "put"
+    ], path, ...handlers);
+  }
+  /**
+  * Register a DELETE route handler.
+  */
+  delete(path, ...handlers) {
+    return this.registerRoute([
+      "delete"
+    ], path, ...handlers);
+  }
+  /**
+  * Register a PATCH route handler.
+  */
+  patch(path, ...handlers) {
+    return this.registerRoute([
+      "patch"
+    ], path, ...handlers);
+  }
+  /**
+  * Register an OPTIONS route handler.
+  */
+  options(path, ...handlers) {
+    return this.registerRoute([
+      "options"
+    ], path, ...handlers);
+  }
+  /**
+  * Register a HEAD route handler.
+  */
+  head(path, ...handlers) {
+    return this.registerRoute([
+      "head"
+    ], path, ...handlers);
+  }
+  /**
   * Register custom middleware with optional path restriction.
   *
   * Use this for:
@@ -1535,7 +1755,7 @@ var ExpressServer = class {
   * @returns This instance for method chaining
   */
   registerMiddleware(path, middleware) {
-    const routerToUse = this.externalRouter || this.rootRouter;
+    const routerToUse = this.rootRouter;
     if (typeof path === "string") {
       const normalizedPath = this.normalizePath(path);
       if (normalizedPath) {
@@ -1558,7 +1778,7 @@ var ExpressServer = class {
   */
   useMiddleware(...middlewares) {
     middlewares.forEach((middleware) => {
-      (this.externalRouter || this.rootRouter).use(middleware);
+      this.rootRouter.use(middleware);
     });
     return this;
   }