@darco2903/pulse 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darco2903
+
+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,102 @@
-# Temporary Holding Version
+# @darco2903/pulse
 
-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.
+`/health` endpoint and Docker healthcheck for Node.js web servers. No dependencies, works with Express and `node:http`.
+
+## Installation
+
+```sh
+npm install @darco2903/pulse
+```
+
+## Usage
+
+```ts
+import { health, binary } from "@darco2903/pulse";
+
+// Before the request logger and the catch-all routes
+app.use(
+  health({
+    version: pkg.version,
+    logger, // pino, console...
+    checks: {
+      db: { check: () => db.query("SELECT 1"), critical: true },
+      ffmpeg: binary("ffmpeg", ["-version"]),
+    },
+  }),
+);
+```
+
+`GET /health`:
+
+```json
+{
+  "status": "ok",
+  "version": "2.3.0",
+  "commit": "05cb060",
+  "buildTime": "2026-11-05T10:00:00Z",
+  "uptime": 3600,
+  "checks": { "db": "ok", "ffmpeg": "ok" }
+}
+```
+
+| Status     | When                       | HTTP |
+| ---------- | -------------------------- | ---- |
+| `ok`       | every check passes         | 200  |
+| `degraded` | a non-critical check fails | 200  |
+| `down`     | a critical check fails     | 503  |
+
+The endpoint is public, so it only says whether each check passed. Why a check failed, and what a check returned (like the version of a binary), is logged instead, and only when a check changes state, so a failing check doesn't flood the logs.
+
+### Options
+
+| Option      | Default                                          |
+| ----------- | ------------------------------------------------ |
+| `version`   | required                                         |
+| `commit`    | `$GIT_COMMIT`, then `git rev-parse --short HEAD` |
+| `buildTime` | `$BUILD_TIME`                                    |
+| `path`      | `/health`                                        |
+| `checks`    | none                                             |
+| `timeout`   | `2000` ms per check                              |
+| `logger`    | `console`                                        |
+
+### Checks
+
+A check fails when it throws, rejects or times out.
+
+| Field      | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| `check`    | the function to run                                  |
+| `critical` | if it fails, the app is `down` instead of `degraded` |
+| `once`     | run once at startup and keep the result              |
+| `timeout`  | overrides the `timeout` option                       |
+
+`binary(command, args = ["--version"])` is a `once` check that runs a binary and logs the first line of its output.
+
+Concurrent requests share one run of the checks. For a server that isn't Express or `node:http`, `createHealth(options).getHealth()` gives the report without the HTTP part.
+
+## Docker
+
+```dockerfile
+ARG GIT_COMMIT
+ARG BUILD_TIME
+ENV GIT_COMMIT=$GIT_COMMIT BUILD_TIME=$BUILD_TIME
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+    CMD ["node", "node_modules/@darco2903/pulse/dist/healthcheck.js"]
+```
+
+With the build args passed in `compose.yml`:
+
+```yaml
+build:
+  context: .
+  args:
+    GIT_COMMIT: ${GIT_COMMIT:-}
+    BUILD_TIME: ${BUILD_TIME:-}
+```
+
+```bash
+GIT_COMMIT=$(git rev-parse --short HEAD) BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) docker compose up -d --build
+```
+
+`healthcheck.js` exits 0 when the endpoint answers 200 (`ok` or `degraded`). It calls the URL given as first argument, then `$HEALTHCHECK_URL`, then `https://127.0.0.1:$SERVER_PORT/health`. The certificate isn't verified on loopback, since it is for the public domain.

package/dist/checks.d.ts

@@ -0,0 +1,7 @@
+import type { Check } from "./types.js";
+/**
+ * Checks that a binary (ffmpeg, yt-dlp...) runs, once at startup. Its version (first line of
+ * the output) is logged.
+ * @param args ffmpeg needs ["-version"]
+ */
+export declare function binary(command: string, args?: string[], options?: Omit<Check, "check" | "once">): Check;

package/dist/checks.js

