# `@suaveplan/websocket-gateway` health probes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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.