@catbee/utils 2.1.1 → 2.2.1

package/types/index.d.ts

@@ -157,6 +157,134 @@ type Without<T, U> = {
     [P in keyof T as T[P] extends U ? never : P]: T[P];
 };
 
+/**
+ * A health check function that can be synchronous or asynchronous.
+ * Receives an AbortSignal that is triggered when `checkTimeoutMs` is exceeded.
+ *
+ * > **Cancellation Note**: Cancellation is cooperative. The check function must listen to
+ * > `signal.aborted` or pass `signal` to underlying asynchronous APIs (e.g. database drivers, `fetch`).
+ * > Synchronous CPU-bound loops or operations that ignore `signal` cannot be forcibly stopped by JavaScript.
+ *
+ * - Return `true` (or resolve to true) to signal healthy.
+ * - Return `false` (or resolve to false) to signal unhealthy.
+ * - Throw an error (or reject) to signal unhealthy with an error message.
+ */
+type HealthCheckFn = (signal?: AbortSignal) => boolean | Promise<boolean>;
+/**
+ * A readiness check function.
+ * Receives an AbortSignal that is triggered when `checkTimeoutMs` is exceeded.
+ *
+ * > **Cancellation Note**: Cancellation is cooperative. The check function must listen to
+ * > `signal.aborted` or pass `signal` to underlying asynchronous APIs (e.g. database drivers, `fetch`).
+ * > Synchronous CPU-bound loops or operations that ignore `signal` cannot be forcibly stopped by JavaScript.
+ *
+ * - Return `true` (or resolve to true) to signal ready.
+ * - Return `false` (or resolve to false) to signal not ready.
+ * - Throw an error (or reject) to signal not ready with an error.
+ */
+type ReadinessCheckFn = (signal?: AbortSignal) => boolean | Promise<boolean>;
+/**
+ * A named health check with an associated check function.
+ */
+interface NamedCheck {
+    /** Human-readable name for this check (e.g. 'database', 'redis', 'disk') */
+    name: string;
+    /**
+     * Check function — return false or throw to indicate failure.
+     * Receives an AbortSignal that is triggered when the check times out.
+     * Cancellation via the signal is cooperative.
+     */
+    check: (signal?: AbortSignal) => boolean | Promise<boolean>;
+}
+/**
+ * Configuration for the standalone healthz HTTP server.
+ */
+interface CatbeeHealthzServerConfig {
+    /** Hostname / IP to bind to
+     *  - **default**: `'0.0.0.0'`
+     *  - **env**: `HEALTHZ_HOST` (fallback: `SERVER_HOST`, `HOST`)
+     */
+    host?: string;
+    /** Port to listen on
+     *  - **default**: `8282`
+     *  - **env**: `HEALTHZ_PORT` (fallback: `SERVER_HEALTHZ_PORT`)
+     */
+    port?: number;
+    /** Liveness probe path — Kubernetes `livenessProbe.httpGet.path`
+     *  - **default**: `'/healthz'`
+     *  - **env**: `HEALTHZ_PATH` (fallback: `SERVER_HEALTH_CHECK_PATH`)
+     */
+    healthzPath?: string;
+    /** Readiness probe path — Kubernetes `readinessProbe.httpGet.path`
+     *  - **default**: `'/readyz'`
+     *  - **env**: `HEALTHZ_READYZ_PATH` (fallback: `SERVER_READYZ_PATH`)
+     */
+    readyzPath?: string;
+    /** Startup probe path — Kubernetes `startupProbe.httpGet.path`
+     *  - **default**: `'/startupz'`
+     *  - **env**: `HEALTHZ_STARTUPZ_PATH` (fallback: `SERVER_STARTUPZ_PATH`)
+     */
+    startupzPath?: string;
+    /** Include individual check results in the JSON response
+     *  - **default**: `true`
+     *  - **env**: `HEALTHZ_DETAILED` (fallback: `SERVER_HEALTH_CHECK_DETAILED_OUTPUT`)
+     */
+    detailed?: boolean;
+    /**
+     * Named checks to run on the liveness endpoint (`/healthz`).
+     *
+     * > **Kubernetes Best Practice**: Keep liveness checks very lightweight (e.g. process is responsive,
+     * > event loop not blocked). Avoid placing external dependencies (DB, Redis, downstream APIs) here;
+     * > if a shared dependency encounters transient downtime, failing liveness causes Kubernetes to restart
+     * > the container, risking cascading restart storms.
+     * >
+     * > Place external dependency checks in `readinessChecks` instead.
+     */
+    checks?: NamedCheck[];
+    /**
+     * Named checks to run on the readiness endpoint (`/readyz`).
+     *
+     * Use this for external dependencies (DB, Redis, cache, message broker).
+     * If a dependency goes down, Kubernetes will temporarily remove the pod from traffic rotation
+     * without killing/restarting the container, allowing it to recover cleanly.
+     *
+     * - If **omitted** (`undefined`): falls back to `checks`.
+     * - If **explicitly empty** (`[]`): no readiness checks are run (traffic gated purely by `setReady(true)`).
+     */
+    readinessChecks?: NamedCheck[];
+    /**
+     * Custom liveness check function. Runs *in addition to* `checks`.
+     * Return `false` or throw to indicate unhealthy.
+     */
+    onHealthCheck?: HealthCheckFn;
+    /**
+     * Custom readiness check function. Runs *in addition to* `readinessChecks`.
+     * Return `false` or throw to indicate not ready.
+     */
+    onReadinessCheck?: ReadinessCheckFn;
+    /** Timeout (ms) per individual check before it's considered failed
+     *  - **default**: `5000`
+     *  - **env**: `HEALTHZ_CHECK_TIMEOUT_MS`
+     */
+    checkTimeoutMs?: number;
+    /**
+     * Graceful shutdown delay in milliseconds.
+     * After receiving SIGTERM/SIGINT the server immediately flips readiness
+     * to `false` and waits this many ms before closing — giving the load
+     * balancer time to drain traffic.
+     *  - **default**: `5000`
+     *  - **env**: `HEALTHZ_SHUTDOWN_DELAY_MS`
+     */
+    shutdownDelayMs?: number;
+    /**
+     * Whether the HealthzServer should register its own SIGTERM/SIGINT process signal listeners.
+     * When managed by an orchestrating server (such as Catbee ExpressServer), set this to `false`
+     * to prevent signal listener conflicts and allow coordinated teardown.
+     *  - **default**: `true`
+     */
+    handleSignals?: boolean;
+}
+
 /**
  * Server configuration for Catbee HTTP/Express server.
  * Designed with secure and high-performance defaults for production use.
@@ -370,35 +498,19 @@ interface CatbeeServerConfig {
          */
         skipNotFoundRoutes?: boolean;
     };
