@catbee/utils 2.0.5 → 2.1.1

package/healthz-server/index.cjs

@@ -0,0 +1,356 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+'use strict';
+
+var http = require('http');
+var env = require('@catbee/utils/env');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function getDefaultHealthzConfig() {
+  return {
+    host: env.Env.get("HEALTHZ_HOST", "") || env.Env.get("SERVER_HEALTHZ_HOST", "") || env.Env.get("SERVER_HOST", "") || env.Env.get("HOST", "0.0.0.0"),
+    port: env.Env.getPort("HEALTHZ_PORT", env.Env.getPort("SERVER_HEALTHZ_PORT", 8282)),
+    healthzPath: env.Env.get("HEALTHZ_PATH", "") || env.Env.get("SERVER_HEALTHZ_PATH", "") || env.Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
+    readyzPath: env.Env.get("HEALTHZ_READYZ_PATH", "") || env.Env.get("SERVER_READYZ_PATH", "/readyz"),
+    startupzPath: env.Env.get("HEALTHZ_STARTUPZ_PATH", "") || env.Env.get("SERVER_STARTUPZ_PATH", "/startupz"),
+    detailed: env.Env.getBoolean("HEALTHZ_DETAILED", env.Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true)),
+    checks: [],
+    checkTimeoutMs: env.Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", 5e3),
+    shutdownDelayMs: env.Env.getDuration("HEALTHZ_SHUTDOWN_DELAY_MS", 5e3)
+  };
+}
+__name(getDefaultHealthzConfig, "getDefaultHealthzConfig");
+function resolveConfig(userConfig) {
+  const defaults = getDefaultHealthzConfig();
+  if (!userConfig) return {
+    ...defaults
+  };
+  const cleaned = Object.fromEntries(Object.entries(userConfig).filter(([, v]) => v !== void 0));
+  return {
+    ...defaults,
+    ...cleaned
+  };
+}
+__name(resolveConfig, "resolveConfig");
+
+// src/healthz-server/healthz-server.ts
+var SINGLETON_KEY = Symbol.for("CatbeeHealthzServer");
+var _global = globalThis;
+var HealthzServer = class _HealthzServer {
+  static {
+    __name(this, "HealthzServer");
+  }
+  server;
+  config;
+  startedAt = Date.now();
+  /** Whether the health server has successfully started listening (for `/startupz`) */
+  started = false;
+  /** Whether the service is ready to receive traffic (for `/readyz`) */
+  ready = false;
+  shuttingDown = false;
+  onSigterm = /* @__PURE__ */ __name(() => this.initiateShutdown(), "onSigterm");
+  onSigint = /* @__PURE__ */ __name(() => this.initiateShutdown(), "onSigint");
+  constructor(config) {
+    this.config = config;
+    this.server = http.createServer((req, res) => this.handleRequest(req, res));
+    process.once("SIGTERM", this.onSigterm);
+    process.once("SIGINT", this.onSigint);
+  }
+  /**
+  * Boot the health-check server.
+  * Returns `null` if a server is already running in this process.
+  */
+  static async start(opts) {
+    if (_global[SINGLETON_KEY]) return null;
+    const config = resolveConfig(opts);
+    const instance = new _HealthzServer(config);
+    _global[SINGLETON_KEY] = instance;
+    return new Promise((resolve, reject) => {
+      const onError = /* @__PURE__ */ __name((err) => {
+        instance.cleanup();
+        delete _global[SINGLETON_KEY];
+        reject(err);
+      }, "onError");
+      instance.server.once("error", onError);
+      instance.server.listen({
+        host: config.host,
+        port: config.port
+      }, () => {
+        instance.server.off("error", onError);
+        instance.started = true;
+        const addr = instance.server.address();
+        if (!addr || typeof addr === "string") {
+          instance.cleanup();
+          delete _global[SINGLETON_KEY];
+          reject(new Error("Failed to resolve health server address"));
+          return;
+        }
+        resolve({
+          address: addr.address,
+          family: addr.family,
+          port: addr.port
+        });
+      });
+    });
+  }
+  /** Whether the health-check server is currently running and started. */
+  static isStarted() {
+    return _global[SINGLETON_KEY]?.started ?? false;
+  }
+  /** Mark the service as ready / not-ready for traffic. */
+  static setReady(ready) {
+    const instance = _global[SINGLETON_KEY];
+    if (!instance) return;
+    instance.ready = ready;
+  }
+  /** Whether the service is currently marked as ready. */
+  static isReady() {
+    return _global[SINGLETON_KEY]?.ready ?? false;
+  }
+  /** Gracefully stop the health-check server. */
+  static async stop() {
+    const instance = _global[SINGLETON_KEY];
+    if (!instance) return;
+    instance.cleanup();
+    return new Promise((resolve) => {
+      if (typeof instance.server.closeIdleConnections === "function") {
+        instance.server.closeIdleConnections();
+      }
+      instance.server.close(() => {
+        delete _global[SINGLETON_KEY];
+        resolve();
+      });
+    });
+  }
+  static getInstance() {
+    return _global[SINGLETON_KEY];
+  }
+  async handleRequest(req, res) {
+    const isHead = req.method === "HEAD";
+    if (req.method !== "GET" && !isHead) {
+      this.sendJson(res, 405, {
+        error: "Method Not Allowed"
+      }, isHead);
+      return;
+    }
+    const url = req.url ?? "/";
+    try {
+      if (url === this.config.healthzPath) {
+        await this.handleLiveness(res, isHead);
+      } else if (url === this.config.readyzPath) {
+        await this.handleReadiness(res, isHead);
+      } else if (url === this.config.startupzPath) {
+        this.handleStartup(res, isHead);
+      } else {
+        this.sendJson(res, 404, {
+          error: "Not Found"
+        }, isHead);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Internal Server Error";
+      this.sendJson(res, 500, {
+        error: message
+      }, isHead);
+    }
+  }
+  /** `/healthz` — Liveness probe */
+  async handleLiveness(res, isHead = false) {
+    const results = await this.runChecks(this.config.checks);
+    if (this.config.onHealthCheck) {
+      const start = Date.now();
+      try {
+        const ok = await this.executeCheck(this.config.onHealthCheck, this.config.checkTimeoutMs);
+        results.push({
+          name: "custom",
+          ok: !!ok,
+          durationMs: Date.now() - start,
+          ...!ok ? {
+            error: "Health check returned false"
+          } : {}
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        results.push({
+          name: "custom",
+          ok: false,
+          durationMs: Date.now() - start,
+          error: message
+        });
+      }
+    }
+    const allOk = results.every((r) => r.ok);
+    const status = allOk ? "ok" : "unhealthy";
+    const httpStatus = allOk ? 200 : 503;
+    this.sendProbe(res, httpStatus, status, results, isHead);
+  }
+  /** `/readyz` — Readiness probe */
+  async handleReadiness(res, isHead = false) {
+    if (this.shuttingDown || !this.ready) {
+      const status2 = "unhealthy";
+      this.sendProbe(res, 503, status2, [
+        {
+          name: "readiness",
+          ok: false,
+          durationMs: 0,
+          error: this.shuttingDown ? "Shutting down" : "Not ready"
+        }
+      ], isHead);
+      return;
+    }
+    const checksToRun = this.config.readinessChecks ?? this.config.checks;
+    const results = await this.runChecks(checksToRun);
+    if (this.config.onReadinessCheck) {
+      const start = Date.now();
+      try {
+        const ready = await this.executeCheck(this.config.onReadinessCheck, this.config.checkTimeoutMs);
+        results.push({
+          name: "custom-readiness",
+          ok: !!ready,
+          durationMs: Date.now() - start,
+          ...!ready ? {
+            error: "Readiness check returned false"
+          } : {}
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        results.push({
+          name: "custom-readiness",
+          ok: false,
+          durationMs: Date.now() - start,
+          error: message
+        });
+      }
+    }
+    const allOk = results.every((r) => r.ok);
+    const status = allOk ? "ok" : "unhealthy";
+    const httpStatus = allOk ? 200 : 503;
+    this.sendProbe(res, httpStatus, status, results, isHead);
+  }
+  /** `/startupz` — Startup probe */
+  handleStartup(res, isHead = false) {
+    if (this.started) {
+      this.sendProbe(res, 200, "ok", [], isHead);
+    } else {
+      this.sendProbe(res, 503, "unhealthy", [
+        {
+          name: "startup",
+          ok: false,
+          durationMs: 0,
+          error: "Service has not started yet"
+        }
+      ], isHead);
+    }
+  }
+  async runChecks(checks) {
+    if (checks.length === 0) return [];
+    return Promise.all(checks.map(async ({ name, check }) => {
+      const start = Date.now();
+      try {
+        const result = await this.executeCheck(check, this.config.checkTimeoutMs);
+        return {
+          name,
+          ok: !!result,
+          durationMs: Date.now() - start
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          name,
+          ok: false,
+          durationMs: Date.now() - start,
+          error: message
+        };
+      }
+    }));
+  }
+  sendProbe(res, httpStatus, status, checks, isHead = false) {
+    const body = {
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      uptimeSeconds: Math.floor((Date.now() - this.startedAt) / 1e3)
+    };
+    if (this.config.detailed && checks.length > 0) {
+      body.checks = checks;
+    }
+    this.sendJson(res, httpStatus, body, isHead);
+  }
+  sendJson(res, status, body, isHead = false) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+      "Content-Type": "application/json; charset=utf-8",
+      "Content-Length": Buffer.byteLength(payload),
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+      "X-Content-Type-Options": "nosniff"
+    });
+    if (isHead) {
+      res.end();
+    } else {
+      res.end(payload);
+    }
+  }
+  async executeCheck(fn, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const error = new Error(`Check timed out after ${ms}ms`);
+        controller.abort(error);
+        reject(error);
+      }, ms);
+    });
+    try {
+      const checkPromise = Promise.resolve().then(() => fn(controller.signal));
+      checkPromise.catch(() => {
+      });
+      return await Promise.race([
+        checkPromise,
+        timeoutPromise
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  async initiateShutdown() {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    this.ready = false;
+    if (this.config.shutdownDelayMs > 0) {
+      await new Promise((r) => setTimeout(r, this.config.shutdownDelayMs));
+    }
+    await _HealthzServer.stop();
+  }
+  cleanup() {
+    process.off("SIGTERM", this.onSigterm);
+    process.off("SIGINT", this.onSigint);
+    this.ready = false;
+    this.started = false;
+    this.shuttingDown = false;
+  }
+};
+
+exports.HealthzServer = HealthzServer;
+exports.getDefaultHealthzConfig = getDefaultHealthzConfig;
+exports.resolveConfig = resolveConfig;

package/healthz-server/index.d.ts

@@ -0,0 +1,291 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * 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>;
+}
+/**
+ * Result of a single named health check.
+ */
+interface CheckResult {
+    /** Name of the check */
+    name: string;
+    /** Whether the check passed */
+    ok: boolean;
+    /** Duration of the check in milliseconds */
+    durationMs: number;
+    /** Error message if the check failed */
+    error?: string;
+}
+/** Aggregate status string used in JSON probe responses */
+type ProbeStatus = 'ok' | 'unhealthy';
+/**
+ * Structured JSON response returned by probe endpoints.
+ */
+interface ProbeResponse {
+    /** Overall status */
+    status: ProbeStatus;
+    /** ISO-8601 timestamp of the check */
+    timestamp: string;
+    /** Server uptime in seconds */
+    uptimeSeconds: number;
+    /** Individual check results (only when `detailed` is enabled) */
+    checks?: CheckResult[];
+}
+/**
+ * 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;
+}
+/**
+ * Address information returned after the server starts listening.
+ */
+interface HealthzAddressInfo {
+    address: string;
+    family: string;
+    port: number;
+}
+
+/**
+ * Standalone HTTP health-check server designed for Kubernetes probes
+ * and microservice orchestration.
+ *
+ * Exposes three probe endpoints (paths are configurable):
+ *
+ * | Probe     | Default path | K8s probe type   | Behaviour |
+ * |-----------|-------------|------------------|-----------|
+ * | 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 |
+ *
+ * ### Kubernetes Probe Best Practices:
+ * - **Liveness (`/healthz`)**: Keep these checks extremely lightweight (e.g. process is responsive,
+ *   event loop not blocked). Avoid external dependencies (DB/Redis) here; if a shared database has
+ *   a transient outage, failing liveness causes Kubernetes to restart the container, which does not
+ *   fix external outages and can cause cascading restart storms.
+ * - **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.
+ *
+ * @example
+ * ```ts
+ * import { HealthzServer } from '@catbee/utils/healthz-server';
+ *
+ * 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 }) },
+ *   ],
+ *   shutdownDelayMs: 10_000,
+ * });
+ *
+ * // Signal readiness after all background services and migrations are ready:
+ * HealthzServer.setReady(true);
+ * ```
+ */
+declare class HealthzServer {
+    private readonly server;
+    private readonly config;
+    private readonly startedAt;
+    /** Whether the health server has successfully started listening (for `/startupz`) */
+    private started;
+    /** Whether the service is ready to receive traffic (for `/readyz`) */
+    private ready;
+    private shuttingDown;
+    private readonly onSigterm;
+    private readonly onSigint;
+    private constructor();
+    /**
+     * Boot the health-check server.
+     * 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;
+    /** Mark the service as ready / not-ready for traffic. */
+    static setReady(ready: boolean): void;
+    /** Whether the service is currently marked as ready. */
+    static isReady(): boolean;
+    /** Gracefully stop the health-check server. */
+    static stop(): Promise<void>;
+    static getInstance(): HealthzServer | undefined;
+    private handleRequest;
+    /** `/healthz` — Liveness probe */
+    private handleLiveness;
+    /** `/readyz` — Readiness probe */
+    private handleReadiness;
+    /** `/startupz` — Startup probe */
+    private handleStartup;
+    private runChecks;
+    private sendProbe;
+    private sendJson;
+    private executeCheck;
+    private initiateShutdown;
+    private cleanup;
+}
+
+/**
+ * Resolved configuration with all defaults applied.
+ * Internal-only — consumers interact with `CatbeeHealthzServerConfig`.
+ *
+ * `readinessChecks` is kept as `NamedCheck[] | undefined` so that
+ * "omitted" (-> fall back to `checks`) is distinguishable from
+ * "explicitly empty" (-> run nothing).
+ */
+interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
+    onHealthCheck?: CatbeeHealthzServerConfig['onHealthCheck'];
+    onReadinessCheck?: CatbeeHealthzServerConfig['onReadinessCheck'];
+    readinessChecks?: CatbeeHealthzServerConfig['readinessChecks'];
+}
+/**
+ * Loads default Healthz server configuration from environment variables.
+ */
+declare function getDefaultHealthzConfig(): ResolvedHealthzConfig;
+/**
+ * Merge user-supplied configuration with environment-resolved defaults.
+ * Undefined user values do not override resolved defaults.
+ */
+declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): ResolvedHealthzConfig;
+
+export { HealthzServer, getDefaultHealthzConfig, resolveConfig };
+export type { CatbeeHealthzServerConfig, CheckResult, HealthCheckFn, HealthzAddressInfo, NamedCheck, ProbeResponse, ProbeStatus, ReadinessCheckFn, ResolvedHealthzConfig };