Health Check

pnpm dlx blockend-cli add health-check

// health status of the entire system
export type HealthStatus = "healthy" | "degraded" | "unhealthy";

// status of an individual check
export type CheckStatus = "healthy" | "unhealthy";

export interface HealthCheck {
  /** Unique name of the check. Example: "database", "redis" */
  name: string;

  /** Whether failure should make the application unhealthy. */
  critical: boolean;

  /** Optional human-friendly message shown when the check fails. */
  message?: string;

  /** Timeout for this specific check in milliseconds. Prevents hanging. */
  timeoutMs?: number;

  /** Actual health check implementation. Throw an error if it fails. */
  run(): Promise<void>;
}

export interface HealthCheckResult {
  name: string;
  critical: boolean;
  status: CheckStatus;
  duration: number; // in milliseconds
  message?: string;
  error?: string; // Sanitized to string to prevent leaking stack traces
}

export interface HealthReport {
  status: HealthStatus;
  timestamp: string;
  uptime: number; // in seconds
  checks: HealthCheckResult[];
}

// Extension points: Allow teams to override default policies
export type StatusCalculator = (results: HealthCheckResult[]) => HealthStatus;
export type ReportBuilder = (results: HealthCheckResult[], status: HealthStatus) => HealthReport;

export interface CreateHealthOptions {
  checks: HealthCheck[];
  /** Global fallback timeout in milliseconds (default: 5000) */
  defaultTimeoutMs?: number;
  /** Optional custom status calculation logic */
  calculateStatus?: StatusCalculator;
  /** Optional custom report generation logic */
  buildReport?: ReportBuilder;
}

export interface Health {
  run(): Promise<HealthReport>;
}

import type { CreateHealthOptions } from "../types/index";

export function validateConfig(options: CreateHealthOptions): void {
  if (!options.checks || !Array.isArray(options.checks)) {
    throw new Error("Health configuration error: 'checks' must be a valid array.");
  }

  if (options.checks.length === 0) {
    throw new Error("Health configuration error: 'checks' array cannot be empty.");
  }

  const names = new Set<string>();

  for (const check of options.checks) {
    if (!check.name || typeof check.name !== "string" || check.name.trim() === "") {
      throw new Error(
        "Health configuration error: Each check must have a non-empty string 'name'."
      );
    }

    if (names.has(check.name)) {
      throw new Error(
        `Health configuration error: Duplicate check name found: "${check.name}". Names must be unique.`
      );
    }
    names.add(check.name);

    if (typeof check.run !== "function") {
      throw new Error(
        `Health configuration error: Check "${check.name}" is missing a valid 'run' function.`
      );
    }

    if (
      check.timeoutMs !== undefined &&
      (typeof check.timeoutMs !== "number" || check.timeoutMs <= 0)
    ) {
      throw new Error(
        `Health configuration error: Check "${check.name}" has an invalid 'timeoutMs'. It must be a positive number.`
      );
    }
  }

  if (
    options.defaultTimeoutMs !== undefined &&
    (typeof options.defaultTimeoutMs !== "number" || options.defaultTimeoutMs <= 0)
  ) {
    throw new Error("Health configuration error: 'defaultTimeoutMs' must be a positive number.");
  }
}

import type { HealthCheck, HealthCheckResult } from "../types/index";

export async function runCheck(
  check: HealthCheck,
  defaultTimeoutMs = 5000
): Promise<HealthCheckResult> {
  const start = performance.now();
  const timeout = check.timeoutMs ?? defaultTimeoutMs;

  try {
    // Enforce timeout to prevent a single slow dependency from hanging the entire health request
    const timeoutPromise = new Promise<never>((_, reject) => {
      setTimeout(() => reject(new Error(`Check timed out after ${timeout}ms`)), timeout);
    });

    await Promise.race([check.run(), timeoutPromise]);

    return {
      name: check.name,
      critical: check.critical,
      status: "healthy",
      duration: performance.now() - start,
      ...(check.message === undefined ? {} : { message: check.message })
    };
  } catch (error) {
    const duration = performance.now() - start;

    // Sanitize error: never expose raw Error objects (stack traces) in production APIs
    const errorMessage = error instanceof Error ? error.message : String(error);

    return {
      name: check.name,
      critical: check.critical,
      status: "unhealthy",
      duration,
      ...(check.message === undefined ? {} : { message: check.message }),
      error: errorMessage
    };
  }
}

