@sandsoftwaresolutions/health 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SandSoftwareSolutions
+
+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.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @sandsoftwaresolutions/health
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/SandSoftwareSolutions/ss-health/actions/workflows/ci.yml/badge.svg)](https://github.com/SandSoftwareSolutions/ss-health/actions/workflows/ci.yml)
+
+Health checks for a service, the way a load balancer, Docker or Kubernetes wants them: a **live** endpoint that only says the process runs, and a **ready** endpoint that checks your database and friends. No dependencies.
+
+## Install
+
+```bash
+npm install @sandsoftwaresolutions/health
+```
+
+Works with `import` and `require()`, and ships TypeScript types for both.
+
+## Usage
+
+```js
+import { createServer } from "node:http";
+import { createHealth } from "@sandsoftwaresolutions/health";
+
+const health = createHealth({
+  checks: {
+    database: () => db.prepare("SELECT 1").get(),
+    disk: () => freeSpaceMb() > 100,                              // return false to fail
+    mail: { check: pingSmtp, critical: false, timeoutMs: 5000 }   // may fail without taking the service down
+  },
+  timeoutMs: 2000,
+  cacheMs: 1000
+});
+
+createServer((req, res) => {
+  if (req.url === "/live") return health.live(req, res);
+  if (req.url === "/ready") return health.ready(req, res);
+  /* ... */
+}).listen(3000);
+```
+
+`GET /ready` answers with
+
+```json
+{ "status": "ok", "checks": { "database": { "status": "up", "ms": 1, "critical": true } }, "at": "2026-10-17T10:00:00.000Z" }
+```
+
+## How it behaves
+
+- **ok / degraded / down.** A failing *critical* check (the default) makes the service `down` (HTTP 503). A failing non-critical one only makes it `degraded` (still HTTP 200), so a broken mail server does not get your app restarted.
+- **A check passes** when it returns without throwing and does not return `false`. It fails when it throws, returns `false`, or takes longer than its timeout.
+- **Caching.** Results are cached for `cacheMs` and simultaneous requests share one run, so a busy load balancer cannot hammer your database.
+- **A hung check is not piled up.** A check that is still running from an earlier probe is not called again: it is reported `down` ("the previous call of this check is still running") until it comes back. Otherwise every probe would add one more hung call to your database. Each check also gets an `AbortSignal` (`check(signal)`) that aborts when it times out, so a check can cancel its own work. Give a check its own timeout if it can hang for ever, because until it settles it stays `down`.
+- **Timeouts** must be a number above 0 (`RangeError` otherwise); a very large one is cut to 2^31-1 ms. A clock that steps back does not freeze the cache.
+- **Live is not ready.** `/live` never runs checks. If your database is slow, you want traffic held back (not ready) and not a restart (not live).
+- **No leaks.** Error messages are left out unless you set `verbose: true`, because they can contain addresses and passwords. Use `verbose` for private networks only.
+- Responses are `no-store`. The check names, their status and timing are in the answer: put `/ready` where only your orchestrator can reach it, or name checks so that they reveal little. If the run itself breaks, `/ready` answers `503 {"status":"down"}`.
+
+Pairs well with `@sandsoftwaresolutions/graceful`: after shutdown starts, answer 503 on `/ready`.

package/dist/index.cjs

@@ -0,0 +1,120 @@
+"use strict";
+// setTimeout fires after 1 ms for anything above this, which would report a slow check as timed out at once.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const TIMED_OUT = Symbol("timed out");
+
+/**
+ * A health check for a service. `checks` maps a name to a function (or `{ check, timeoutMs, critical }`) that throws or returns
+ * false when something is wrong; it gets an AbortSignal that aborts on timeout. A check is not called again while an earlier
+ * call of it is still running. A failing critical check (the default) makes the service "down"; a failing non-critical one
+ * only "degraded". Results are cached for `cacheMs` and concurrent calls share one run, so a busy load balancer cannot
+ * hammer your database. Error details are only included with `verbose: true`.
+ */
+function createHealth({ checks = {}, timeoutMs = 2000, cacheMs = 1000, verbose = false, now = Date.now } = {}) {
+  const checkTimeout = (value, where) => {
+    if (typeof value !== "number" || Number.isNaN(value) || value <= 0) throw new RangeError(`createHealth: ${where} must be a number of milliseconds above 0`);
+    return Math.min(value, MAX_TIMER_MS);
+  };
+  const globalTimeout = checkTimeout(timeoutMs, "timeoutMs");
+  if (typeof cacheMs !== "number" || Number.isNaN(cacheMs) || cacheMs < 0) throw new RangeError("createHealth: cacheMs must be a number of milliseconds, 0 or more");
+  const entries = Object.entries(checks).map(([name, spec]) => {
+    const def = typeof spec === "function" ? { check: spec } : spec;
+    if (typeof def?.check !== "function") throw new TypeError(`createHealth: check "${name}" must be a function`);
+    if (def.critical !== undefined && typeof def.critical !== "boolean") throw new TypeError(`createHealth: critical of check "${name}" must be true or false`);
+    return [name, { check: def.check, timeoutMs: def.timeoutMs === undefined ? globalTimeout : checkTimeout(def.timeoutMs, `timeoutMs of check "${name}"`), critical: def.critical ?? true, inFlight: false }];
+  });
+  let cached = null;
+  let running = null;
+
+  async function runOne(name, def) {
+    const started = now();
+    let state = "up";
+    let error;
+    if (def.inFlight) {
+      // The earlier call has not come back yet. Calling again would add one more hung call (and connection) per probe.
+      state = "down";
+      error = "the previous call of this check is still running";
+    } else {
+      const controller = new AbortController();
+      let timer;
+      const timedOut = new Promise((resolve) => {
+        timer = setTimeout(resolve, def.timeoutMs, TIMED_OUT);
+        timer.unref?.();
+      });
+      def.inFlight = true;
+      const call = Promise.resolve().then(() => def.check(controller.signal));
+      const settled = () => { def.inFlight = false; };
+      call.then(settled, settled);
+      try {
+        const outcome = await Promise.race([call, timedOut]);
+        if (outcome === TIMED_OUT) {
+          state = "down";
+          error = `timed out after ${def.timeoutMs} ms`;
+          controller.abort(new Error(error));
+        } else if (outcome === false) {
+          state = "down";
+          error = "check returned false";
+        }
+      } catch (e) {
+        state = "down";
+        error = e?.message ?? String(e);
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    const result = { status: state, ms: Math.max(0, now() - started), critical: def.critical };
+    if (error && verbose) result.error = error;
+    return [name, result];
+  }
+
+  async function execute() {
+    const results = Object.fromEntries(await Promise.all(entries.map(([name, def]) => runOne(name, def))));
+    const failed = Object.values(results).filter((r) => r.status === "down");
+    const status = failed.some((r) => r.critical) ? "down" : failed.length > 0 ? "degraded" : "ok";
+    return { status, checks: results, at: new Date(now()).toISOString() };
+  }
+
+  /** Runs the checks (or returns the cached result). */
+  async function run() {
+    const age = cached ? now() - cached.time : -1; // a clock that stepped back (negative age) does not keep the cache alive
+    if (cached && age >= 0 && age < cacheMs) return cached.report;
+    running ??= execute().then(
+      (report) => {
+        cached = { time: now(), report };
+        running = null;
+        return report;
+      },
+      (error) => {
+        running = null;
+        throw error;
+      }
+    );
+    return running;
+  }
+
+  const send = (res, code, body) => {
+    res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+  };
+
+  return {
+    run,
+    /** Request handler for `/ready`: 200 for ok and degraded, 503 for down (also when the run itself breaks). */
+    async ready(_req, res) {
+      let report;
+      try {
+        report = await run();
+      } catch {
+        if (!res.headersSent) send(res, 503, { status: "down" });
+        return;
+      }
+      send(res, report.status === "down" ? 503 : 200, report);
+    },
+    /** Request handler for `/live`: 200 as long as the process can answer. No checks, so a slow database never restarts the app. */
+    live(_req, res) {
+      send(res, 200, { status: "ok" });
+    }
+  };
+}
+
+exports.createHealth = createHealth;

package/dist/index.d.cts

@@ -0,0 +1,41 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/** Gets a signal that aborts when the check times out. */
+export type CheckFn = (signal: AbortSignal) => unknown | Promise<unknown>;
+export interface CheckSpec {
+  check: CheckFn;
+  /** Default: the global timeoutMs. */
+  timeoutMs?: number;
+  /** A failing critical check makes the service "down" (default true); otherwise "degraded". */
+  critical?: boolean;
+}
+
+export interface CheckResult {
+  status: "up" | "down";
+  ms: number;
+  critical: boolean;
+  /** Only with `verbose: true`. */
+  error?: string;
+}
+
+export interface HealthReport {
+  status: "ok" | "degraded" | "down";
+  checks: Record<string, CheckResult>;
+  at: string;
+}
+
+export interface HealthOptions {
+  checks?: Record<string, CheckFn | CheckSpec>;
+  timeoutMs?: number;
+  cacheMs?: number;
+  verbose?: boolean;
+  now?: () => number;
+}
+
+export interface Health {
+  run(): Promise<HealthReport>;
+  ready(req: IncomingMessage, res: ServerResponse): Promise<void>;
+  live(req: IncomingMessage, res: ServerResponse): void;
+}
+
+export function createHealth(options?: HealthOptions): Health;

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@sandsoftwaresolutions/health",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Live and ready health endpoints with timeouts, caching and degraded state, for Docker and load balancers.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test && node scripts/build-cjs.mjs --check",
+    "pack:check": "npm pack --dry-run",
+    "build": "node scripts/build-cjs.mjs",
+    "prepack": "node scripts/build-cjs.mjs"
+  },
+  "keywords": [
+    "health",
+    "readiness",
+    "liveness",
+    "docker"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SandSoftwareSolutions/ss-health.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SandSoftwareSolutions/ss-health/issues"
+  },
+  "homepage": "https://github.com/SandSoftwareSolutions/ss-health#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,41 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/** Gets a signal that aborts when the check times out. */
+export type CheckFn = (signal: AbortSignal) => unknown | Promise<unknown>;
+export interface CheckSpec {
+  check: CheckFn;
+  /** Default: the global timeoutMs. */
+  timeoutMs?: number;
+  /** A failing critical check makes the service "down" (default true); otherwise "degraded". */
+  critical?: boolean;
+}
+
+export interface CheckResult {
+  status: "up" | "down";
+  ms: number;
+  critical: boolean;
+  /** Only with `verbose: true`. */
+  error?: string;
+}
+
+export interface HealthReport {
+  status: "ok" | "degraded" | "down";
+  checks: Record<string, CheckResult>;
+  at: string;
+}
+
+export interface HealthOptions {
+  checks?: Record<string, CheckFn | CheckSpec>;
+  timeoutMs?: number;
+  cacheMs?: number;
+  verbose?: boolean;
+  now?: () => number;
+}
+
+export interface Health {
+  run(): Promise<HealthReport>;
+  ready(req: IncomingMessage, res: ServerResponse): Promise<void>;
+  live(req: IncomingMessage, res: ServerResponse): void;
+}
+
+export function createHealth(options?: HealthOptions): Health;

package/src/index.js

@@ -0,0 +1,117 @@
+// setTimeout fires after 1 ms for anything above this, which would report a slow check as timed out at once.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const TIMED_OUT = Symbol("timed out");
+
+/**
+ * A health check for a service. `checks` maps a name to a function (or `{ check, timeoutMs, critical }`) that throws or returns
+ * false when something is wrong; it gets an AbortSignal that aborts on timeout. A check is not called again while an earlier
+ * call of it is still running. A failing critical check (the default) makes the service "down"; a failing non-critical one
+ * only "degraded". Results are cached for `cacheMs` and concurrent calls share one run, so a busy load balancer cannot
+ * hammer your database. Error details are only included with `verbose: true`.
+ */
+export function createHealth({ checks = {}, timeoutMs = 2000, cacheMs = 1000, verbose = false, now = Date.now } = {}) {
+  const checkTimeout = (value, where) => {
+    if (typeof value !== "number" || Number.isNaN(value) || value <= 0) throw new RangeError(`createHealth: ${where} must be a number of milliseconds above 0`);
+    return Math.min(value, MAX_TIMER_MS);
+  };
+  const globalTimeout = checkTimeout(timeoutMs, "timeoutMs");
+  if (typeof cacheMs !== "number" || Number.isNaN(cacheMs) || cacheMs < 0) throw new RangeError("createHealth: cacheMs must be a number of milliseconds, 0 or more");
+  const entries = Object.entries(checks).map(([name, spec]) => {
+    const def = typeof spec === "function" ? { check: spec } : spec;
+    if (typeof def?.check !== "function") throw new TypeError(`createHealth: check "${name}" must be a function`);
+    if (def.critical !== undefined && typeof def.critical !== "boolean") throw new TypeError(`createHealth: critical of check "${name}" must be true or false`);
+    return [name, { check: def.check, timeoutMs: def.timeoutMs === undefined ? globalTimeout : checkTimeout(def.timeoutMs, `timeoutMs of check "${name}"`), critical: def.critical ?? true, inFlight: false }];
+  });
+  let cached = null;
+  let running = null;
+
+  async function runOne(name, def) {
+    const started = now();
+    let state = "up";
+    let error;
+    if (def.inFlight) {
+      // The earlier call has not come back yet. Calling again would add one more hung call (and connection) per probe.
+      state = "down";
+      error = "the previous call of this check is still running";
+    } else {
+      const controller = new AbortController();
+      let timer;
+      const timedOut = new Promise((resolve) => {
+        timer = setTimeout(resolve, def.timeoutMs, TIMED_OUT);
+        timer.unref?.();
+      });
+      def.inFlight = true;
+      const call = Promise.resolve().then(() => def.check(controller.signal));
+      const settled = () => { def.inFlight = false; };
+      call.then(settled, settled);
+      try {
+        const outcome = await Promise.race([call, timedOut]);
+        if (outcome === TIMED_OUT) {
+          state = "down";
+          error = `timed out after ${def.timeoutMs} ms`;
+          controller.abort(new Error(error));
+        } else if (outcome === false) {
+          state = "down";
+          error = "check returned false";
+        }
+      } catch (e) {
+        state = "down";
+        error = e?.message ?? String(e);
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    const result = { status: state, ms: Math.max(0, now() - started), critical: def.critical };
+    if (error && verbose) result.error = error;
+    return [name, result];
+  }
+
+  async function execute() {
+    const results = Object.fromEntries(await Promise.all(entries.map(([name, def]) => runOne(name, def))));
+    const failed = Object.values(results).filter((r) => r.status === "down");
+    const status = failed.some((r) => r.critical) ? "down" : failed.length > 0 ? "degraded" : "ok";
+    return { status, checks: results, at: new Date(now()).toISOString() };
+  }
+
+  /** Runs the checks (or returns the cached result). */
+  async function run() {
+    const age = cached ? now() - cached.time : -1; // a clock that stepped back (negative age) does not keep the cache alive
+    if (cached && age >= 0 && age < cacheMs) return cached.report;
+    running ??= execute().then(
+      (report) => {
+        cached = { time: now(), report };
+        running = null;
+        return report;
+      },
+      (error) => {
+        running = null;
+        throw error;
+      }
+    );
+    return running;
+  }
+
+  const send = (res, code, body) => {
+    res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+  };
+
+  return {
+    run,
+    /** Request handler for `/ready`: 200 for ok and degraded, 503 for down (also when the run itself breaks). */
+    async ready(_req, res) {
+      let report;
+      try {
+        report = await run();
+      } catch {
+        if (!res.headersSent) send(res, 503, { status: "down" });
+        return;
+      }
+      send(res, report.status === "down" ? 503 : 200, report);
+    },
+    /** Request handler for `/live`: 200 as long as the process can answer. No checks, so a slow database never restarts the app. */
+    live(_req, res) {
+      send(res, 200, { status: "ok" });
+    }
+  };
+}