Health Check#

Health check endpoints for monitoring application status, database connectivity, and dependencies.

Warning

Do NOT wrap healthCheck() with app.get(). The function registers the route itself. Wrapping it will create duplicate routes or cause unexpected behavior.

Basic Usage#

typescript

import { healthCheck } from "@buntok/core/middlewares";

// Simple health check at /health
healthCheck(app);

Options#

Option	Type	Default	Description
path	string	"/health"	Endpoint path
check	() => Promise<HealthStatus>	undefined	Custom health check function
includeUptime	boolean	true	Include uptime in response
version	string	undefined	Buntok version in response

Database Check#

typescript

import { healthCheck, createDatabaseCheck } from "@buntok/core/middlewares";

healthCheck(app, {
  check: createDatabaseCheck(async () => {
    await db.$queryRaw`SELECT 1`;
    return true; // healthy
  }),
});

Combined Checks#

Use createHealthCheck to combine multiple checks:

typescript

import { healthCheck, createHealthCheck } from "@buntok/core/middlewares";

healthCheck(app, {
  version: "1.0.0",
  check: createHealthCheck([
    {
      name: "database",
      check: async () => {
        await db.$queryRaw`SELECT 1`;
        return true;
      },
    },
    {
      name: "redis",
      check: async () => {
        await redis.ping();
        return true;
      },
    },
    {
      name: "external-api",
      check: async () => {
        const res = await fetch("https://api.example.com/health");
        return res.ok;
      },
    },
  ]),
});

Response#

typescript

// Healthy (200)
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600,
  "version": "1.0.0",
  "checks": {
    "database": { "status": "up", "duration": 12 },
    "redis": { "status": "up", "duration": 3 }
  }
}

// Unhealthy (503)
{
  "status": "unhealthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "checks": {
    "database": { "status": "down", "message": "Connection refused" }
  }
}

Kubernetes Liveness & Readiness Probes#

Kubernetes-ready health check endpoints for container orchestration.

typescript

import { livenessCheck, readinessCheck } from "@buntok/core/middlewares";

// Liveness probe - is the process alive?
livenessCheck(app, { path: "/health/live" });  // default: "/health/live"

// Readiness probe - can it serve traffic?
readinessCheck(app, {
  path: "/health/ready",
  checks: [
    async () => {
      const dbOk = await checkDbConnection();
      return dbOk
        ? { status: "healthy" }
        : { status: "unhealthy", message: "DB unreachable" };
    },
  ],
});

Function	Description
livenessCheck(app, opts?)	Register liveness endpoint - always returns `200 OK` if server is running
readinessCheck(app, opts?)	Register readiness endpoint - runs `checks` array, returns `200` if all healthy
runReadinessChecks(checks)	Execute `ReadinessCheck[]` and aggregate results

Custom Check Function#

typescript

healthCheck(app, {
  check: async () => {
    const dbOk = await checkDatabase();
    const redisOk = await checkRedis();
    const diskOk = await checkDiskSpace();

    if (dbOk && redisOk && diskOk) {
      return { status: "healthy" };
    }
    if (!dbOk) {
      return {
        status: "unhealthy",
        message: "Database is down",
        checks: { database: { status: "down" } },
      };
    }
    return {
      status: "degraded",
      message: "Some services unavailable",
      checks: {
        database: { status: "up" },
        redis: { status: redisOk ? "up" : "down" },
        disk: { status: diskOk ? "up" : "down" },
      },
    };
  },
});

PreviousAudit Log Next FFI / Native