@catbee/utils 2.2.0 → 2.3.0

package/healthz-server/index.mjs

@@ -23,6 +23,7 @@
  */
 
 import { createServer } from 'http';
+import { trimChars } from '@catbee/utils/string';
 import { Env } from '@catbee/utils/env';
 
 var __defProp = Object.defineProperty;
@@ -58,6 +59,24 @@ __name(resolveConfig, "resolveConfig");
 // src/healthz-server/healthz-server.ts
 var SINGLETON_KEY = Symbol.for("CatbeeHealthzServer");
 var _global = globalThis;
+function formatHostForUrl(host) {
+  if (host.includes(":")) {
+    return `[${host}]`;
+  }
+  return host;
+}
+__name(formatHostForUrl, "formatHostForUrl");
+function getErrorMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string" && err.trim().length > 0) return err;
+  return "Unknown error";
+}
+__name(getErrorMessage, "getErrorMessage");
+function normalizeProbePath(p) {
+  const trimmed = trimChars(p, "/");
+  return trimmed ? `/${trimmed}` : "/";
+}
+__name(normalizeProbePath, "normalizeProbePath");
 var HealthzServer = class _HealthzServer {
   static {
     __name(this, "HealthzServer");
@@ -65,15 +84,30 @@ var HealthzServer = class _HealthzServer {
   server;
   config;
   startedAt = Date.now();
-  /** Whether the health server has successfully started listening (for `/startupz`) */
-  started = false;
+  /** Running address info for the Healthz probe server */
+  addressInfo = null;
+  /** Whether the health HTTP server is currently running and listening on its port */
+  running = false;
+  /** Whether application startup has completed (for `/startupz`) */
+  startupComplete = false;
   /** Whether the service is ready to receive traffic (for `/readyz`) */
   ready = false;
   shuttingDown = false;
+  livenessChecks;
+  readinessChecks;
+  stoppingPromise;
   onSigterm = /* @__PURE__ */ __name(() => this.initiateShutdown(), "onSigterm");
   onSigint = /* @__PURE__ */ __name(() => this.initiateShutdown(), "onSigint");
   constructor(config) {
     this.config = config;
+    this.livenessChecks = [
+      ...config.checks
+    ];
+    this.readinessChecks = config.readinessChecks !== void 0 ? [
+      ...config.readinessChecks
+    ] : [
+      ...config.checks
+    ];
     this.server = createServer((req, res) => this.handleRequest(req, res));
     if (this.config.handleSignals !== false) {
       process.once("SIGTERM", this.onSigterm);
@@ -95,68 +129,181 @@ var HealthzServer = class _HealthzServer {
     const config = resolveConfig(opts);
     const instance = new _HealthzServer(config);
     _global[SINGLETON_KEY] = instance;
+    const bindHost = config.host.startsWith("[") && config.host.endsWith("]") ? config.host.slice(1, -1) : config.host;
     return new Promise((resolve, reject) => {
       const onError = /* @__PURE__ */ __name((err) => {
         instance.cleanup();
+        instance.running = false;
+        instance.shuttingDown = false;
+        instance.addressInfo = null;
         delete _global[SINGLETON_KEY];
         reject(err);
       }, "onError");
       instance.server.once("error", onError);
       instance.server.listen({
-        host: config.host,
+        host: bindHost,
         port: config.port
       }, () => {
         instance.server.off("error", onError);
-        instance.started = true;
+        instance.server.on("error", () => {
+        });
+        instance.running = true;
         const addr = instance.server.address();
         if (!addr || typeof addr === "string") {
           instance.cleanup();
+          instance.running = false;
+          instance.shuttingDown = false;
+          instance.addressInfo = null;
           delete _global[SINGLETON_KEY];
           reject(new Error("Failed to resolve health server address"));
           return;
         }
-        resolve({
+        instance.addressInfo = {
           address: addr.address,
           family: addr.family,
           port: addr.port
+        };
+        resolve({
+          ...instance.addressInfo
         });
       });
     });
   }
-  /** Whether the health-check server is currently running and started. */
-  static isStarted() {
-    return _global[SINGLETON_KEY]?.started ?? false;
+  /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+  isRunning() {
+    return this.running;
+  }
+  /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+  static isRunning() {
+    return _global[SINGLETON_KEY]?.running ?? false;
+  }
+  /** Mark application startup as completed (switches `/startupz` to 200). */
+  markStartupComplete() {
+    this.startupComplete = true;
+    return this;
+  }
+  /** Mark application startup as completed (switches `/startupz` to 200). */
+  static markStartupComplete() {
+    _global[SINGLETON_KEY]?.markStartupComplete();
+  }
+  /** Set application startup completion status. */
+  setStartupComplete(complete) {
+    this.startupComplete = complete;
+    return this;
+  }
+  /** Set application startup completion status. */
+  static setStartupComplete(complete) {
+    _global[SINGLETON_KEY]?.setStartupComplete(complete);
+  }
+  /** Whether application startup has completed (for `/startupz`). */
+  isStartupComplete() {
+    return this.startupComplete;
+  }
+  /** Whether application startup has completed (for `/startupz`). */
+  static isStartupComplete() {
+    return _global[SINGLETON_KEY]?.isStartupComplete() ?? false;
+  }
+  /** Mark the service as ready / not-ready for traffic. */
+  setReady(ready) {
+    this.ready = ready;
+    return this;
   }
   /** Mark the service as ready / not-ready for traffic. */
   static setReady(ready) {
-    const instance = _global[SINGLETON_KEY];
-    if (!instance) return;
-    instance.ready = ready;
+    _global[SINGLETON_KEY]?.setReady(ready);
+  }
+  /** Whether the service is currently marked as ready. */
+  isReady() {
+    return this.ready;
   }
   /** Whether the service is currently marked as ready. */
   static isReady() {
-    return _global[SINGLETON_KEY]?.ready ?? false;
+    return _global[SINGLETON_KEY]?.isReady() ?? false;
+  }
+  /** Get address info of this health server instance. */
+  getAddress() {
+    return this.addressInfo;
+  }
+  /** Get address info of the active singleton health server. */
+  static getAddress() {
+    return _global[SINGLETON_KEY]?.getAddress() ?? null;
+  }
+  /** Get port the health server is listening on. */
+  getPort() {
+    return this.addressInfo?.port;
+  }
+  /** Get port the active singleton health server is listening on. */
+  static getPort() {
+    return _global[SINGLETON_KEY]?.getPort();
+  }
+  /** Get configured host. */
+  getHost() {
+    return this.config.host;
+  }
+  /** Get configured host of the active singleton health server. */
+  static getHost() {
+    return _global[SINGLETON_KEY]?.getHost();
+  }
+  /** Get full URL for this health server instance. */
+  getUrl() {
+    if (!this.addressInfo) return void 0;
+    const host = formatHostForUrl(this.addressInfo.address);
+    return `http://${host}:${this.addressInfo.port}`;
+  }
+  /** Get full URL for the active singleton health server. */
+  static getUrl() {
+    return _global[SINGLETON_KEY]?.getUrl();
+  }
+  /** Gracefully stop this health server instance. */
+  async stop() {
+    return _HealthzServer.stop();
   }
   /** Gracefully stop the health-check server. */
   static async stop() {
     const instance = _global[SINGLETON_KEY];
     if (!instance) return;
+    if (instance.stoppingPromise) {
+      return instance.stoppingPromise;
+    }
+    instance.shuttingDown = true;
+    instance.ready = false;
     instance.cleanup();
-    return new Promise((resolve) => {
+    instance.stoppingPromise = new Promise((resolve, reject) => {
+      let forceTimer;
+      const onDone = /* @__PURE__ */ __name((err) => {
+        if (forceTimer) clearTimeout(forceTimer);
+        instance.running = false;
+        instance.shuttingDown = false;
+        instance.addressInfo = null;
+        delete _global[SINGLETON_KEY];
+        if (err && err.code !== "ERR_SERVER_NOT_RUNNING") {
+          reject(err);
+        } else {
+          resolve();
+        }
+      }, "onDone");
       if (typeof instance.server.closeIdleConnections === "function") {
         instance.server.closeIdleConnections();
       }
-      instance.server.close(() => {
-        delete _global[SINGLETON_KEY];
-        resolve();
-      });
+      if (typeof instance.server.closeAllConnections === "function") {
+        instance.server.closeAllConnections();
+      }
+      forceTimer = setTimeout(() => {
+        if (typeof instance.server.closeAllConnections === "function") {
+          instance.server.closeAllConnections();
+        }
+        onDone();
+      }, 5e3);
+      instance.server.close((err) => onDone(err ?? void 0));
     });
+    return instance.stoppingPromise;
   }
   static getInstance() {
     return _global[SINGLETON_KEY];
   }
   /**
   * 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')
@@ -164,18 +311,57 @@ var HealthzServer = class _HealthzServer {
   */
   registerCheck(check, type = "readiness") {
     if (type === "liveness" || type === "both") {
-      this.config.checks.push(check);
+      const idx = this.livenessChecks.findIndex((c) => c.name === check.name);
+      if (idx !== -1) {
+        this.livenessChecks[idx] = check;
+      } else {
+        this.livenessChecks.push(check);
+      }
+    }
+    if (type === "readiness" || type === "both") {
+      const idx = this.readinessChecks.findIndex((c) => c.name === check.name);
+      if (idx !== -1) {
+        this.readinessChecks[idx] = check;
+      } else {
+        this.readinessChecks.push(check);
+      }
+    }
+    return 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, type = "both") {
+    if (type === "liveness" || type === "both") {
+      const idx = this.livenessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.livenessChecks.splice(idx, 1);
     }
     if (type === "readiness" || type === "both") {
-      this.config.readinessChecks ??= [
-        ...this.config.checks
-      ];
-      this.config.readinessChecks.push(check);
+      const idx = this.readinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.readinessChecks.splice(idx, 1);
     }
     return this;
   }
   /**
+  * Get all registered checks on this instance.
+  */
+  getChecks() {
+    return {
+      liveness: [
+        ...this.livenessChecks
+      ],
+      readiness: [
+        ...this.readinessChecks
+      ]
+    };
+  }
+  /**
   * 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')
@@ -183,51 +369,73 @@ var HealthzServer = class _HealthzServer {
   static registerCheck(check, type = "readiness") {
     _global[SINGLETON_KEY]?.registerCheck(check, type);
   }
+  /**
+  * 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, type = "both") {
+    _global[SINGLETON_KEY]?.unregisterCheck(name, type);
+  }
+  /**
+  * Get all registered checks on the active singleton HealthzServer instance.
+  */
+  static getChecks() {
+    return _global[SINGLETON_KEY]?.getChecks() ?? {
+      liveness: [],
+      readiness: []
+    };
+  }
   async handleRequest(req, res) {
     const isHead = req.method === "HEAD";
     if (req.method !== "GET" && !isHead) {
+      res.setHeader("Allow", "GET, HEAD");
       this.sendJson(res, 405, {
         error: "Method Not Allowed"
       }, isHead);
       return;
     }
-    const url = req.url ?? "/";
+    const rawUrl = req.url ?? "/";
+    const pathname = normalizeProbePath(rawUrl.split("?")[0]);
+    const matchPath = /* @__PURE__ */ __name((configured) => pathname === normalizeProbePath(configured), "matchPath");
     try {
-      if (url === this.config.healthzPath) {
+      if (matchPath(this.config.healthzPath)) {
         await this.handleLiveness(res, isHead);
-      } else if (url === this.config.readyzPath) {
+      } else if (matchPath(this.config.readyzPath)) {
         await this.handleReadiness(res, isHead);
-      } else if (url === this.config.startupzPath) {
+      } else if (matchPath(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";
+    } catch (_err) {
       this.sendJson(res, 500, {
-        error: message
+        error: "Internal Server Error"
       }, isHead);
     }
   }
   /** `/healthz` — Liveness probe */
   async handleLiveness(res, isHead = false) {
-    const results = await this.runChecks(this.config.checks);
-    if (this.config.onHealthCheck) {
+    const results = await this.runChecks(this.livenessChecks);
+    const livenessCheck = this.config.onLivenessCheck ?? this.config.onHealthCheck;
+    if (livenessCheck) {
       const start = Date.now();
       try {
-        const ok = await this.executeCheck(this.config.onHealthCheck, this.config.checkTimeoutMs);
+        const result = await this.executeCheck(livenessCheck, this.config.checkTimeoutMs);
+        const ok = result === void 0 ? true : !!result;
         results.push({
           name: "custom",
-          ok: !!ok,
+          ok,
           durationMs: Date.now() - start,
           ...!ok ? {
             error: "Health check returned false"
           } : {}
         });
       } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
+        const message = getErrorMessage(err);
         results.push({
           name: "custom",
           ok: false,
@@ -255,22 +463,22 @@ var HealthzServer = class _HealthzServer {
       ], isHead);
       return;
     }
-    const checksToRun = this.config.readinessChecks ?? this.config.checks;
-    const results = await this.runChecks(checksToRun);
+    const results = await this.runChecks(this.readinessChecks);
     if (this.config.onReadinessCheck) {
       const start = Date.now();
       try {
-        const ready = await this.executeCheck(this.config.onReadinessCheck, this.config.checkTimeoutMs);
+        const result = await this.executeCheck(this.config.onReadinessCheck, this.config.checkTimeoutMs);
+        const ready = result === void 0 ? true : !!result;
         results.push({
           name: "custom-readiness",
-          ok: !!ready,
+          ok: ready,
           durationMs: Date.now() - start,
           ...!ready ? {
             error: "Readiness check returned false"
           } : {}
         });
       } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
+        const message = getErrorMessage(err);
         results.push({
           name: "custom-readiness",
           ok: false,
@@ -286,7 +494,7 @@ var HealthzServer = class _HealthzServer {
   }
   /** `/startupz` — Startup probe */
   handleStartup(res, isHead = false) {
-    if (this.started) {
+    if (this.startupComplete) {
       this.sendProbe(res, 200, "ok", [], isHead);
     } else {
       this.sendProbe(res, 503, "unhealthy", [
@@ -294,7 +502,7 @@ var HealthzServer = class _HealthzServer {
           name: "startup",
           ok: false,
           durationMs: 0,
-          error: "Service has not started yet"
+          error: "Application startup not complete"
         }
       ], isHead);
     }
@@ -305,13 +513,17 @@ var HealthzServer = class _HealthzServer {
       const start = Date.now();
       try {
         const result = await this.executeCheck(check, this.config.checkTimeoutMs);
+        const ok = result === void 0 ? true : !!result;
         return {
           name,
-          ok: !!result,
-          durationMs: Date.now() - start
+          ok,
+          durationMs: Date.now() - start,
+          ...!ok ? {
+            error: "Check returned false"
+          } : {}
         };
       } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
+        const message = getErrorMessage(err);
         return {
           name,
           ok: false,
@@ -322,6 +534,9 @@ var HealthzServer = class _HealthzServer {
     }));
   }
   sendProbe(res, httpStatus, status, checks, isHead = false) {
+    if (this.shuttingDown) {
+      res.setHeader("Connection", "close");
+    }
     const body = {
       status,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -333,6 +548,7 @@ var HealthzServer = class _HealthzServer {
     this.sendJson(res, httpStatus, body, isHead);
   }
   sendJson(res, status, body, isHead = false) {
+    if (res.headersSent) return;
     const payload = JSON.stringify(body);
     res.writeHead(status, {
       "Content-Type": "application/json; charset=utf-8",
@@ -346,27 +562,37 @@ var HealthzServer = class _HealthzServer {
       res.end(payload);
     }
   }
+  /**
+  * 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.
+  */
   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(() => {
+    if (ms > 0) {
+      const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          const error = new Error(`Check timed out after ${ms}ms`);
+          controller.abort(error);
+          reject(error);
+        }, ms);
       });
-      return await Promise.race([
-        checkPromise,
-        timeoutPromise
-      ]);
-    } finally {
-      if (timer) clearTimeout(timer);
+      try {
+        const checkPromise = Promise.resolve().then(() => fn(controller.signal));
+        checkPromise.catch(() => {
+        });
+        return await Promise.race([
+          checkPromise,
+          timeoutPromise
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
     }
+    return await Promise.resolve().then(() => fn(controller.signal));
   }
   async initiateShutdown() {
     if (this.shuttingDown) return;
@@ -381,8 +607,7 @@ var HealthzServer = class _HealthzServer {
     process.off("SIGTERM", this.onSigterm);
     process.off("SIGINT", this.onSigint);
     this.ready = false;
-    this.started = false;
-    this.shuttingDown = false;
+    this.startupComplete = false;
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catbee/utils",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.",
   "publishConfig": {
     "access": "public"