Health

@absolutejs/healthv0.3.0betaPlatform & Infra

Liveness and readiness probes for Bun services — one Elysia plugin exposing /healthz and /readyz with a standard JSON envelope.

Gives any Elysia app on Bun the /healthz and /readyz endpoints that load balancers and Kubernetes-style orchestrators expect, with a standard application/health+json envelope. createHealthChecker composes named checks with per-check timeouts, and the aggregate status is the worst of any check, so a single failing dependency flips the envelope to 503. Bundled check factories cover downstream HTTP dependencies, arbitrary probes, and metrics() snapshots from other @absolutejs packages.

#Installation

BASH

bun add @absolutejs/health

#Capabilities

Overview

Liveness + readiness probes for the AbsoluteJS substrate. One Elysia plugin, two endpoints, a standard JSON envelope that load balancers and Kubernetes-style orchestrators understand out of the box.

Two endpoints, two semantics

Endpoint — Purpose — Used by

/healthz — "Is this process alive?" If fail, the orchestrator restarts the container. — Kubernetes liveness probe, systemd WatchdogSec, @absolutejs/runtime

/readyz — "Can this instance serve traffic right now?" If fail, the LB stops routing to it (but doesn't kill it). — Load balancer health checks, drain workflows

Show 3 more

The distinction matters: a draining instance returns readyz: fail

healthz: pass. The LB stops sending new traffic while in-flight

requests finish.

Body shape

Compatible with the IETF health-check JSON draft and the Kubernetes livez / readyz conventions. content-type: application/health+json.

Status codes

pass → 200 OK

warn → 200 OK (don't reroute traffic; surface in your dashboard)

fail → 503 Service Unavailable

Show 1 more

LBs route on status code; humans + dashboards read the body.

Aggregation

Status is the WORST of any check: fail > warn > pass. A single failing dependency fails the whole envelope — same as Kubernetes /healthz rollup behavior.

Check factories

probeCheck wraps any promise (resolve = pass, throw = fail), httpCheck grades a downstream URL by status code, and metricsCheck evaluates a metrics() snapshot into pass/warn/fail with observed values for dashboards.

Kind filtering

Each check declares a kind ('liveness', 'readiness', or 'both') so heavy downstream checks run only under /readyz and liveness stays a cheap process-responsiveness probe.

Liveness vs readiness

/healthz answers "is this process alive?" (fail means restart it); /readyz answers "can it serve traffic right now?" (fail means stop routing, keep it running). A draining instance fails readiness while liveness stays green.

Standards-compatible envelope

The JSON body follows the IETF health-check draft and Kubernetes livez/readyz conventions, served as application/health+json with Cache-Control: no-store.

Worst-of-any aggregation

Status rolls up as fail > warn > pass. warn still returns 200 — the LB keeps routing while your dashboard surfaces the degradation.

Outcomes

What you can build

Overview

Liveness + readiness probes for the AbsoluteJS substrate. One Elysia plugin, two endpoints, a standard JSON envelope that load balancers and Kubernetes-style orchestrators understand out of the box.

Two endpoints, two semantics

Endpoint — Purpose — Used by

Body shape

Compatible with the IETF health-check JSON draft and the Kubernetes livez / readyz conventions. content-type: application/health+json.

Hardening checklist

Production guidance

OverviewLiveness + readiness probes for the AbsoluteJS substrate. One Elysia plugin, two endpoints, a standard JSON envelope that load balancers and Kubernetes-style orchestrators understand out of the box.

Kind filteringA check's kind ('liveness' / 'readiness' / 'both', default 'both') controls which endpoint runs it. Run heavy downstream checks under readiness only; keep liveness limited to "the JS process is responsive."

Follow in order

Troubleshooting path

Trace from the first failed boundary

Reproduce the smallest canonical @absolutejs/health example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#@absolutejs/health quick start

Partial snippet

# @absolutejs/health

import { Elysia } from 'elysia';
import {
  createHealthChecker,
  healthPlugin,
  metricsCheck,
  probeCheck,
  httpCheck,
} from '@absolutejs/health';

const checker = createHealthChecker({
  checks: [
    // Synthesis from a substrate package's metrics() snapshot.
    metricsCheck('queue', () => worker.metrics(), (m) => ({
      status: m.failed > 100 ? 'warn' : 'pass',
      observed: { runs: m.runs, failed: m.failed },
    })),

    // Wrap an arbitrary probe.
    probeCheck('postgres', () => pg.query('SELECT 1')),

    // Downstream HTTP dependency.
    httpCheck('otlp-collector', 'http://collector:4318/healthz', {
      kind: 'readiness',  // run only under /readyz
    }),
  ],
});

const app = new Elysia().use(await healthPlugin({ checker }));
// GET /healthz → liveness:  200 / 503 with { status, checks, at }
// GET /readyz  → readiness: same shape, filtered to readiness + both

#Body shape

Partial snippet

Working example for Body shape.

JSON

{
  "status": "pass",
  "at": 1717161600000,
  "checks": {
    "queue": {
      "status": "pass",
      "latencyMs": 1,
      "observed": { "runs": 1057, "failed": 0 }
    },
    "postgres": { "status": "pass", "latencyMs": 12 }
  }
}

#Kind filtering

Partial snippet

Working example for Kind filtering.

{ name: 'shutting-down', kind: 'readiness', check: () => ({
  status: draining ? 'fail' : 'pass'
})}

#Quick Start

Partial snippet

Compose named checks and mount the plugin — two endpoints with a standard envelope, no per-route wiring.

import { Elysia } from 'elysia';
import {
  createHealthChecker,
  healthPlugin,
  metricsCheck,
  probeCheck,
  httpCheck,
} from '@absolutejs/health';

const checker = createHealthChecker({
  checks: [
    // Evaluate a metrics() snapshot into pass/warn/fail.
    metricsCheck('queue', () => worker.metrics(), (m) => ({
      status: m.failed > 100 ? 'warn' : 'pass',
      observed: { runs: m.runs, failed: m.failed },
    })),

    // Wrap an arbitrary probe.
    probeCheck('postgres', () => pg.query('SELECT 1')),

    // Downstream HTTP dependency, readiness only.
    httpCheck('otlp-collector', 'http://collector:4318/healthz', {
      kind: 'readiness',
    }),
  ],
});

const app = new Elysia().use(await healthPlugin({ checker }));
// GET /healthz -> liveness:  200 / 503 with { status, checks, at }
// GET /readyz  -> readiness: same shape, readiness + both checks

#Drain-Aware Readiness

Partial snippet

A readiness-only check lets an instance drain gracefully: the load balancer stops sending new traffic while in-flight requests finish.

const checker = createHealthChecker({
  checks: [
    {
      name: 'shutting-down',
      kind: 'readiness',
      check: () => ({ status: draining ? 'fail' : 'pass' }),
    },
  ],
});
// While draining: /readyz -> 503 (LB stops routing),
// /healthz -> 200 (orchestrator does NOT restart the process)

Beta

The package is pre-1.0. The endpoint semantics follow established conventions and are unlikely to move, but the check-factory signatures may see minor adjustments before a stable release.

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

13 symbols

HealthStatustypePermalink

@absolutejs/health — liveness + readiness probes for the AbsoluteJS substrate. Two endpoints behind one Elysia plugin: - GET /healthz (liveness): is this process alive at all? Used by orchestrators (Kubernetes, systemd, runtime supervisors) to decide when to restart a container. - GET /readyz (readiness): can this instance serve traffic RIGHT NOW? Used by load balancers to decide when to route requests. Returning false while liveness still passes is the "drain me but don't kill me" state. Body s

type HealthStatus = 'pass' | 'warn' | 'fail';

Exported from @absolutejs/health

GitHub npm

Current package surface

What ships today

@absolutejs/healthv0.3.0 · betaObservabilitynpm Source

3entry points14symbols

Import surface · click to copy

PreviousAutoscaler NextOps CLI