@catbee/utils 2.2.0 → 2.3.0

package/healthz-server/index.d.ts

@@ -26,28 +26,42 @@
  * 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.
+ * > **Cancellation & Timeout Semantics**:
+ * > When `checkTimeoutMs` expires, the HTTP probe response immediately fast-fails with 503
+ * > and aborts the supplied `AbortSignal`.
+ * >
+ * > However, runtime cancellation in JavaScript is **strictly cooperative**. The probe server cannot
+ * > preemptively interrupt executing JavaScript or force-cancel asynchronous work that does not listen
+ * > to the signal. If a check executes asynchronous tasks without passing `signal`
+ * > (e.g., `await db.query(...)` without `{ signal }`), that task will continue running in the background.
+ * > To prevent background resource leaks, always pass `signal` to underlying drivers/clients
+ * > (e.g. `fetch(url, { signal })`, database clients, HTTP clients) or check `signal?.aborted`.
  *
- * - Return `true` (or resolve to true) to signal healthy.
+ * - Return `true` (or resolve to true, or resolve void without error) 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>;
+type HealthCheckFn = (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 /**
  * 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.
+ * > **Cancellation & Timeout Semantics**:
+ * > When `checkTimeoutMs` expires, the HTTP probe response immediately fast-fails with 503
+ * > and aborts the supplied `AbortSignal`.
+ * >
+ * > However, runtime cancellation in JavaScript is **strictly cooperative**. The probe server cannot
+ * > preemptively interrupt executing JavaScript or force-cancel asynchronous work that does not listen
+ * > to the signal. If a check executes asynchronous tasks without passing `signal`
+ * > (e.g., `await db.query(...)` without `{ signal }`), that task will continue running in the background.
+ * > To prevent background resource leaks, always pass `signal` to underlying drivers/clients
+ * > (e.g. `fetch(url, { signal })`, database clients, HTTP clients) or check `signal?.aborted`.
  *
- * - Return `true` (or resolve to true) to signal ready.
+ * - Return `true` (or resolve to true, or resolve void without error) 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>;
+type ReadinessCheckFn = (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 /**
  * A named health check with an associated check function.
  */
@@ -56,10 +70,11 @@ interface NamedCheck {
     name: string;
     /**
      * Check function — return false or throw to indicate failure.
+     * Resolving void without throwing is considered healthy/ready.
      * Receives an AbortSignal that is triggered when the check times out.
-     * Cancellation via the signal is cooperative.
+     * Cancellation via the signal is cooperative; pass `signal` to underlying operations.
      */
-    check: (signal?: AbortSignal) => boolean | Promise<boolean>;
+    check: (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 }
 /**
  * Result of a single named health check.
@@ -148,14 +163,27 @@ interface CatbeeHealthzServerConfig {
     /**
      * Custom liveness check function. Runs *in addition to* `checks`.
      * Return `false` or throw to indicate unhealthy.
+     * Can also be provided via `onLivenessCheck`.
      */
     onHealthCheck?: HealthCheckFn;
+    /**
+     * Symmetrical alias for `onHealthCheck` — custom liveness check function.
+     * Runs *in addition to* `checks` on `/healthz`.
+     * Return `false` or throw to indicate unhealthy.
+     */
+    onLivenessCheck?: 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
+    /**
+     * Timeout (ms) per individual check before it's considered failed.
+     *
+     * When exceeded, the probe immediately fast-fails with status 503 and triggers
+     * `abort()` on the check's `AbortSignal`. Note that cancellation is cooperative;
+     * checks should forward `signal` to downstream clients (e.g. database drivers, fetch)
+     * to avoid orphaned background execution.
      *  - **default**: `5000`
      *  - **env**: `HEALTHZ_CHECK_TIMEOUT_MS`
      */
@@ -194,8 +222,9 @@ interface HealthzAddressInfo {
  * "omitted" (-> fall back to `checks`) is distinguishable from
  * "explicitly empty" (-> run nothing).
  */
-interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
+interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onLivenessCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
     onHealthCheck?: CatbeeHealthzServerConfig['onHealthCheck'];
+    onLivenessCheck?: CatbeeHealthzServerConfig['onLivenessCheck'];
     onReadinessCheck?: CatbeeHealthzServerConfig['onReadinessCheck'];
     readinessChecks?: CatbeeHealthzServerConfig['readinessChecks'];
 }
@@ -219,7 +248,7 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  * |-----------|-------------|------------------|-----------|
  * | Liveness  | `/healthz`  | `livenessProbe`  | Runs configured checks; 200 = alive, 503 = unhealthy |
  * | Readiness | `/readyz`   | `readinessProbe` | Checks readiness flag + readiness checks; 503 while not ready |
- * | Startup   | `/startupz` | `startupProbe`   | 200 once the server has successfully started listening; 503 before that |
+ * | Startup   | `/startupz` | `startupProbe`   | 200 once application startup completes (`markStartupComplete()`); 503 while booting |
  *
  * ### Kubernetes Probe Best Practices:
  * - **Liveness (`/healthz`)**: Keep these checks extremely lightweight (e.g. process is responsive,
@@ -229,7 +258,8 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  * - **Readiness (`/readyz`)**: Place external dependency checks (DB, Redis, downstream APIs) here via
  *   `readinessChecks`. If a dependency fails, Kubernetes temporarily pulls the pod from service endpoints
  *   without restarting the container, allowing it to recover gracefully.
- * - **Startup (`/startupz`)**: Verifies the health server process has started listening.
+ * - **Startup (`/startupz`)**: Verifies the application has completed its startup sequence
+ *   (signaled via `markStartupComplete()`). Protects slow-starting applications from premature liveness kills.
  *
  * @example
  * ```ts
@@ -237,11 +267,9 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  *
  * const addr = await HealthzServer.start({
  *   port: 8282,
- *   // Keep liveness lightweight:
  *   checks: [
  *     { name: 'process', check: () => true },
  *   ],
- *   // Place dependency checks on readiness:
  *   readinessChecks: [
  *     { name: 'database', check: (signal) => db.ping({ signal }) },
  *     { name: 'redis',    check: (signal) => redis.ping({ signal }) },
@@ -249,6 +277,9 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  *   shutdownDelayMs: 10_000,
  * });
  *
+ * // Signal application startup complete (switches /startupz to 200):
+ * HealthzServer.markStartupComplete();
+ *
  * // Signal readiness after all background services and migrations are ready:
  * HealthzServer.setReady(true);
  * ```
@@ -257,11 +288,18 @@ declare class HealthzServer {
     private readonly server;
     private readonly config;
     private readonly startedAt;
-    /** Whether the health server has successfully started listening (for `/startupz`) */
-    private started;
+    /** Running address info for the Healthz probe server */
+    private addressInfo;
+    /** Whether the health HTTP server is currently running and listening on its port */
+    private running;
+    /** Whether application startup has completed (for `/startupz`) */
+    private startupComplete;
     /** Whether the service is ready to receive traffic (for `/readyz`) */
     private ready;
     private shuttingDown;
+    private readonly livenessChecks;
+    private readonly readinessChecks;
+    private stoppingPromise?;
     private readonly onSigterm;
     private readonly onSigint;
     private constructor();
@@ -274,30 +312,97 @@ declare class HealthzServer {
      * Returns `null` if a server is already running in this process.
      */
     static start(opts?: CatbeeHealthzServerConfig): Promise<HealthzAddressInfo | null>;
-    /** Whether the health-check server is currently running and started. */
-    static isStarted(): boolean;
+    /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+    isRunning(): boolean;
+    /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+    static isRunning(): boolean;
+    /** Mark application startup as completed (switches `/startupz` to 200). */
+    markStartupComplete(): this;
+    /** Mark application startup as completed (switches `/startupz` to 200). */
+    static markStartupComplete(): void;
+    /** Set application startup completion status. */
+    setStartupComplete(complete: boolean): this;
+    /** Set application startup completion status. */
+    static setStartupComplete(complete: boolean): void;
+    /** Whether application startup has completed (for `/startupz`). */
+    isStartupComplete(): boolean;
+    /** Whether application startup has completed (for `/startupz`). */
+    static isStartupComplete(): boolean;
+    /** Mark the service as ready / not-ready for traffic. */
+    setReady(ready: boolean): this;
     /** Mark the service as ready / not-ready for traffic. */
     static setReady(ready: boolean): void;
     /** Whether the service is currently marked as ready. */
+    isReady(): boolean;
+    /** Whether the service is currently marked as ready. */
     static isReady(): boolean;
+    /** Get address info of this health server instance. */
+    getAddress(): HealthzAddressInfo | null;
+    /** Get address info of the active singleton health server. */
+    static getAddress(): HealthzAddressInfo | null;
+    /** Get port the health server is listening on. */
+    getPort(): number | undefined;
+    /** Get port the active singleton health server is listening on. */
+    static getPort(): number | undefined;
+    /** Get configured host. */
+    getHost(): string | undefined;
+    /** Get configured host of the active singleton health server. */
+    static getHost(): string | undefined;
+    /** Get full URL for this health server instance. */
+    getUrl(): string | undefined;
+    /** Get full URL for the active singleton health server. */
+    static getUrl(): string | undefined;
+    /** Gracefully stop this health server instance. */
+    stop(): Promise<void>;
     /** Gracefully stop the health-check server. */
     static stop(): Promise<void>;
     static getInstance(): HealthzServer | undefined;
     /**
      * Register a named check on this HealthzServer instance dynamically.
+     * If a check with the same name already exists in the target probe, it is updated in-place.
      *
      * @param check - The named check to register
      * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
      * @returns This instance for chaining
      */
     registerCheck(check: NamedCheck, type?: 'liveness' | 'readiness' | 'both'): this;
+    /**
+     * Unregister a named check on this HealthzServer instance.
+     *
+     * @param name - The name of the check to remove
+     * @param type - Which probe to remove from ('liveness', 'readiness', or 'both')
+     * @returns This instance for chaining
+     */
+    unregisterCheck(name: string, type?: 'liveness' | 'readiness' | 'both'): this;
+    /**
+     * Get all registered checks on this instance.
+     */
+    getChecks(): {
+        liveness: NamedCheck[];
+        readiness: NamedCheck[];
+    };
     /**
      * Register a named check on the active singleton HealthzServer instance (if started).
+     * If a check with the same name already exists in the target probe, it is updated in-place.
      *
      * @param check - The named check to register
      * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
      */
     static registerCheck(check: NamedCheck, type?: 'liveness' | 'readiness' | 'both'): void;
+    /**
+     * Unregister a named check on the active singleton HealthzServer instance (if started).
+     *
+     * @param name - Name of the check to remove
+     * @param type - Which probe to remove from ('liveness', 'readiness', or 'both')
+     */
+    static unregisterCheck(name: string, type?: 'liveness' | 'readiness' | 'both'): void;
+    /**
+     * Get all registered checks on the active singleton HealthzServer instance.
+     */
+    static getChecks(): {
+        liveness: NamedCheck[];
+        readiness: NamedCheck[];
+    };
     private handleRequest;
     /** `/healthz` — Liveness probe */
     private handleLiveness;
@@ -308,6 +413,13 @@ declare class HealthzServer {
     private runChecks;
     private sendProbe;
     private sendJson;
+    /**
+     * Executes a check function with timeout and cooperative cancellation.
+     *
+     * Note on cancellation: The AbortController aborts when `ms` expires, which signals cooperative
+     * consumers (e.g., fetch, pg, ioredis) to terminate their work. The attached .catch() on checkPromise
+     * prevents unhandled rejections if the check promise rejects after the timeout has already resolved.
+     */
     private executeCheck;
     private initiateShutdown;
     private cleanup;