-    /** Health-check configuration
-     *  - **path**: `/healthz`
-     *  - **detailed**: `true`
-     *  - **withGlobalPrefix**: `false`
+    /** Standalone Healthz probe HTTP server configuration (for Kubernetes liveness, readiness, startup probes)
+     *  - **default**: `false`
+     *  - **env**: `SERVER_HEALTHZ_ENABLE` || `HEALTHZ_ENABLE`
+     *
+     * When enabled, ExpressServer automatically:
+     * - Starts `HealthzServer` on `server.start()`
+     * - Sets `HealthzServer.setReady(true)` after Express server is listening and ready
+     * - Sets `HealthzServer.setReady(false)` and gracefully drains/stops `HealthzServer` on `server.stop()`
+     * - Syncs health checks registered via `server.registerHealthCheck()` to `HealthzServer`
      */
-    healthCheck?: {
-        /** Health-check endpoint path
-         *  - **default**: `'/healthz'`
-         *  - **env**: `SERVER_HEALTH_CHECK_PATH`
-         */
-        path?: string;
-        /** Include detailed check results in the response
-         *  - **default**: `true`
-         *  - **env**: `SERVER_HEALTH_CHECK_DETAILED_OUTPUT`
-         */
-        detailed?: boolean;
-        /** Apply global route prefix
-         *  - **default**: `false`
-         *  - **env**: `SERVER_HEALTH_CHECK_WITH_GLOBAL_PREFIX`
-         */
-        withGlobalPrefix?: boolean;
-        /** Custom health checks */
-        checks?: Array<{
-            /** Name of the health check */
-            name: string;
-            /** Check function that returns boolean or Promise<boolean> */
-            check: () => Promise<boolean> | boolean;
-        }>;
-    };
+    healthzServer?: ToggleConfig<CatbeeHealthzServerConfig & {
+        enable?: boolean;
+    }>;
     /** Request timeout in ms
      *  - **default**: `30000` (30 seconds)
      *  - **env**: `SERVER_REQUEST_TIMEOUT_MS`
@@ -557,25 +669,8 @@ interface CatbeeServerHooks {
     /** Called before response is sent */
     onResponse?: (req: Request, res: Response, next: NextFunction) => void;
 }
-interface GlobalServerAddons {
-    /**
-     * Skip healthz endpoint even if health checks are configured
-     *  - **default**: `false`
-     *  - **env**: `SERVER_SKIP_HEALTHZ_CHECKS_VALIDATION`
-     *
-     * @additionalInfo
-     * Set to true to return `200 OK` for `/healthz` without checks
-     * Useful in environments where a simple liveness probe is needed
-     * without performing actual health checks
-     * Example: Kubernetes liveness probe
-     * Note: This does not disable the health check functionality itself
-     *       Health checks can still be performed programmatically
-     *       or via other endpoints if needed
-     */
-    skipHealthzChecksValidation: boolean;
-}
 /** Combined global server configuration type */
-type CatbeeGlobalServerConfig = CatbeeServerConfig & GlobalServerAddons;
+type CatbeeGlobalServerConfig = CatbeeServerConfig;
 
 /**
  * Generic API response format.
@@ -781,4 +876,4 @@ interface CatbeeConfig {
 }
 
 export { SortDirection };
-export type { ApiErrorResponse, ApiResponse, ApiSuccessResponse, AsyncOperationResponse, Awaited, BatchResponse, CatbeeConfig, CatbeeGlobalServerConfig, CatbeeServerConfig, CatbeeServerHooks, DeepPartial, DeepReadonly, DeepRequired, DeepStringifyOrNull, Func, GlobalServerAddons, IsEqual, KeysOfType, MaybePromise, Mutable, NonEmptyArray, Nullable, Optional, Optional2, Pagination, PaginationParams, PaginationResponse, PartialPick, PickByType, Primitive, RecordOptional, RequireAtLeastOne, StreamResponse, StringKeyedRecord, ToggleConfig, UnionToIntersection, ValueOf, WithPagination, Without, Writable };
+export type { ApiErrorResponse, ApiResponse, ApiSuccessResponse, AsyncOperationResponse, Awaited, BatchResponse, CatbeeConfig, CatbeeGlobalServerConfig, CatbeeServerConfig, CatbeeServerHooks, DeepPartial, DeepReadonly, DeepRequired, DeepStringifyOrNull, Func, IsEqual, KeysOfType, MaybePromise, Mutable, NonEmptyArray, Nullable, Optional, Optional2, Pagination, PaginationParams, PaginationResponse, PartialPick, PickByType, Primitive, RecordOptional, RequireAtLeastOne, StreamResponse, StringKeyedRecord, ToggleConfig, UnionToIntersection, ValueOf, WithPagination, Without, Writable };