Build a Health Check Endpoint System

npm install hono @hono/node-server pg ioredis zod
npm install -D typescript tsx @types/node @types/pg

// src/health/checks.ts: dependency checks, probes and a cached detailed report
import { statfs } from "node:fs/promises";
import { Hono } from "hono";
import { Pool } from "pg";
import { Redis } from "ioredis";
import { z } from "zod";

const env = z
  .object({
    DATABASE_URL: z.string().url(),
    REDIS_URL: z.string().url(),
    APP_VERSION: z.string().default("unknown"),
    HEALTH_CACHE_MS: z.coerce.number().int().min(0).default(10_000),
  })
  .parse(process.env);

// Short timeouts: a health check must fail fast instead of hanging with the dependency
const pool = new Pool({ connectionString: env.DATABASE_URL, max: 2, connectionTimeoutMillis: 2000, query_timeout: 3000 });
pool.on("error", () => {}); // an idle connection dropped by a restarting database would otherwise crash the process
const redis = new Redis(env.REDIS_URL, { maxRetriesPerRequest: 1, commandTimeout: 2000, enableOfflineQueue: false });
redis.on("error", () => {}); // outages show up in the check result, not as unhandled events

type Status = "healthy" | "degraded" | "unhealthy";
interface Check {
  name: string;
  status: Status;
  latencyMs: number;
  message?: string;
  details?: Record<string, unknown>;
}

const startTime = Date.now();
const uptime = () => Math.round((Date.now() - startTime) / 1000);

async function timed(name: string, fn: () => Promise<Omit<Check, "name" | "latencyMs">>): Promise<Check> {
  const start = Date.now();
  try {
    return { name, latencyMs: Date.now() - start, ...(await fn()) };
  } catch (err) {
    return { name, status: "unhealthy", latencyMs: Date.now() - start, message: (err as Error).message };
  }
}

const checkPostgres = () =>
  timed("postgresql", async () => {
    const t = Date.now();
    await pool.query("SELECT 1");
    const latency = Date.now() - t;
    return { status: latency > 1000 ? "degraded" : "healthy" };
  });

const checkRedis = () =>
  timed("redis", async () => {
    const t = Date.now();
    const pong = await redis.ping();
    const latency = Date.now() - t;
    return { status: pong !== "PONG" ? "unhealthy" : latency > 500 ? "degraded" : "healthy" };
  });

const checkDisk = () =>
  timed("disk", async () => {
    const s = await statfs("/");
    const usedPercent = Math.round((1 - s.bavail / s.blocks) * 100);
    return {
      status: usedPercent > 90 ? "unhealthy" : usedPercent > 80 ? "degraded" : "healthy",
      details: { usedPercent, availableGB: Math.round((s.bavail * s.bsize) / 1e9) },
    };
  });

const checkMemory = () =>
  timed("memory", async () => {
    const m = process.memoryUsage();
    const heapUsedMB = Math.round(m.heapUsed / 1048576);
    return { status: heapUsedMB > 1500 ? "degraded" : "healthy", details: { heapUsedMB, rssMB: Math.round(m.rss / 1048576) } };
  });

// For third-party dependencies you can live without: they can only make the app "degraded"
export const checkExternal = (name: string, url: string, timeoutMs = 5000) =>
  timed(name, async () => {
    const t = Date.now();
    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
    return { status: res.ok && Date.now() - t < 3000 ? "healthy" : "degraded", details: { statusCode: res.status } };
  });

const rank: Record<Status, number> = { healthy: 0, degraded: 1, unhealthy: 2 };

async function runAllChecks() {
  const checks = await Promise.all([checkPostgres(), checkRedis(), checkDisk(), checkMemory()]);
  const status = checks.reduce<Status>((w, c) => (rank[c.status] > rank[w] ? c.status : w), "healthy");
  return { status, version: env.APP_VERSION, uptime: uptime(), timestamp: new Date().toISOString(), checks };
}

// Cache the report in-process so frequent pollers cannot turn /health into load on the database
let cached: { at: number; value: Awaited<ReturnType<typeof runAllChecks>> } | undefined;
async function getReport() {
  if (!cached || Date.now() - cached.at > env.HEALTH_CACHE_MS) {
    cached = { at: Date.now(), value: await runAllChecks() };
  }
  return cached.value;
}

const app = new Hono();

// Liveness: the process answers. No dependency checks on purpose.
app.get("/healthz", (c) => c.json({ status: "ok", uptime: uptime() }));

// Readiness: 503 takes the pod out of the Service endpoints without restarting it
app.get("/readyz", async (c) => {
  const [db, cache] = await Promise.all([checkPostgres(), checkRedis()]);
  const ready = db.status !== "unhealthy" && cache.status !== "unhealthy";
  return c.json({ ready, database: db.status, cache: cache.status }, ready ? 200 : 503);
});

// Detailed report: 503 only when something is down; "degraded" still answers 200
app.get("/health", async (c) => {
  const report = await getReport();
  return c.json(report, report.status === "unhealthy" ? 503 : 200);
});

// Startup: the app is initialized once the database answers
app.get("/startupz", async (c) => {
  const db = await checkPostgres();
  return db.status === "unhealthy" ? c.json({ started: false, reason: "database not ready" }, 503) : c.json({ started: true });
});

export default app;

// src/server.ts
import { serve } from "@hono/node-server";
import app from "./health/checks";

serve({ fetch: app.fetch, port: 8080, hostname: "0.0.0.0" }); // pods are reached over the pod network

containers:
  - name: api
    startupProbe:
      httpGet: { path: /startupz, port: 8080 }
      periodSeconds: 5
      failureThreshold: 30     # up to 150 s to boot before the pod is restarted
    livenessProbe:
      httpGet: { path: /healthz, port: 8080 }
      periodSeconds: 10
      timeoutSeconds: 2
      failureThreshold: 3
    readinessProbe:
      httpGet: { path: /readyz, port: 8080 }
      periodSeconds: 5
      timeoutSeconds: 3
      failureThreshold: 2