@catbee/utils 2.0.4 → 2.1.1

package/healthz-server/index.mjs

@@ -0,0 +1,352 @@
+/*
+ * 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.
+ */
+
+import { createServer } from 'http';
+import { Env } from '@catbee/utils/env';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function getDefaultHealthzConfig() {
+  return {
+    host: Env.get("HEALTHZ_HOST", "") || Env.get("SERVER_HEALTHZ_HOST", "") || Env.get("SERVER_HOST", "") || Env.get("HOST", "0.0.0.0"),
+    port: Env.getPort("HEALTHZ_PORT", Env.getPort("SERVER_HEALTHZ_PORT", 8282)),
+    healthzPath: Env.get("HEALTHZ_PATH", "") || Env.get("SERVER_HEALTHZ_PATH", "") || Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
+    readyzPath: Env.get("HEALTHZ_READYZ_PATH", "") || Env.get("SERVER_READYZ_PATH", "/readyz"),
+    startupzPath: Env.get("HEALTHZ_STARTUPZ_PATH", "") || Env.get("SERVER_STARTUPZ_PATH", "/startupz"),
+    detailed: Env.getBoolean("HEALTHZ_DETAILED", Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true)),
+    checks: [],
+    checkTimeoutMs: Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", 5e3),
+    shutdownDelayMs: 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 = 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;
+  }
+};
+
+export { HealthzServer, getDefaultHealthzConfig, resolveConfig };

package/index.cjs

@@ -39,6 +39,7 @@ var env = require("./env/index.cjs");
 var error = require("./error/index.cjs");
 var exception = require("./exception/index.cjs");
 var fs = require("./fs/index.cjs");
+var healthzServer = require("./healthz-server/index.cjs");
 var httpStatusCodes = require("./http-status-codes/index.cjs");
 var id = require("./id/index.cjs");
 var logger = require("./logger/index.cjs");
@@ -145,6 +146,12 @@ Object.keys(fs).forEach(function (k) {
 		get: function () { return fs[k]; }
 	});
 });
+Object.keys(healthzServer).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return healthzServer[k]; }
+	});
+});
 Object.keys(httpStatusCodes).forEach(function (k) {
 	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/index.d.ts

@@ -37,6 +37,7 @@ export * from './env';
 export * from './error';
 export * from './exception';
 export * from './fs';
+export * from './healthz-server';
 export * from './http-status-codes';
 export * from './id';
 export * from './logger';

package/index.mjs

@@ -37,6 +37,7 @@ export * from "./env/index.mjs";
 export * from "./error/index.mjs";
 export * from "./exception/index.mjs";
 export * from "./fs/index.mjs";
+export * from "./healthz-server/index.mjs";
 export * from "./http-status-codes/index.mjs";
 export * from "./id/index.mjs";
 export * from "./logger/index.mjs";