@@ -0,0 +1,22 @@
+import { execFile } from "child_process";
+/**
+ * Checks that a binary (ffmpeg, yt-dlp...) runs, once at startup. Its version (first line of
+ * the output) is logged.
+ * @param args ffmpeg needs ["-version"]
+ */
+export function binary(command, args = ["--version"], options = {}) {
+    return {
+        ...options,
+        once: true,
+        check: () => new Promise((resolve, reject) => {
+            execFile(command, args, (err, stdout) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(stdout.split("\n")[0].trim());
+                }
+            });
+        }),
+    };
+}

package/dist/health.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "http";
+import type { HealthOptions, HealthReport } from "./types.js";
+/** The health report without the HTTP part, for servers that aren't Express or node:http */
+export declare function createHealth(options: HealthOptions): {
+    getHealth: () => Promise<HealthReport>;
+};
+/**
+ * Middleware answering GET and HEAD on /health, works with Express and node:http. Register it
+ * before the request logger and the catch-all routes.
+ */
+export declare function health(options: HealthOptions): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;

package/dist/health.js

@@ -0,0 +1,110 @@
+import { execFileSync } from "child_process";
+const DEFAULT_TIMEOUT = 2000;
+async function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+async function runCheck(check, timeout) {
+    try {
+        // Through then() so a check that throws synchronously is a failure too
+        const value = await withTimeout(Promise.resolve().then(() => check.check()), check.timeout ?? timeout);
+        return { ok: true, detail: typeof value === "string" && value ? value : undefined };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** For dev, where the build args aren't set */
+function gitCommit() {
+    try {
+        const commit = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return commit || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The health report without the HTTP part, for servers that aren't Express or node:http */
+export function createHealth(options) {
+    const logger = options.logger ?? console;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const checks = Object.entries(options.checks ?? {});
+    // || and not ??: an unset Docker build arg gives an empty variable
+    const commit = options.commit ?? (process.env.GIT_COMMIT || gitCommit());
+    const buildTime = options.buildTime ?? (process.env.BUILD_TIME || null);
+    // Only changes are logged, so a check failing on every healthcheck doesn't flood the logs
+    const lastOk = new Map();
+    const run = async (name, check) => {
+        return runCheck(check, timeout).then((result) => {
+            if (lastOk.get(name) !== result.ok) {
+                lastOk.set(name, result.ok);
+                if (result.ok) {
+                    logger.info(`Health check ${name} OK${result.detail ? `: ${result.detail}` : ""}`);
+                }
+                else {
+                    logger.warn(`Health check ${name} failed: ${result.error}`);
+                }
+            }
+            return result;
+        });
+    };
+    const onceResults = new Map(checks.filter(([, check]) => check.once).map(([name, check]) => [name, run(name, check)]));
+    const evaluate = async () => {
+        const results = await Promise.all(checks.map(([name, check]) => onceResults.get(name) ?? run(name, check)));
+        const failed = checks.filter((_, i) => !results[i].ok);
+        const status = failed.some(([, check]) => check.critical)
+            ? "down"
+            : failed.length > 0
+                ? "degraded"
+                : "ok";
+        return {
+            status,
+            version: options.version,
+            commit,
+            buildTime,
+            uptime: Math.floor(process.uptime()),
+            ...(checks.length > 0 && {
+                checks: Object.fromEntries(checks.map(([name], i) => [name, results[i].ok ? "ok" : "fail"])),
+            }),
+        };
+    };
+    let pending = null;
+    /** Requests that come in while the checks run share their result, a burst doesn't multiply them */
+    const getHealth = () => {
+        pending ??= evaluate().finally(() => {
+            pending = null;
+        });
+        return pending;
+    };
+    return { getHealth };
+}
+/**
+ * Middleware answering GET and HEAD on /health, works with Express and node:http. Register it
+ * before the request logger and the catch-all routes.
+ */
+export function health(options) {
+    const path = options.path ?? "/health";
+    const { getHealth } = createHealth(options);
+    return (req, res, next) => {
+        const pathname = req.url?.split("?")[0];
+        if (pathname !== path || (req.method !== "GET" && req.method !== "HEAD")) {
+            next();
+            return;
+        }
+        getHealth().then((report) => {
+            const body = JSON.stringify(report);
+            res.writeHead(report.status === "down" ? 503 : 200, {
+                "Content-Type": "application/json; charset=utf-8",
+                "Content-Length": Buffer.byteLength(body),
+                "Cache-Control": "no-store",
+            });
+            res.end(req.method === "HEAD" ? undefined : body);
+        }, next);
+    };
+}

package/dist/healthcheck.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/healthcheck.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * For Docker HEALTHCHECK: exits 0 when /health answers 200 (ok or degraded), 1 otherwise.
+ * The URL is the first argument, then $HEALTHCHECK_URL, then https://127.0.0.1:$SERVER_PORT/health
+ */
+import http from "http";
+import https from "https";
+const url = new URL(process.argv[2] ?? process.env.HEALTHCHECK_URL ?? `https://127.0.0.1:${process.env.SERVER_PORT ?? 8080}/health`);
+const LOOPBACK = ["127.0.0.1", "localhost", "[::1]"];
+const options = {
+    // The certificate is for the public domain, not for 127.0.0.1: there is nothing to verify on loopback
+    rejectUnauthorized: !LOOPBACK.includes(url.hostname),
+    timeout: 4000,
+};
+function onResponse(res) {
+    res.resume();
+    if (res.statusCode !== 200) {
+        console.error(`${url} answered ${res.statusCode}`);
+    }
+    process.exit(res.statusCode === 200 ? 0 : 1);
+}
+const req = url.protocol === "http:" ? http.get(url, options, onResponse) : https.get(url, options, onResponse);
+req.on("timeout", () => req.destroy(new Error(`${url} timed out`)));
+req.on("error", (err) => {
+    console.error(err.message);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { health, createHealth } from "./health.js";
+export { binary } from "./checks.js";
+export type { Check, HealthOptions, HealthReport, HealthStatus, Logger } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { health, createHealth } from "./health.js";
+export { binary } from "./checks.js";

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+export interface Check {
+    /** Throws or rejects when the check fails. A returned string (a version...) is logged, never sent */
+    check: () => unknown;
+    /** A failing critical check makes the app "down" (503), any other one only "degraded" (200) */
+    critical?: boolean;
+    /** Run once at startup and keep the result, for things that don't change while the app runs */
+    once?: boolean;
+    /** In milliseconds, defaults to the timeout of the options */
+    timeout?: number;
+}
+/** pino, console... */
+export interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+export interface HealthOptions {
+    version: string;
+    /** Defaults to $GIT_COMMIT, then to `git rev-parse --short HEAD` */
+    commit?: string;
+    /** Defaults to $BUILD_TIME */
+    buildTime?: string;
+    /** Defaults to /health */
+    path?: string;
+    checks?: Record<string, Check>;
+    /** Timeout of each check in milliseconds, defaults to 2000 */
+    timeout?: number;
+    /** Defaults to console */
+    logger?: Logger;
+}
+export type HealthStatus = "ok" | "degraded" | "down";
+/** Public: check results are only ok/fail, the reason of a failure is logged */
+export interface HealthReport {
+    status: HealthStatus;
+    version: string;
+    commit: string | null;
+    buildTime: string | null;
+    /** In seconds */
+    uptime: number;
+    checks?: Record<string, "ok" | "fail">;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@darco2903/pulse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "author": "Darco2903",
+  "description": "/health endpoint and Docker healthcheck for Node.js web servers",
+  "keywords": [
+    "health",
+    "healthcheck",
+    "express",
+    "docker"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "pulse-check": "dist/healthcheck.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "homepage": "https://github.com/Darco2903/pulse#readme",
+  "bugs": {
+    "url": "https://github.com/Darco2903/pulse/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Darco2903/pulse.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit && tsc -p tests",
+    "test": "vitest run",
+    "clean": "rimraf -g dist darco2903-pulse-*.tgz"
+  }
 }