import type { HealthCheck, HealthCheckResult } from "../types/index";
import { runCheck } from "./run-check";

export async function runChecks(
  checks: HealthCheck[],
  defaultTimeoutMs?: number
): Promise<HealthCheckResult[]> {
  const tasks = checks.map((check) => runCheck(check, defaultTimeoutMs));
  return await Promise.all(tasks);
}

import type { HealthCheckResult, HealthStatus } from "../types/index";

export function calculateStatus(results: HealthCheckResult[]): HealthStatus {
  const hasCriticalFailure = results.some(
    (result) => result.critical && result.status === "unhealthy"
  );

  if (hasCriticalFailure) {
    return "unhealthy";
  }

  const hasOptionalFailure = results.some(
    (result) => !result.critical && result.status === "unhealthy"
  );

  if (hasOptionalFailure) {
    return "degraded";
  }

  return "healthy";
}

import type { HealthCheckResult, HealthReport, HealthStatus } from "../types/index";

export function buildReport(results: HealthCheckResult[], status: HealthStatus): HealthReport {
  // Safely get uptime for Node.js, fallback to 0 for other environments
  const uptime =
    typeof process !== "undefined" && typeof process.uptime === "function" ? process.uptime() : 0;

  return {
    status,
    checks: results,
    timestamp: new Date().toISOString(),
    uptime
  };
}

import type { CreateHealthOptions, Health } from "../types/index";
import { buildReport as defaultBuildReport } from "./build-report";
import { calculateStatus as defaultCalculateStatus } from "./calculate-status";
import { runChecks } from "./run-checks";
import { validateConfig } from "./validate-config";

export function createHealth(options: CreateHealthOptions): Health {
  // Fail fast: Validate configuration immediately upon creation
  validateConfig(options);

  // Allow teams to override default policies if business rules differ
  const calculateStatus = options.calculateStatus ?? defaultCalculateStatus;
  const buildReport = options.buildReport ?? defaultBuildReport;

  return {
    async run() {
      const results = await runChecks(options.checks, options.defaultTimeoutMs);
      const status = calculateStatus(results);
      return buildReport(results, status);
    }
  };
}

import type { Express, Request, Response } from "express";
import type { Health } from "../types/index"; // Adjust path to your core block

export function registerExpressHealthRoute(app: Express, health: Health, path = "/health") {
  app.get(path, async (_req: Request, res: Response) => {
    const report = await health.run();

    // 503 for unhealthy (pull from load balancer)
    // 200 for healthy/degraded (keep in rotation, let the JSON report show the degraded state)
    const statusCode = report.status === "unhealthy" ? 503 : 200;

    res.status(statusCode).json(report);
  });
}

import type { FastifyInstance } from "fastify";
import type { Health } from "../types/index";
export function registerFastifyHealthRoute(app: FastifyInstance, health: Health, path = "/health") {
  app.get(path, async (_request, reply) => {
    const report = await health.run();
    const statusCode = report.status === "unhealthy" ? 503 : 200;

    reply.code(statusCode).send(report);
  });
}

import type { Hono } from "hono";
import type { Health } from "../types/index";

export function registerHonoHealthRoute(app: Hono, health: Health, path = "/health") {
  app.get(path, async (c) => {
    const report = await health.run();
    const statusCode = report.status === "unhealthy" ? 503 : 200;

    return c.json(report, statusCode);
  });
}