`health` — broker health snapshot

(no submodules)

Purpose

This module is the pure, side-effect-free evaluator for the broker's health status. It inspects the two underlying RESP clients (one publisher socket, one subscriber socket) and folds their isReady flags plus the broker's last observed error into a three-state status (up, degraded, down). The host's readiness endpoint consumes this snapshot to decide whether to report ready, partially ready, or unhealthy.

Keeping the evaluator pure means tests can probe every state combination deterministically without a real Redis container — the broker's integration test then pins that up is reached against a live container and that the snapshot recovers after a forced socket close.

Features

Three-state status (up, degraded, down) with clear documented semantics — degraded means in-flight publishes will queue per reconnect strategy; down means new publishes will fail fast with CONNECTION_LOST.
Pure function — no I/O, no global state, trivially testable.
Optional lastError propagation so dashboards can show the most recent underlying socket failure even after the broker has recovered.

Usage: Basic

import { evaluateBrokerHealth } from "@suaveplan/api-ws-broker-redis/health";

const snap = evaluateBrokerHealth(publisher, subscriber, lastError);
if (snap.status === "down") {
    return new Response("unavailable", { status: 503 });
}

Usage: Advanced

import { evaluateBrokerHealth } from "@suaveplan/api-ws-broker-redis/health";

// Custom readiness probe that distinguishes degraded vs down.
function readiness(): { status: number; body: unknown } {
    const snap = evaluateBrokerHealth(publisher, subscriber, lastError);
    if (snap.status === "up") {
        return { status: 200, body: { status: "ok" } };
    }
    if (snap.status === "degraded") {
        return {
            status: 200,
            body: {
                status: "degraded",
                publisherReady: snap.publisherReady,
                subscriberReady: snap.subscriberReady,
                lastError: snap.lastError,
            },
        };
    }
    return { status: 503, body: { status: "down", lastError: snap.lastError } };
}

API Reference

evaluateBrokerHealth(publisher, subscriber, lastError): BrokerHealthSnapshot — pure folder over the two clients.
BrokerHealthSnapshot { status, publisherReady, subscriberReady, lastError? }.
BrokerHealthStatus = "up" | "degraded" | "down".

Implementation Notes

The lastError field is set conditionally so the field is omitted from the snapshot (rather than carrying undefined) when no error has ever been observed. This matters for the JSON-serialised readiness response — a dashboard parsing lastError should see "absent" vs "present" as a clean boolean, not need to special-case null or undefined.

The publisher socket and subscriber socket are evaluated independently because Redis's subscribe-mode connection is a separate TCP socket from the reply-mode one; either can drop without the other. Operators see the actual state of each socket via publisherReady / subscriberReady so they can diagnose a partial outage (e.g. firewall dropping ESTABLISHED long-lived subscribe sockets) directly from the readiness endpoint.

3.3 KiB Raw Permalink Blame History

health — broker health snapshot