first commit

docs/networking/network/websocket-gateway/src/health/health.md

@@ -0,0 +1,59 @@
+# `@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.