`@suaveplan/websocket-gateway` health probes

(no submodules)

Purpose

Inline implementation of the three Kubernetes-style health verbs (/health, /ready, /live) that the daemon hosts on the same TCP port as the WebSocket upgrade endpoint. The proposal explicitly defers full integration with @suaveplan/health-check until that package ships — this module is the standalone replacement and the contract stays stable once health-check lands.

Features

classifyHealthRequest(url) — pure URL-path classifier; ignores querystrings and trailing slashes.
buildHealthResponse(verb, snap) — pure decision function returning the HTTP status + body for one verb.
handleHealth(url, snap) — single-call wrapper returning {status, body} or null so the daemon can short-circuit health requests before falling through to the WS upgrade path.
Status discriminator (ok / degraded / starting / stopped) carries enough state for k8s probes and human dashboards.

Usage: Basic Example

import { handleHealth } from "@suaveplan/websocket-gateway";

const result = handleHealth(req.url, {
    running: true,
    disposed: false,
    clientCount: 7,
    roomCount: 2,
    startedAt: 1700000000000,
});
if (result) res.writeHead(result.status).end(result.body);

Usage: Advanced Example

import {
    buildHealthResponse,
    classifyHealthRequest,
    type HealthSnapshot,
} from "@suaveplan/websocket-gateway";

const snap: HealthSnapshot = gateway.snapshot();
const verb = classifyHealthRequest("/ready?probe=k8s");
if (verb !== null) {
    const decision = buildHealthResponse(verb, snap);
    metrics.ready_probe.add(1, { status: decision.body.status });
}

API Reference

HEALTH_PATHS — frozen mapping of verb → path string.
classifyHealthRequest(url): HealthKind — returns "health" | "ready" | "live" | null.
buildHealthResponse(verb, snap): {status, body} — returns the HTTP status + JSON-encodable body for a verb.
handleHealth(url, snap): {status, body} | null — combined classify + build returning the serialized response body.
HealthSnapshot, HealthResponse, HealthKind, HealthPath — supporting types.

Implementation Notes

live returns 200 unless stop() has cleared state (process is up but daemon-internal storage is torn down). ready returns 503 with status: "starting" until start() resolves so cluster ingress holds traffic until the daemon is actually accepting WebSocket upgrades. health is the catch-all aggregate verb consumers can wire to PagerDuty / Prometheus. The functions are pure to keep the daemon under the 300-line cap and to let unit tests cover every branch without booting a server.

2.7 KiB Raw Permalink Blame History

@suaveplan/websocket-gateway health probes