@catbee/utils 2.2.1 → 2.3.0

package/server/index.cjs

@@ -39,6 +39,7 @@ var fs = require('@catbee/utils/fs');
 var validation = require('@catbee/utils/validation');
 var async = require('@catbee/utils/async');
 var id = require('@catbee/utils/id');
+var string = require('@catbee/utils/string');
 var healthzServer = require('@catbee/utils/healthz-server');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -738,8 +739,12 @@ var ExpressServer = class {
   app;
   /** Set of active WebSocket connections */
   connections = /* @__PURE__ */ new Set();
-  /** Flag indicating if the server is shutting down */
+  /** Flag indicating if the server is shutting down (rejects traffic with 503) */
   isShuttingDown = false;
+  /** Flag indicating if the server is in graceful drain delay (sets Connection: close while servicing traffic) */
+  isDraining = false;
+  /** Internal readiness state (used when HealthzServer is not enabled) */
+  internalReady = false;
   /** Flag indicating if graceful shutdown handlers are registered */
   gracefulShutdownRegistered = false;
   /** Map of registered signal listeners for clean teardown */
@@ -750,10 +755,14 @@ var ExpressServer = class {
   healthzChecks = [];
   /** Named checks queued for Healthz readiness probe */
   healthzReadinessChecks = [];
+  /** Whether readiness checks were explicitly provided or registered */
+  hasExplicitReadinessChecks = false;
   /** Promise that resolves when initialization (middleware + routes) is complete */
   initPromise;
   /** In-flight start promise to protect against concurrent start() calls */
   startPromise;
+  /** In-flight stop promise to protect against concurrent stop() calls */
+  stopPromise;
   /**
   * Initializes server with intelligent defaults and security best practices.
   * All settings can be customized via config and hooks.
@@ -794,7 +803,8 @@ var ExpressServer = class {
       if (this.config.healthzServer.checks) {
         this.healthzChecks.push(...this.config.healthzServer.checks);
       }
-      if (this.config.healthzServer.readinessChecks) {
+      if (this.config.healthzServer.readinessChecks !== void 0) {
+        this.hasExplicitReadinessChecks = true;
         this.healthzReadinessChecks.push(...this.config.healthzServer.readinessChecks);
       }
     }
@@ -892,6 +902,9 @@ var ExpressServer = class {
         res.status(httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE).json(new exception.ServiceUnavailableException("Server is shutting down"));
         return;
       }
+      if (this.isDraining) {
+        res.setHeader("Connection", "close");
+      }
       next();
     });
   }
@@ -1205,21 +1218,96 @@ var ExpressServer = class {
       check
     };
     if (probeType === "liveness" || probeType === "both") {
-      this.healthzChecks.push(namedCheck);
+      const idx = this.healthzChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) {
+        this.healthzChecks[idx] = namedCheck;
+      } else {
+        this.healthzChecks.push(namedCheck);
+      }
     }
     if (probeType === "readiness" || probeType === "both") {
-      this.healthzReadinessChecks.push(namedCheck);
+      this.hasExplicitReadinessChecks = true;
+      const idx = this.healthzReadinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) {
+        this.healthzReadinessChecks[idx] = namedCheck;
+      } else {
+        this.healthzReadinessChecks.push(namedCheck);
+      }
     }
     healthzServer.HealthzServer.registerCheck(namedCheck, probeType);
     return this;
   }
   /**
+  * Unregister a health check by name.
+  *
+  * @param name Name of the check to remove
+  * @param options Target probe type ('readiness' | 'liveness' | 'both') or options object
+  * @returns This instance for method chaining
+  */
+  unregisterHealthCheck(name, options) {
+    const probeType = typeof options === "string" ? options : options?.type ?? "both";
+    if (probeType === "liveness" || probeType === "both") {
+      const idx = this.healthzChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.healthzChecks.splice(idx, 1);
+    }
+    if (probeType === "readiness" || probeType === "both") {
+      const idx = this.healthzReadinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.healthzReadinessChecks.splice(idx, 1);
+    }
+    healthzServer.HealthzServer.unregisterCheck(name, probeType);
+    return this;
+  }
+  /**
+  * Get all registered Healthz checks queued for this Express server.
+  */
+  getHealthzChecks() {
+    return {
+      liveness: [
+        ...this.healthzChecks
+      ],
+      readiness: [
+        ...this.healthzReadinessChecks
+      ]
+    };
+  }
+  /**
+  * Register a readiness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerReadinessCheck(name, check) {
+    return this.registerHealthCheck(name, check, "readiness");
+  }
+  /**
+  * Register a liveness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerLivenessCheck(name, check) {
+    return this.registerHealthCheck(name, check, "liveness");
+  }
+  /**
+  * Register a readiness and liveness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerReadinessAndLivenessChecks(name, check) {
+    return this.registerHealthCheck(name, check, "both");
+  }
+  /**
   * Mark the service as ready / not-ready for traffic on the Healthz probe server.
   *
   * @param ready Whether the service is ready to receive traffic
   * @returns This instance for method chaining
   */
   setReady(ready) {
+    this.internalReady = ready;
     healthzServer.HealthzServer.setReady(ready);
     return this;
   }
@@ -1227,7 +1315,10 @@ var ExpressServer = class {
   * Whether the service is currently marked as ready for traffic on the Healthz probe server.
   */
   isReady() {
-    return healthzServer.HealthzServer.isReady();
+    if (this.isHealthzServerEnabled()) {
+      return healthzServer.HealthzServer.isReady();
+    }
+    return this.internalReady && this.isRunning();
   }
   /**
   * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
@@ -1242,7 +1333,10 @@ var ExpressServer = class {
   * Whether application startup has completed on the Healthz probe server.
   */
   isStartupComplete() {
-    return healthzServer.HealthzServer.isStartupComplete();
+    if (this.isHealthzServerEnabled()) {
+      return healthzServer.HealthzServer.isStartupComplete();
+    }
+    return this.isRunning();
   }
   /**
   * Get the running HealthzServer instance (if started).
@@ -1263,7 +1357,7 @@ var ExpressServer = class {
   * @returns `true` when ready, otherwise `false`.
   */
   ready() {
-    return healthzServer.HealthzServer.isReady();
+    return this.isReady();
   }
   /**
   * Get the underlying Express application instance.
@@ -1327,9 +1421,11 @@ var ExpressServer = class {
         checks: [
           ...this.healthzChecks
         ],
-        readinessChecks: [
-          ...this.healthzReadinessChecks
-        ]
+        ...this.hasExplicitReadinessChecks ? {
+          readinessChecks: [
+            ...this.healthzReadinessChecks
+          ]
+        } : {}
       };
       const addr = await healthzServer.HealthzServer.start(healthzConfig);
       if (!addr) {
@@ -1373,6 +1469,7 @@ var ExpressServer = class {
             try {
               this.logServerStartInfo();
               await this.runHook("afterStart", server);
+              this.internalReady = true;
               if (this.isHealthzServerEnabled()) {
                 healthzServer.HealthzServer.markStartupComplete();
                 healthzServer.HealthzServer.setReady(true);
@@ -1459,7 +1556,8 @@ var ExpressServer = class {
     const url = `${protocol}://${host}:${port}`;
     logger.getLogger().info(`Server running on ${url}`);
     if (this.healthzAddress) {
-      logger.getLogger().info(`Healthz probe server running on http://${this.healthzAddress.address}:${this.healthzAddress.port}`);
+      const healthzHost = this.formatHostForUrl(this.healthzAddress.address);
+      logger.getLogger().info(`Healthz server running on http://${healthzHost}:${this.healthzAddress.port}`);
     }
     if (this.config.openApi?.enable) {
       logger.getLogger().info(`API docs available at ${url}${this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)}`);
@@ -1486,11 +1584,21 @@ var ExpressServer = class {
       logger.getLogger().warn("Stop called but server is not running");
       return;
     }
-    if (this.isShuttingDown) {
-      logger.getLogger().warn("Shutdown already in progress");
-      return;
+    if (this.stopPromise) {
+      return this.stopPromise;
+    }
+    this.stopPromise = this.doStop(force);
+    try {
+      await this.stopPromise;
+    } finally {
+      this.stopPromise = void 0;
     }
-    this.isShuttingDown = true;
+  }
+  /**
+  * Internal implementation of server shutdown.
+  */
+  async doStop(force = false) {
+    this.internalReady = false;
     if (healthzServer.HealthzServer.isRunning()) {
       healthzServer.HealthzServer.setReady(false);
     }
@@ -1501,8 +1609,11 @@ var ExpressServer = class {
       const shutdownDelay = this.getHealthzShutdownDelay();
       if (shutdownDelay > 0 && !force && healthzServer.HealthzServer.isRunning()) {
         logger.getLogger().info(`Waiting ${shutdownDelay}ms for load balancer to drain traffic...`);
+        this.isDraining = true;
         await new Promise((resolve) => setTimeout(resolve, shutdownDelay));
       }
+      this.isDraining = false;
+      this.isShuttingDown = true;
       if (this.server) {
         await this.gracefulShutdown(force);
       }
@@ -1512,6 +1623,7 @@ var ExpressServer = class {
         this.healthzAddress = null;
       }
       this.isShuttingDown = false;
+      this.isDraining = false;
     }
   }
   /**
@@ -1598,10 +1710,11 @@ var ExpressServer = class {
         signalHandled = true;
         logger.getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
         try {
-          this.disableGracefulShutdown();
           await this.stop(false);
+          this.disableGracefulShutdown();
           process.exit(0);
         } catch (err) {
+          this.disableGracefulShutdown();
           logger.getLogger().fatal({
             err
           }, "Shutdown failed");
@@ -1959,7 +2072,8 @@ var ExpressServer = class {
   }
   normalizePath(path, withGlobalPrefix = false) {
     const sanitize = /* @__PURE__ */ __name((p) => {
-      return "/" + p.trim().replace(/^\/+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+      const inner = string.trimChars(p.trim(), "/");
+      return inner ? "/" + inner.replace(/\/{2,}/g, "/") : "/";
     }, "sanitize");
     const prefix = withGlobalPrefix && this.globalPrefix ? sanitize(this.globalPrefix) : "";
     if (typeof path !== "string" || !path.trim()) {

package/server/index.d.ts

@@ -26,7 +26,7 @@ import express, { Express, Router } from 'express';
 import http from 'node:http';
 import https from 'node:https';
 import { CatbeeServerConfig, CatbeeServerHooks } from '@catbee/utils/types';
-import { HealthzServer, HealthzAddressInfo, CatbeeHealthzServerConfig } from '@catbee/utils/healthz-server';
+import { NamedCheck, HealthzServer, HealthzAddressInfo, CatbeeHealthzServerConfig } from '@catbee/utils/healthz-server';
 
 /**
  * Map of critical dependencies to their error messages.
@@ -71,8 +71,12 @@ declare class ExpressServer {
     private readonly app;
     /** Set of active WebSocket connections */
     private readonly connections;
-    /** Flag indicating if the server is shutting down */
+    /** Flag indicating if the server is shutting down (rejects traffic with 503) */
     private isShuttingDown;
+    /** Flag indicating if the server is in graceful drain delay (sets Connection: close while servicing traffic) */
+    private isDraining;
+    /** Internal readiness state (used when HealthzServer is not enabled) */
+    private internalReady;
     /** Flag indicating if graceful shutdown handlers are registered */
     private gracefulShutdownRegistered;
     /** Map of registered signal listeners for clean teardown */
@@ -83,10 +87,14 @@ declare class ExpressServer {
     private readonly healthzChecks;
     /** Named checks queued for Healthz readiness probe */
     private readonly healthzReadinessChecks;
+    /** Whether readiness checks were explicitly provided or registered */
+    private hasExplicitReadinessChecks;
     /** Promise that resolves when initialization (middleware + routes) is complete */
     private readonly initPromise;
     /** In-flight start promise to protect against concurrent start() calls */
     private startPromise?;
+    /** In-flight stop promise to protect against concurrent stop() calls */
+    private stopPromise?;
     /**
      * Initializes server with intelligent defaults and security best practices.
      * All settings can be customized via config and hooks.
@@ -223,9 +231,50 @@ declare class ExpressServer {
      * @param options Target probe type ('readiness' | 'liveness' | 'both') or options object
      * @returns This instance for method chaining
      */
-    registerHealthCheck(name: string, check: (signal?: AbortSignal) => Promise<boolean> | boolean, options?: 'readiness' | 'liveness' | 'both' | {
+    registerHealthCheck(name: string, check: (signal?: AbortSignal) => Promise<boolean | void> | boolean | void, options?: 'readiness' | 'liveness' | 'both' | {
         type?: 'readiness' | 'liveness' | 'both';
     }): this;
+    /**
+     * Unregister a health check by name.
+     *
+     * @param name Name of the check to remove
+     * @param options Target probe type ('readiness' | 'liveness' | 'both') or options object
+     * @returns This instance for method chaining
+     */
+    unregisterHealthCheck(name: string, options?: 'readiness' | 'liveness' | 'both' | {
+        type?: 'readiness' | 'liveness' | 'both';
+    }): this;
+    /**
+     * Get all registered Healthz checks queued for this Express server.
+     */
+    getHealthzChecks(): {
+        liveness: NamedCheck[];
+        readiness: NamedCheck[];
+    };
+    /**
+     * Register a readiness health check.
+     *
+     * @param name Unique identifier for the check (used in detailed responses)
+     * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+     * @returns This instance for method chaining
+     */
+    registerReadinessCheck(name: string, check: (signal?: AbortSignal) => Promise<boolean | void> | boolean | void): this;
+    /**
+     * Register a liveness health check.
+     *
+     * @param name Unique identifier for the check (used in detailed responses)
+     * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+     * @returns This instance for method chaining
+     */
+    registerLivenessCheck(name: string, check: (signal?: AbortSignal) => Promise<boolean | void> | boolean | void): this;
+    /**
+     * Register a readiness and liveness health check.
+     *
+     * @param name Unique identifier for the check (used in detailed responses)
+     * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+     * @returns This instance for method chaining
+     */
+    registerReadinessAndLivenessChecks(name: string, check: (signal?: AbortSignal) => Promise<boolean | void> | boolean | void): this;
     /**
      * Mark the service as ready / not-ready for traffic on the Healthz probe server.
      *
@@ -327,6 +376,10 @@ declare class ExpressServer {
      * - Monitoring systems are notified
      */
     stop(force?: boolean): Promise<void>;
+    /**
+     * Internal implementation of server shutdown.
+     */
+    private doStop;
     /**
      * Perform graceful server shutdown with timeout.
      */

package/server/index.mjs

@@ -37,6 +37,7 @@ 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 { trimChars } from '@catbee/utils/string';
 import { HealthzServer } from '@catbee/utils/healthz-server';
 
 var __defProp = Object.defineProperty;
@@ -730,8 +731,12 @@ var ExpressServer = class {
   app;
   /** Set of active WebSocket connections */
   connections = /* @__PURE__ */ new Set();
-  /** Flag indicating if the server is shutting down */
+  /** Flag indicating if the server is shutting down (rejects traffic with 503) */
   isShuttingDown = false;
+  /** Flag indicating if the server is in graceful drain delay (sets Connection: close while servicing traffic) */
+  isDraining = false;
+  /** Internal readiness state (used when HealthzServer is not enabled) */
+  internalReady = false;
   /** Flag indicating if graceful shutdown handlers are registered */
   gracefulShutdownRegistered = false;
   /** Map of registered signal listeners for clean teardown */
@@ -742,10 +747,14 @@ var ExpressServer = class {
   healthzChecks = [];
   /** Named checks queued for Healthz readiness probe */
   healthzReadinessChecks = [];
+  /** Whether readiness checks were explicitly provided or registered */
+  hasExplicitReadinessChecks = false;
   /** Promise that resolves when initialization (middleware + routes) is complete */
   initPromise;
   /** In-flight start promise to protect against concurrent start() calls */
   startPromise;
+  /** In-flight stop promise to protect against concurrent stop() calls */
+  stopPromise;
   /**
   * Initializes server with intelligent defaults and security best practices.
   * All settings can be customized via config and hooks.
@@ -786,7 +795,8 @@ var ExpressServer = class {
       if (this.config.healthzServer.checks) {
         this.healthzChecks.push(...this.config.healthzServer.checks);
       }
-      if (this.config.healthzServer.readinessChecks) {
+      if (this.config.healthzServer.readinessChecks !== void 0) {
+        this.hasExplicitReadinessChecks = true;
         this.healthzReadinessChecks.push(...this.config.healthzServer.readinessChecks);
       }
     }
@@ -884,6 +894,9 @@ var ExpressServer = class {
         res.status(HttpStatusCodes.SERVICE_UNAVAILABLE).json(new ServiceUnavailableException("Server is shutting down"));
         return;
       }
+      if (this.isDraining) {
+        res.setHeader("Connection", "close");
+      }
       next();
     });
   }
@@ -1197,21 +1210,96 @@ var ExpressServer = class {
       check
     };
     if (probeType === "liveness" || probeType === "both") {
-      this.healthzChecks.push(namedCheck);
+      const idx = this.healthzChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) {
+        this.healthzChecks[idx] = namedCheck;
+      } else {
+        this.healthzChecks.push(namedCheck);
+      }
     }
     if (probeType === "readiness" || probeType === "both") {
-      this.healthzReadinessChecks.push(namedCheck);
+      this.hasExplicitReadinessChecks = true;
+      const idx = this.healthzReadinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) {
+        this.healthzReadinessChecks[idx] = namedCheck;
+      } else {
+        this.healthzReadinessChecks.push(namedCheck);
+      }
     }
     HealthzServer.registerCheck(namedCheck, probeType);
     return this;
   }
   /**
+  * Unregister a health check by name.
+  *
+  * @param name Name of the check to remove
+  * @param options Target probe type ('readiness' | 'liveness' | 'both') or options object
+  * @returns This instance for method chaining
+  */
+  unregisterHealthCheck(name, options) {
+    const probeType = typeof options === "string" ? options : options?.type ?? "both";
+    if (probeType === "liveness" || probeType === "both") {
+      const idx = this.healthzChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.healthzChecks.splice(idx, 1);
+    }
+    if (probeType === "readiness" || probeType === "both") {
+      const idx = this.healthzReadinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.healthzReadinessChecks.splice(idx, 1);
+    }
+    HealthzServer.unregisterCheck(name, probeType);
+    return this;
+  }
+  /**
+  * Get all registered Healthz checks queued for this Express server.
+  */
+  getHealthzChecks() {
+    return {
+      liveness: [
+        ...this.healthzChecks
+      ],
+      readiness: [
+        ...this.healthzReadinessChecks
+      ]
+    };
+  }
+  /**
+  * Register a readiness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerReadinessCheck(name, check) {
+    return this.registerHealthCheck(name, check, "readiness");
+  }
+  /**
+  * Register a liveness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerLivenessCheck(name, check) {
+    return this.registerHealthCheck(name, check, "liveness");
+  }
+  /**
+  * Register a readiness and liveness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerReadinessAndLivenessChecks(name, check) {
+    return this.registerHealthCheck(name, check, "both");
+  }
+  /**
   * Mark the service as ready / not-ready for traffic on the Healthz probe server.
   *
   * @param ready Whether the service is ready to receive traffic
   * @returns This instance for method chaining
   */
   setReady(ready) {
+    this.internalReady = ready;
     HealthzServer.setReady(ready);
     return this;
   }
@@ -1219,7 +1307,10 @@ var ExpressServer = class {
   * Whether the service is currently marked as ready for traffic on the Healthz probe server.
   */
   isReady() {
-    return HealthzServer.isReady();
+    if (this.isHealthzServerEnabled()) {
+      return HealthzServer.isReady();
+    }
+    return this.internalReady && this.isRunning();
   }
   /**
   * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
@@ -1234,7 +1325,10 @@ var ExpressServer = class {
   * Whether application startup has completed on the Healthz probe server.
   */
   isStartupComplete() {
-    return HealthzServer.isStartupComplete();
+    if (this.isHealthzServerEnabled()) {
+      return HealthzServer.isStartupComplete();
+    }
+    return this.isRunning();
   }
   /**
   * Get the running HealthzServer instance (if started).
@@ -1255,7 +1349,7 @@ var ExpressServer = class {
   * @returns `true` when ready, otherwise `false`.
   */
   ready() {
-    return HealthzServer.isReady();
+    return this.isReady();
   }
   /**
   * Get the underlying Express application instance.
@@ -1319,9 +1413,11 @@ var ExpressServer = class {
         checks: [
           ...this.healthzChecks
         ],
-        readinessChecks: [
-          ...this.healthzReadinessChecks
-        ]
+        ...this.hasExplicitReadinessChecks ? {
+          readinessChecks: [
+            ...this.healthzReadinessChecks
+          ]
+        } : {}
       };
       const addr = await HealthzServer.start(healthzConfig);
       if (!addr) {
@@ -1365,6 +1461,7 @@ var ExpressServer = class {
             try {
               this.logServerStartInfo();
               await this.runHook("afterStart", server);
+              this.internalReady = true;
               if (this.isHealthzServerEnabled()) {
                 HealthzServer.markStartupComplete();
                 HealthzServer.setReady(true);
@@ -1451,7 +1548,8 @@ var ExpressServer = class {
     const url = `${protocol}://${host}:${port}`;
     getLogger().info(`Server running on ${url}`);
     if (this.healthzAddress) {
-      getLogger().info(`Healthz probe server running on http://${this.healthzAddress.address}:${this.healthzAddress.port}`);
+      const healthzHost = this.formatHostForUrl(this.healthzAddress.address);
+      getLogger().info(`Healthz server running on http://${healthzHost}:${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)}`);
@@ -1478,11 +1576,21 @@ var ExpressServer = class {
       getLogger().warn("Stop called but server is not running");
       return;
     }
-    if (this.isShuttingDown) {
-      getLogger().warn("Shutdown already in progress");
-      return;
+    if (this.stopPromise) {
+      return this.stopPromise;
+    }
+    this.stopPromise = this.doStop(force);
+    try {
+      await this.stopPromise;
+    } finally {
+      this.stopPromise = void 0;
     }
-    this.isShuttingDown = true;
+  }
+  /**
+  * Internal implementation of server shutdown.
+  */
+  async doStop(force = false) {
+    this.internalReady = false;
     if (HealthzServer.isRunning()) {
       HealthzServer.setReady(false);
     }
@@ -1493,8 +1601,11 @@ var ExpressServer = class {
       const shutdownDelay = this.getHealthzShutdownDelay();
       if (shutdownDelay > 0 && !force && HealthzServer.isRunning()) {
         getLogger().info(`Waiting ${shutdownDelay}ms for load balancer to drain traffic...`);
+        this.isDraining = true;
         await new Promise((resolve) => setTimeout(resolve, shutdownDelay));
       }
+      this.isDraining = false;
+      this.isShuttingDown = true;
       if (this.server) {
         await this.gracefulShutdown(force);
       }
@@ -1504,6 +1615,7 @@ var ExpressServer = class {
         this.healthzAddress = null;
       }
       this.isShuttingDown = false;
+      this.isDraining = false;
     }
   }
   /**
@@ -1590,10 +1702,11 @@ var ExpressServer = class {
         signalHandled = true;
         getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
         try {
-          this.disableGracefulShutdown();
           await this.stop(false);
+          this.disableGracefulShutdown();
           process.exit(0);
         } catch (err) {
+          this.disableGracefulShutdown();
           getLogger().fatal({
             err
           }, "Shutdown failed");
@@ -1951,7 +2064,8 @@ var ExpressServer = class {
   }
   normalizePath(path, withGlobalPrefix = false) {
     const sanitize = /* @__PURE__ */ __name((p) => {
-      return "/" + p.trim().replace(/^\/+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+      const inner = trimChars(p.trim(), "/");
+      return inner ? "/" + inner.replace(/\/{2,}/g, "/") : "/";
     }, "sanitize");
     const prefix = withGlobalPrefix && this.globalPrefix ? sanitize(this.globalPrefix) : "";
     if (typeof path !== "string" || !path.trim()) {