@catbee/utils 2.1.1 → 2.2.1

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 healthzServer = require('@catbee/utils/healthz-server');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -307,36 +308,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 = object.isPlainObject(this.config.healthzServer) ? object.deepClone(this.config.healthzServer) : {};
+      this.config.healthzServer = object.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.
@@ -726,11 +744,12 @@ var ExpressServer = class {
   gracefulShutdownRegistered = false;
   /** Map of registered signal listeners for clean teardown */
   signalListeners = /* @__PURE__ */ new Map();
-  /**
-  * Collection of registered health check functions.
-  * These are executed when the health check endpoint is accessed.
-  */
-  healthChecks = [];
+  /** 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 */
@@ -765,8 +784,19 @@ var ExpressServer = class {
       logger.getLogger().error(msg);
       throw new Error(msg);
     }
-    if (config$1?.healthCheck?.checks) {
-      this.healthChecks.push(...config$1.healthCheck.checks);
+    if (typeof this.config.healthzServer === "boolean") {
+      this.config.healthzServer = {
+        ...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;
@@ -1114,10 +1144,6 @@ 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);
-    });
     this.app.use(this.globalPrefix, this.rootRouter);
     await this.runHook("afterRoutes", this.app);
     this.app.use((req, res) => {
@@ -1141,60 +1167,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 || config.getCatbeeServerGlobalConfig().skipHealthzChecksValidation) {
-        return res.status(httpStatusCodes.HttpStatusCodes.OK).json(new response.SuccessResponse("OK"));
-      }
-      const results = await this.executeHealthChecks();
-      const allOk = results.every((r) => r.status);
-      const status = allOk ? httpStatusCodes.HttpStatusCodes.OK : httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE;
-      const response$1 = new response.SuccessResponse(allOk ? "OK" : "Service unavailable");
-      if (!allOk) response$1.error = true;
-      if (this.config.healthCheck?.detailed) response$1.data = {
-        checks: results
-      };
-      return res.status(status).json(response$1);
-    } catch {
-      return res.status(httpStatusCodes.HttpStatusCodes.INTERNAL_SERVER_ERROR).json(new exception.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
@@ -1203,33 +1194,76 @@ 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.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 || config.getCatbeeServerGlobalConfig().skipHealthzChecksValidation) return true;
-      const results = await this.executeHealthChecks();
-      return results.every((r) => r.status === true);
-    } catch (err) {
-      logger.getLogger().error({
-        err
-      }, "Error while running readiness checks");
-      return false;
-    }
+  setReady(ready) {
+    healthzServer.HealthzServer.setReady(ready);
+    return this;
+  }
+  /**
+  * Whether the service is currently marked as ready for traffic on the Healthz probe server.
+  */
+  isReady() {
+    return healthzServer.HealthzServer.isReady();
+  }
+  /**
+  * 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() {
+    return healthzServer.HealthzServer.isStartupComplete();
+  }
+  /**
+  * Get the running HealthzServer instance (if started).
+  */
+  getHealthzServer() {
+    return healthzServer.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.HealthzServer.isReady();
   }
   /**
   * Get the underlying Express application instance.
@@ -1286,48 +1320,105 @@ 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();
-          } catch {
+    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;
+    }
+    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
+            }, "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(err);
+          } else {
+            logger.getLogger().error({
+              err
+            }, "Server runtime error");
           }
-          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 () => {
-          isListening = true;
-          this.logServerStartInfo();
-          await this.runHook("afterStart", server);
-          resolve(server);
-        }, "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);
+              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).
@@ -1367,8 +1458,8 @@ var ExpressServer = class {
     const host = this.formatHostForUrl(this.config.host || "localhost");
     const url = `${protocol}://${host}:${port}`;
     logger.getLogger().info(`Server running on ${url}`);
-    if (this.config.healthCheck && this.config.healthCheck?.path) {
-      logger.getLogger().info(`Health check available at ${url}${this.normalizePath(this.config.healthCheck.path, this.config.healthCheck.withGlobalPrefix)}`);
+    if (this.healthzAddress) {
+      logger.getLogger().info(`Healthz probe server running on http://${this.healthzAddress.address}:${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)}`);
@@ -1391,7 +1482,7 @@ var ExpressServer = class {
   * - Monitoring systems are notified
   */
   async stop(force = false) {
-    if (!this.server) {
+    if (!this.server && !healthzServer.HealthzServer.isRunning()) {
       logger.getLogger().warn("Stop called but server is not running");
       return;
     }
@@ -1400,10 +1491,26 @@ var ExpressServer = class {
       return;
     }
     this.isShuttingDown = true;
-    await this.runHook("beforeStop", this.server);
+    if (healthzServer.HealthzServer.isRunning()) {
+      healthzServer.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.HealthzServer.isRunning()) {
+        logger.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.HealthzServer.isRunning()) {
+        await healthzServer.HealthzServer.stop();
+        this.healthzAddress = null;
+      }
       this.isShuttingDown = false;
     }
   }
@@ -1492,7 +1599,7 @@ var ExpressServer = class {
         logger.getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
         try {
           this.disableGracefulShutdown();
-          await this.stop(true);
+          await this.stop(false);
           process.exit(0);
         } catch (err) {
           logger.getLogger().fatal({

package/server/index.d.ts

@@ -26,6 +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';
 
 /**
  * Map of critical dependencies to their error messages.
@@ -76,11 +77,12 @@ declare class ExpressServer {
     private gracefulShutdownRegistered;
     /** Map of registered signal listeners for clean teardown */
     private readonly signalListeners;
-    /**
-     * Collection of registered health check functions.
-     * These are executed when the health check endpoint is accessed.
-     */
-    private readonly healthChecks;
+    /** Running address info for the Healthz probe server */
+    private healthzAddress?;
+    /** Named checks queued for Healthz liveness probe */
+    private readonly healthzChecks;
+    /** Named checks queued for Healthz readiness probe */
+    private readonly healthzReadinessChecks;
     /** Promise that resolves when initialization (middleware + routes) is complete */
     private readonly initPromise;
     /** In-flight start promise to protect against concurrent start() calls */
@@ -197,18 +199,18 @@ declare class ExpressServer {
      */
     protected setupRoutes(): Promise<void>;
     /**
-     * Execute health check and return response.
+     * Whether the Healthz probe server is enabled.
      */
-    private handleHealthCheckRequest;
+    isHealthzServerEnabled(): boolean;
     /**
-     * Execute all registered health checks and return results.
+     * Get the graceful shutdown delay in milliseconds configured for HealthzServer.
      */
-    private executeHealthChecks;
+    private getHealthzShutdownDelay;
     /**
-     * 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
@@ -217,17 +219,49 @@ declare class ExpressServer {
      * - 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: string, check: (signal?: AbortSignal) => Promise<boolean> | boolean, options?: 'readiness' | 'liveness' | 'both' | {
+        type?: 'readiness' | 'liveness' | 'both';
+    }): this;
+    /**
+     * 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: boolean): this;
+    /**
+     * 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
      */
-    registerHealthCheck(name: string, check: () => Promise<boolean> | boolean): this;
+    markStartupComplete(): this;
     /**
-     * Run registered health checks and return whether the service is ready.
-     * Useful for readiness probes in deployment tooling.
+     * Whether application startup has completed on the Healthz probe server.
+     */
+    isStartupComplete(): boolean;
+    /**
+     * Get the running HealthzServer instance (if started).
+     */
+    getHealthzServer(): HealthzServer | undefined;
+    /**
+     * Get the address info of the running HealthzServer (if started).
+     */
+    getHealthzAddress(): HealthzAddressInfo | null | undefined;
+    /**
+     * Returns whether the service is currently marked as ready for traffic on the Healthz probe server.
+     * Useful for readiness checks in deployment tooling.
      *
-     * @returns Promise resolving to `true` when all checks pass, otherwise `false`.
+     * @returns `true` when ready, otherwise `false`.
      */
-    ready(): Promise<boolean>;
+    ready(): boolean;
     /**
      * Get the underlying Express application instance.
      * Use this for advanced Express features not exposed by this wrapper.
@@ -715,32 +749,36 @@ declare class ServerConfigBuilder {
      */
     disableRequestLogging(): this;
     /**
-     * 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: Partial<NonNullable<CatbeeServerConfig['healthCheck']>>): this;
+    withHealthzServer(opts: NonNullable<CatbeeServerConfig['healthzServer']>): 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?: Partial<CatbeeHealthzServerConfig>): this;
+    /**
+     * Disables the dedicated Healthz probe HTTP server.
      *
-     * @example
-     * ```typescript
-     * builder.disableHealthCheck()
-     * ```
+     * @returns The builder instance for chaining
      */
-    disableHealthCheck(): this;
+    disableHealthzServer(): this;
     /**
      * Configures OpenAPI/Swagger documentation for the API.
      *