@sigil-dev/plugin-health

Adds a /health endpoint to your Grimoire application. In coordinator mode it fans out to all workers and aggregates their status, respecting your names defined in the namepool plugin In worker mode it reports local uptime, version, and any custom fields you provide.

Installation

bun add @sigil-dev/plugin-health

Why?

Unified health endpoint format allows for easier library development, for example a health -> Discord webhook or a headless status page

Usage

import { defineConfig } from "@sigil-dev/grimoire";
import { healthPlugin } from "@sigil-dev/plugin-health";

export default defineConfig({
  plugins: [
    healthPlugin(),
  ],
});

Hit /health to get a full cluster report:

{
  "ok": true,
  "version": "1.0.0",
  "uptime": 3600,
  "cluster": [
    { "name": "api-0", "status": "up", "pid": 1234, "version": "1.0.0", "lastSeen": 1718000000000 },
    { "name": "ws-0",  "status": "up", "pid": 1235, "version": "1.0.0", "lastSeen": 1718000000000 }
  ]
}

Returns 200 when all workers are up or reserved, 503 when any worker is down.

Options

interface HealthPluginOptions {
  /** Route to serve health at. Default: "/health" */
  path?: string;
  /** Extra fields to include in the response. */
  extend?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
  /** Worker names to track. Auto-detected from plugin-namepool if present. */
  names?: string[];
}

Custom fields

Use extend to add dependency health checks or any other metadata:

healthPlugin({
  extend: async () => ({
    db: await checkPostgres(),
    redis: await checkRedis(),
    version_sha: process.env.GIT_SHA,
  }),
})

Worker status values

| Status | Meaning | |---|---| | "up" | Worker is running and responding. | | "down" | Worker exists in coordinator but did not respond within 2 seconds. | | "reserved" | Name is in the pool but no worker slot is configured for it. |

"reserved" workers do not fail the health check — they indicate a name is allocated but not yet deployed.

Response shape

Coordinator (/health)

interface HealthResponse {
  ok: boolean;
  version: string;
  uptime: number;         // seconds since coordinator start
  cluster: WorkerHealth[];
  [key: string]: unknown; // any fields added via extend()
}

interface WorkerHealth {
  name: string;
  status: "up" | "down" | "reserved";
  pid?: number;
  version: string;
  lastSeen: number | null; // null if the worker never started
}

Worker (/health)

{
  ok: true,
  version: "1.0.0",
  uptime: 120,
  instanceId: "alpha",
  pid: 1234,
  // ...any fields from extend()
}

Integration with plugin-namepool

When @sigil-dev/plugin-namepool is also registered, plugin-health automatically detects it via the plugin registry and uses the name pool to report reserved workers. No configuration needed.

import { namepool } from "@sigil-dev/plugin-namepool";
import { healthPlugin } from "@sigil-dev/plugin-health";

export default defineConfig({
  plugins: [
    namepool({ names: ["alpha", "beta", "gamma"] }),
    healthPlugin(),
  ],
  scale: { api: 2 }, // only 2 workers — "gamma" shows as reserved
});