@catbee/utils 2.0.5 → 2.2.0

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.
@@ -62,11 +63,11 @@ declare class ExpressServer {
     protected hooks: CatbeeServerHooks;
     /** Global API prefix (from config) */
     protected globalPrefix: string;
-    /** Internal fallback router */
+    /** Primary root router mounted to the application */
     private readonly rootRouter;
-    /** User-supplied router */
-    private externalRouter?;
-    /** Internal Express app instance */
+    /** Set of registered sub-routers to prevent duplicate mounting */
+    private readonly mountedRouters;
+    /** Express app instance */
     private readonly app;
     /** Set of active WebSocket connections */
     private readonly connections;
@@ -74,13 +75,18 @@ declare class ExpressServer {
     private isShuttingDown;
     /** Flag indicating if graceful shutdown handlers are registered */
     private gracefulShutdownRegistered;
-    /**
-     * Collection of registered health check functions.
-     * These are executed when the health check endpoint is accessed.
-     */
-    private readonly healthChecks;
+    /** Map of registered signal listeners for clean teardown */
+    private readonly signalListeners;
+    /** 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 */
+    private startPromise?;
     /**
      * Initializes server with intelligent defaults and security best practices.
      * All settings can be customized via config and hooks.
@@ -178,6 +184,10 @@ declare class ExpressServer {
      * Set up OpenAPI documentation middleware.
      */
     private setupOpenApiMiddleware;
+    /**
+     * Set up response preprocessing hook (applies global prefix if set).
+     */
+    private setupResponseHook;
     /**
      * Configure server routes and error handling.
      * Sets up in following order:
@@ -189,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
@@ -209,17 +219,39 @@ 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: () => Promise<boolean> | boolean): this;
+    registerHealthCheck(name: string, check: (signal?: AbortSignal) => Promise<boolean> | boolean, options?: 'readiness' | 'liveness' | 'both' | {
+        type?: 'readiness' | 'liveness' | 'both';
+    }): 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
      */
-    ready(): Promise<boolean>;
+    setReady(ready: boolean): this;
+    /**
+     * Whether the service is currently marked as ready for traffic on the Healthz probe server.
+     */
+    isReady(): 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 `true` when ready, otherwise `false`.
+     */
+    ready(): boolean;
     /**
      * Get the underlying Express application instance.
      * Use this for advanced Express features not exposed by this wrapper.
@@ -238,28 +270,32 @@ declare class ExpressServer {
      * 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
      */
     start(): Promise<http.Server | https.Server>;
     /**
-     * Create HTTP or HTTPS server instance.
+     * Internal implementation of server startup.
+     */
+    private doStart;
+    /**
+     * Create HTTP or HTTPS server instance (without listening).
      */
     private createServerInstance;
     /**
      * Set up connection tracking for graceful shutdown.
      */
     private setupConnectionTracking;
-    /**
-     * Set up error handling for server startup.
-     */
-    private setupServerErrorHandling;
     /**
      * Log server startup information.
      */
@@ -297,14 +333,32 @@ declare class ExpressServer {
      * @param signals Array of process signals to listen for (default: SIGINT, SIGTERM)
      */
     enableGracefulShutdown(signals?: NodeJS.Signals[]): this;
+    /**
+     * Unregister graceful shutdown signal listeners.
+     * Useful for testing and dynamic server lifecycles to prevent memory and listener leaks.
+     */
+    disableGracefulShutdown(): this;
     /**
      * Destroy all active connections (gracefully if possible).
      * If a connection does not close cleanly, it will be force-destroyed.
      */
     private destroyConnections;
     /**
-     * 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
+     */
+    addBaseRouter(router: Router): 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: Router): this;
     /**
@@ -321,6 +375,34 @@ declare class ExpressServer {
      * @returns This instance for method chaining
      */
     registerRoute(methods: Array<keyof Pick<Express, 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head'>>, path: string, ...handlers: Array<express.RequestHandler>): this;
+    /**
+     * Register a GET route handler.
+     */
+    get(path: string, ...handlers: express.RequestHandler[]): this;
+    /**
+     * Register a POST route handler.
+     */
+    post(path: string, ...handlers: express.RequestHandler[]): this;
+    /**
+     * Register a PUT route handler.
+     */
+    put(path: string, ...handlers: express.RequestHandler[]): this;
+    /**
+     * Register a DELETE route handler.
+     */
+    delete(path: string, ...handlers: express.RequestHandler[]): this;
+    /**
+     * Register a PATCH route handler.
+     */
+    patch(path: string, ...handlers: express.RequestHandler[]): this;
+    /**
+     * Register an OPTIONS route handler.
+     */
+    options(path: string, ...handlers: express.RequestHandler[]): this;
+    /**
+     * Register a HEAD route handler.
+     */
+    head(path: string, ...handlers: express.RequestHandler[]): this;
     /**
      * Register custom middleware with optional path restriction.
      *
@@ -657,32 +739,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.
      *