@catbee/utils 2.2.0 → 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,28 @@ 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).
+  *
+  * @returns This instance for method chaining
+  */
+  markStartupComplete() {
+    healthzServer.HealthzServer.markStartupComplete();
+    return this;
+  }
+  /**
+  * Whether application startup has completed on the Healthz probe server.
+  */
+  isStartupComplete() {
+    if (this.isHealthzServerEnabled()) {
+      return healthzServer.HealthzServer.isStartupComplete();
+    }
+    return this.isRunning();
   }
   /**
   * Get the running HealthzServer instance (if started).
@@ -1248,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.
@@ -1305,92 +1414,108 @@ var ExpressServer = class {
   */
   async doStart() {
     await this.initPromise;
-    await this.runHook("beforeStart", this.app);
-    const server = this.createServerInstance();
-    this.server = server;
-    return new Promise((resolve, reject) => {
-      let isListening = false;
-      server.on("error", (err) => {
-        if (!isListening) {
-          logger.getLogger().error({
-            err
-          }, "Server failed to start");
-          try {
-            server.removeAllListeners();
-            server.close();
-            if (healthzServer.HealthzServer.isStarted()) {
-              healthzServer.HealthzServer.stop().catch(() => {
-              });
-            }
-          } catch {
-          }
-          this.server = null;
-          this.connections.clear();
-          reject(err);
-        } else {
-          logger.getLogger().error({
-            err
-          }, "Server runtime error");
-        }
-      });
-      this.setupConnectionTracking();
-      Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
-        const onListening = /* @__PURE__ */ __name(async () => {
-          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.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.HealthzServer.setReady(true);
-            }
-            isListening = true;
-            resolve(server);
-          } catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
+    if (this.isHealthzServerEnabled()) {
+      const healthzConfig = {
+        ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
+        handleSignals: false,
+        checks: [
+          ...this.healthzChecks
+        ],
+        ...this.hasExplicitReadinessChecks ? {
+          readinessChecks: [
+            ...this.healthzReadinessChecks
+          ]
+        } : {}
+      };
+      const addr = await healthzServer.HealthzServer.start(healthzConfig);
+      if (!addr) {
+        throw new Error("Healthz probe server failed to start (already running in this process)");
+      }
+      this.healthzAddress = addr;
+    }
+    try {
+      await this.runHook("beforeStart", this.app);
+      const server = this.createServerInstance();
+      this.server = server;
+      return await new Promise((resolve, reject) => {
+        let isListening = false;
+        server.on("error", async (err) => {
+          if (!isListening) {
             logger.getLogger().error({
-              err: error
-            }, "Server startup failed");
-            if (healthzServer.HealthzServer.isStarted()) {
-              await healthzServer.HealthzServer.stop().catch(() => {
-              });
-            }
+              err
+            }, "Server failed to start");
             try {
               server.removeAllListeners();
               server.close();
+              if (healthzServer.HealthzServer.isRunning()) {
+                await healthzServer.HealthzServer.stop().catch(() => {
+                });
+              }
             } catch {
             }
             this.server = null;
             this.healthzAddress = null;
             this.connections.clear();
-            reject(error);
+            reject(err);
+          } else {
+            logger.getLogger().error({
+              err
+            }, "Server runtime error");
           }
-        }, "onListening");
-        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)));
+        });
+        this.setupConnectionTracking();
+        Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
+          const onListening = /* @__PURE__ */ __name(async () => {
+            try {
+              this.logServerStartInfo();
+              await this.runHook("afterStart", server);
+              this.internalReady = true;
+              if (this.isHealthzServerEnabled()) {
+                healthzServer.HealthzServer.markStartupComplete();
+                healthzServer.HealthzServer.setReady(true);
+              }
+              isListening = true;
+              resolve(server);
+            } catch (err) {
+              const error = err instanceof Error ? err : new Error(String(err));
+              logger.getLogger().error({
+                err: error
+              }, "Server startup failed");
+              if (healthzServer.HealthzServer.isRunning()) {
+                await healthzServer.HealthzServer.stop().catch(() => {
+                });
+              }
+              try {
+                server.removeAllListeners();
+                server.close();
+              } catch {
+              }
+              this.server = null;
+              this.healthzAddress = null;
+              this.connections.clear();
+              reject(error);
+            }
+          }, "onListening");
+          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)));
+        });
       });
-    });
+    } catch (err) {
+      if (healthzServer.HealthzServer.isRunning()) {
+        await healthzServer.HealthzServer.stop().catch(() => {
+        });
+      }
+      this.healthzAddress = null;
+      this.server = null;
+      this.connections.clear();
+      throw err;
+    }
   }
   /**
   * Create HTTP or HTTPS server instance (without listening).
@@ -1431,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)}`);
@@ -1454,16 +1580,26 @@ var ExpressServer = class {
   * - Monitoring systems are notified
   */
   async stop(force = false) {
-    if (!this.server && !healthzServer.HealthzServer.isStarted()) {
+    if (!this.server && !healthzServer.HealthzServer.isRunning()) {
       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;
-    if (healthzServer.HealthzServer.isStarted()) {
+  }
+  /**
+  * Internal implementation of server shutdown.
+  */
+  async doStop(force = false) {
+    this.internalReady = false;
+    if (healthzServer.HealthzServer.isRunning()) {
       healthzServer.HealthzServer.setReady(false);
     }
     if (this.server) {
@@ -1471,19 +1607,23 @@ var ExpressServer = class {
     }
     try {
       const shutdownDelay = this.getHealthzShutdownDelay();
-      if (shutdownDelay > 0 && !force && healthzServer.HealthzServer.isStarted()) {
+      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);
       }
     } finally {
-      if (healthzServer.HealthzServer.isStarted()) {
+      if (healthzServer.HealthzServer.isRunning()) {
         await healthzServer.HealthzServer.stop();
         this.healthzAddress = null;
       }
       this.isShuttingDown = false;
+      this.isDraining = false;
     }
   }
   /**
@@ -1570,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");
@@ -1931,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.
      *
@@ -237,6 +286,16 @@ declare class ExpressServer {
      * Whether the service is currently marked as ready for traffic on the Healthz probe server.
      */
     isReady(): boolean;
+    /**
+     * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
+     *
+     * @returns This instance for method chaining
+     */
+    markStartupComplete(): this;
+    /**
+     * Whether application startup has completed on the Healthz probe server.
+     */
+    isStartupComplete(): boolean;
     /**
      * Get the running HealthzServer instance (if started).
      */
@@ -317,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.
      */