@dunx/http 2.0.0 → 2.1.0

package/README.md

@@ -144,13 +144,17 @@ behind `~standard` changed, and reports what each one costs per request:
 | Valibot                     |  0.89 µs | built in                |
 | zod                         |  0.94 µs | built in                |
 
-**`await req.json()` on the same request costs 3.10 µs**, which is more than all of
-them put together. So validation is not where a slow endpoint's time goes, and
-swapping zod for a compiled validator buys about 7% of a small request - worth having
-if a profile points at it, not worth restructuring for. zod is what `@dunx/openapi`
-reads schemas from (via `z.toJSONSchema`), and it is the default for that reason
-rather than a performance one. Three fields, though: a deeply nested schema would very
-likely separate these engines much further.
+**`await req.json()` on the same request costs 3.10 µs**, which is more than
+all of them put together.
+
+So validation is not where a slow endpoint's time goes, and swapping zod for a
+compiled validator buys about 7% of a small request - worth having if a profile
+points at it, though not worth restructuring for. zod is what `@dunx/openapi`
+reads schemas from (via `z.toJSONSchema`), and it is the default for that
+reason rather than a performance one.
+
+Three fields, though: a deeply nested schema would very likely separate these
+engines much further.
 
 Two of the five ship no `~standard` property. Bridging one is small enough to inline -
 this is the whole of it:
@@ -181,7 +185,7 @@ Full numbers, methodology and the ajv version:
 ## Route metadata and scoped middleware
 
 A decorator annotates a route; a guard reads the annotation back. Metadata on its
-own enforces nothing - which is why `@Roles` needs a guard that looks at it, and
+own enforces nothing, so `@Roles` needs a guard that looks at it, and
 why one global guard plus `@Public()` is the combination worth learning.
 
 ```ts
@@ -317,7 +321,7 @@ Every request produces **one** structured entry, request and response together:
 }
 ```
 
-One entry, not two, is the point. The common arrangement logs on the way in from a middleware and on
+One entry per request, never two. The common arrangement logs on the way in from a middleware and on
 the way out from an interceptor, because they are different classes and the
 interceptor cannot see what the middleware saw. Here they are the same closure, so
 there is no pair to correlate by `requestId` to find out how a call ended. A 4xx
@@ -371,12 +375,14 @@ HttpFactory.create(AppModule, {
 });
 ```
 
-**Even at its cheapest, a log line is not free.** `internal/bench` carries `dunx` and
-`dunx-logging` as separate subjects for exactly this reason: with logging off dunx
-runs at 81-100% of raw `Bun.serve` depending on the scenario, and with it on, 40-45%.
+**Even at its cheapest, a log line is not free.** `internal/bench` carries
+`dunx` and `dunx-logging` as separate subjects for exactly this reason: with
+logging off dunx runs at 81-100% of raw `Bun.serve` depending on the scenario,
+and with it on, 40-45%.
+
 The remainder is `JSON.stringify` plus a `write` per request inside an
-`AsyncLocalStorage` scope. If you need the last of the throughput, turn it off and
-sample at the edge instead - but know what you gave up.
+`AsyncLocalStorage` scope. If you need the last of the throughput, turn it off
+and sample at the edge instead - but know what you gave up.
 
 ### Unmatched paths are logged too
 
@@ -392,10 +398,11 @@ fallback runs only after it has decided nothing matched.
 
 A route with **no middleware and no CORS** is dispatched by a handler in which
 nothing is `async`. It returns a `Response` rather than a `Promise<Response>`
-wherever it has nothing to wait for - Bun accepts either. The general path awaits the
-input reader, the handler and the response coercion, and for most shapes those awaits
-are on values that were never thenable, each costing an async frame and a microtask
-tick for nothing.
+wherever it has nothing to wait for - Bun accepts either.
+
+The general path awaits the input reader, the handler and the response
+coercion, and for most shapes those awaits are on values that were never
+thenable, each costing an async frame and a microtask tick for nothing.
 
 | Route shape                              | What it costs                             |
 | ---------------------------------------- | ----------------------------------------- |
@@ -412,6 +419,84 @@ writing sync code.
 Adding middleware - including `requestLogging` - opts a route back into the async
 path, because middleware is `async` by contract.
 
+## Health checks and draining
+
+Two routes, `/health/live` and `/health/ready`, and the drain phase that makes the
+second one worth having.
+
+```ts
+import {
+  DatabaseIndicator,
+  HealthModule,
+  MemoryIndicator,
+  MemoryOptions,
+  RedisIndicator,
+} from '@dunx/http';
+
+HealthModule.forRootAsync({
+  useFactory: (db: DbConnection, redis: RedisConnection) => ({
+    readiness: [new DatabaseIndicator(db), new RedisIndicator(redis)],
+    liveness: [
+      new MemoryIndicator(new MemoryOptions({ maxRssBytes: 512 * 1024 ** 2 })),
+    ],
+    drainDelayMs: 15_000,
+  }),
+  inject: [DbConnection, RedisConnection],
+});
+```
+
+The report is one list, so finding the unhappy check is one place to look:
+
+```json
+{
+  "status": "up",
+  "draining": false,
+  "uptimeMs": 41233,
+  "checks": [{ "name": "database", "state": "up", "critical": true, "ms": 1 }]
+}
+```
+
+`up` is 200 and anything else is 503, which is what an orchestrator reads to stop
+routing without restarting.
+
+**Readiness fails before the port closes**, and that ordering is the feature.
+`Readiness` implements `@dunx/core`'s `OnDrain`, which runs while the server is
+still accepting. Every `onShutdown` hook runs after `server.stop()` has resolved, so
+a probe answering from one answers on a closed socket.
+
+`drainDelayMs` keeps readiness failing for a few probe intervals before the socket
+goes, because a load balancer notices on its own schedule.
+
+Liveness deliberately keeps passing while draining. A pod that is shutting down does
+not need restarting, and reporting `down` there invites a SIGKILL mid-drain.
+
+**Three states, not two.** A check that throws is `down`; one that outruns
+`timeoutMs` is `unknown`, because a probe that did not answer has told you nothing.
+`unknown` on a critical check fails readiness and on a non-critical one it does not.
+
+**`critical: false` reports without shedding traffic.** `MemoryIndicator` and
+`DiskIndicator` ship that way: a disk at 91% is worth seeing, and pulling the pod
+out of rotation does not help, since no other pod's disk is emptier. A memory
+ceiling belongs on liveness, where the orchestrator restarts the process.
+
+`Readiness` is injectable, so a handler can `hold('migrating')` and `release()` to
+take the pod out of rotation without shutting down. A `release()` does not undo a
+shutdown.
+
+There is no startup probe. The port already answers that: `create()` finishes every
+`onInit` before `listen()` binds, so connection refused *is* "not started yet".
+
+`MemoryIndicator` uses `process.memoryUsage()` at 5.96 us. `jsc.heapStats()` walks
+every live object at 2.2 ms and up, and `Bun.generateHeapSnapshot()` is hundreds of
+milliseconds, so neither belongs on a path scraped every two seconds.
+
+Bun ships no disk API, so `DiskIndicator` is `node:fs`'s **async** `statfs` at 167 us
+rather than `statfsSync` at 1.85 us. A stalled network mount blocks the loop for as
+long as it stalls, and a health check is what gets called while one is stalling.
+
+`routes: false` binds everything and mounts nothing, for an app answering on its own
+paths.
+
 ## App-level configuration
 
 `create()` boots the container and discovers routes; `listen()` is what builds the
@@ -448,25 +533,26 @@ could only ever be a silent no-op - the failure mode worth trading for an error.
 - **Port**: the `listen(port)` argument, else `HttpOptions.port`, else `3000`.
 - **Error mapper**: `HttpOptions.onError`; there is no imperative equivalent.
 - **Overrides**: `HttpOptions.overrides` is core's `AppOptions.overrides`, passed
-  straight through - bindings replaced in place, which is what `@dunx/testing`'s
+  straight through, bindings replaced in place, as `@dunx/testing`'s
   `createTestServer` uses.
 - **Repeated calls**: `setGlobalPrefix`, `set` and `enableCors` all replace, so the
   last call wins. `use()` appends.
 - **Collisions**: rejected at `create()`, and re-checked at `listen()` against the
   final prefixed paths. A uniform prefix cannot introduce a collision the
-  unprefixed paths did not already have, which is why the early check is complete.
+  unprefixed paths did not already have, so the early check is complete.
 
 ### CORS and preflight
 
-`Bun.serve({ routes })` answers a method miss with `404`, so a preflight can never
-be inferred - `enableCors()` mounts an explicit `OPTIONS` handler on every path,
-built at boot from the methods that path actually declares. `origin` takes a
-string, a list, or a predicate; anything not allowed gets **no** CORS headers at
-all, which is what makes the browser block it. `'*'` is the default, and because a
-browser rejects `*` alongside credentials, `credentials: true` reflects the
-caller's origin instead. `allowedHeaders` defaults to echoing
-`Access-Control-Request-Headers`. Headers are applied outside the error mapper, so
-a mapped `500` still carries them.
+`Bun.serve({ routes })` answers a method miss with `404`, so a preflight can
+never be inferred - `enableCors()` mounts an explicit `OPTIONS` handler on
+every path, built at boot from the methods that path actually declares.
+`origin` takes a string, a list, or a predicate; anything not allowed gets
+**no** CORS headers at all, and the absence is what makes the browser block it.
+
+`'*'` is the default, and because a browser rejects `*` alongside credentials,
+`credentials: true` reflects the caller's origin instead. `allowedHeaders`
+defaults to echoing `Access-Control-Request-Headers`. Headers are applied
+outside the error mapper, so a mapped `500` still carries them.
 
 ### Client IP
 
@@ -611,20 +697,21 @@ smallest one that works:
 { "event": "chat.say", "data": { "room": "general", "text": "hi" } }
 ```
 
-It is **opt-in**: a frame is only parsed for a gateway that declares at least one
-`@OnMessage(event)` handler. A gateway with only a raw `@OnMessage()` never sees
-JSON it did not ask for. Binary frames, invalid JSON, a non-object, a missing
-`event`, and an event no handler claims all fall through to the raw handler - and
-are ignored if there is none. Nothing is ever replied to the sender that a handler
-did not return.
+It is **opt-in**: a frame is only parsed for a gateway that declares at least
+one `@OnMessage(event)` handler. A gateway with only a raw `@OnMessage()` never
+sees JSON it did not ask for.
+
+Binary frames, invalid JSON, a non-object, a missing `event`, and an event no
+handler claims all fall through to the raw handler - and are ignored if there
+is none. Nothing is ever replied to the sender that a handler did not return.
 
 `encode(event, data)` and `decode(frame)` are exported, so a client can share them.
-A handler's payload parameter type is what you expect to receive, not a runtime
+A handler's payload parameter type states what you expect to receive, with no runtime
 guarantee: the frame's `data` is handed over as it arrived.
 
 ### Pub/sub
 
-Topics live in Bun, not in a JavaScript map. A socket joins one with
+Topics live in Bun rather than in a JavaScript map. A socket joins one with
 `socket.subscribe(topic)` and leaves with `socket.unsubscribe(topic)`; both are
 native methods on the socket you already hold.
 
@@ -675,12 +762,14 @@ the default logs.
 
 ### Shutdown with a live socket
 
-Measured: a graceful `server.stop()` waits for open connections, and a WebSocket
-does not close on its own - so it **never resolves** while a socket is open. An app
-with at least one gateway therefore force-stops (`stop(true)`) in `shutdown()`, and
-those clients see a `1006` close. An app with no gateways still stops gracefully.
-Bun also delivers an empty close `reason` to `@OnClose` once a socket has exchanged
-frames, whatever the client passed; the `code` is reliable.
+Measured: a graceful `server.stop()` waits for open connections, and a
+WebSocket does not close on its own - so it **never resolves** while a socket
+is open. An app with at least one gateway therefore force-stops (`stop(true)`)
+in `shutdown()`, and those clients see a `1006` close. An app with no gateways
+still stops gracefully.
+
+Bun also delivers an empty close `reason` to `@OnClose` once a socket has
+exchanged frames, whatever the client passed; the `code` is reliable.
 
 ### Multi-node fan-out
 
@@ -744,14 +833,14 @@ subscriptions on one channel is the other way to deliver everything twice.
 cross nodes goes through `PubSub`. `subscriberCount` is local too - Bun cannot count
 another node's sockets.
 
-`maxRetries` on `RedisRelay` defaults to `0`, and that is deliberate: a
+`maxRetries` on `RedisRelay` defaults to `0`: a
 `Bun.RedisClient` that never connects keeps a retry timer alive past `close()` and
 the process then never exits. Raise it when Redis is a hard requirement and you want
 Bun's reconnection.
 
 ## Status codes
 
-`HttpStatusCode` is a frozen object, not an `enum` - one name serving as both the
+`HttpStatusCode` is a frozen object rather than an `enum`, one name serving as both the
 value and the type, so it reads like an enum and erases like a constant:
 
 ```ts
@@ -806,7 +895,7 @@ export class Rates {
 ```
 
 `fetch` and nothing else underneath: it is a Web standard Bun implements natively,
-which is why `axios` and `node-fetch` are banned repo-wide and why there is no
+so `axios` and `node-fetch` are banned repo-wide and there is no
 client dependency to justify. What the service adds is the part every caller
 otherwise rewrites slightly differently.
 
@@ -818,7 +907,7 @@ otherwise rewrites slightly differently.
 | **URLs** | `buildUrl` and `interpolate` from `@arkv/shared`, so `{param}` and query building are not rewritten |
 | **Tracing** | The inbound request id is forwarded as `x-request-id`, so one trace spans both services |
 | **Bun-only** | `proxy`, `tls`, `unix`, `decompress` passed straight through to `fetch` |
-| **SSE** | `streamSse` yields each `data:` payload; deliberately never retried |
+| **SSE** | `streamSse` yields each `data:` payload; never retried |
 
 ### A failure is not your status
 

package/dist/{chunk-5z96f3gr.js → chunk-sz4pvqxy.js}

@@ -18,6 +18,7 @@ var __defNormalProp = (obj, key, value) => (key in obj) ? __defProp(obj, key, {
 var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
 var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
 var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
@@ -104,7 +105,7 @@ var HttpStatusCode = Object.freeze({
   GATEWAY_TIMEOUT: 504
 });
 
-export { __decoratorStart, __decoratorMetadata, __runInitializers, __decorateElement, HttpStatusCode };
+export { __privateGet, __privateAdd, __decoratorStart, __decoratorMetadata, __runInitializers, __decorateElement, HttpStatusCode };
 
-//# debugId=83F76F267D9DFA2264756E2164756E21
-//# sourceMappingURL=chunk-5z96f3gr.js.map
+//# debugId=463DAE47FB741BC964756E2164756E21
+//# sourceMappingURL=chunk-sz4pvqxy.js.map

package/dist/{chunk-5z96f3gr.js.map → chunk-sz4pvqxy.js.map}

@@ -4,7 +4,7 @@
   "sourcesContent": [
     "/**\n * Frozen object plus an indexed-access union, not an `enum`. An enum emits a\n * runtime object that no other syntax can produce, which is why the repo bans it -\n * see CLAUDE.md. This gives the same `HttpStatusCode.NOT_FOUND` ergonomics, a\n * narrower type, and erases cleanly.\n */\nexport const HttpStatusCode = Object.freeze({\n  OK: 200,\n  CREATED: 201,\n  ACCEPTED: 202,\n  NO_CONTENT: 204,\n  MOVED_PERMANENTLY: 301,\n  FOUND: 302,\n  NOT_MODIFIED: 304,\n  TEMPORARY_REDIRECT: 307,\n  PERMANENT_REDIRECT: 308,\n  BAD_REQUEST: 400,\n  UNAUTHORIZED: 401,\n  PAYMENT_REQUIRED: 402,\n  FORBIDDEN: 403,\n  NOT_FOUND: 404,\n  METHOD_NOT_ALLOWED: 405,\n  NOT_ACCEPTABLE: 406,\n  REQUEST_TIMEOUT: 408,\n  CONFLICT: 409,\n  GONE: 410,\n  PRECONDITION_FAILED: 412,\n  PAYLOAD_TOO_LARGE: 413,\n  URI_TOO_LONG: 414,\n  UNSUPPORTED_MEDIA_TYPE: 415,\n  IM_A_TEAPOT: 418,\n  UNPROCESSABLE_ENTITY: 422,\n  TOO_MANY_REQUESTS: 429,\n  INTERNAL_SERVER_ERROR: 500,\n  NOT_IMPLEMENTED: 501,\n  BAD_GATEWAY: 502,\n  SERVICE_UNAVAILABLE: 503,\n  GATEWAY_TIMEOUT: 504,\n} as const);\n\n/** The status numbers: `200 | 201 | ...`. */\nexport type HttpStatusCode =\n  (typeof HttpStatusCode)[keyof typeof HttpStatusCode];\n\n/** The names: `'OK' | 'CREATED' | ...`. */\nexport type HttpStatusName = keyof typeof HttpStatusCode;\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMO,IAAM,iBAAiB,OAAO,OAAO;AAAA,EAC1C,IAAI;AAAA,EACJ,SAAS;AAAA,EACT,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,mBAAmB;AAAA,EACnB,OAAO;AAAA,EACP,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,aAAa;AAAA,EACb,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,UAAU;AAAA,EACV,MAAM;AAAA,EACN,qBAAqB;AAAA,EACrB,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,wBAAwB;AAAA,EACxB,aAAa;AAAA,EACb,sBAAsB;AAAA,EACtB,mBAAmB;AAAA,EACnB,uBAAuB;AAAA,EACvB,iBAAiB;AAAA,EACjB,aAAa;AAAA,EACb,qBAAqB;AAAA,EACrB,iBAAiB;AACnB,CAAU;",
-  "debugId": "83F76F267D9DFA2264756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMO,IAAM,iBAAiB,OAAO,OAAO;AAAA,EAC1C,IAAI;AAAA,EACJ,SAAS;AAAA,EACT,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,mBAAmB;AAAA,EACnB,OAAO;AAAA,EACP,cAAc;AAAA,EACd,oBAAoB;AAAA,EACpB,oBAAoB;AAAA,EACpB,aAAa;AAAA,EACb,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,WAAW;AAAA,EACX,WAAW;AAAA,EACX,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,UAAU;AAAA,EACV,MAAM;AAAA,EACN,qBAAqB;AAAA,EACrB,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,wBAAwB;AAAA,EACxB,aAAa;AAAA,EACb,sBAAsB;AAAA,EACtB,mBAAmB;AAAA,EACnB,uBAAuB;AAAA,EACvB,iBAAiB;AAAA,EACjB,aAAa;AAAA,EACb,qBAAqB;AAAA,EACrB,iBAAiB;AACnB,CAAU;",
+  "debugId": "463DAE47FB741BC964756E2164756E21",
   "names": []
 }

package/dist/client.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   HttpStatusCode
-} from "./chunk-5z96f3gr.js";
+} from "./chunk-sz4pvqxy.js";
 
 // src/client/errors.ts
 import { AppError } from "@dunx/core";

package/dist/health/contracts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The state a probe reports.
+ *
+ * `unknown` is not `down`. A probe that timed out has told you nothing, and the
+ * difference decides whether traffic is shed: `unknown` on a critical check fails
+ * readiness, on a non-critical one it does not. `@dunx/dashboard` had this rule
+ * first and re-exports these two from here.
+ */
+export type ProbeState = 'up' | 'down' | 'unknown';
+export interface ProbeResult {
+    readonly state: ProbeState;
+    /** One line for the operator: a latency, a version, a failure message. */
+    readonly detail?: string;
+}
+/**
+ * One thing worth checking.
+ *
+ * An abstract class rather than an interface because it is an injection site: the
+ * container needs a runtime value to record, and an interface there is a boot
+ * error. Subclass it, or hand `HealthOptions` any object with the three members.
+ */
+export declare abstract class HealthIndicator {
+    abstract readonly name: string;
+    /**
+     * Whether a failure here should shed traffic. `true` by default.
+     *
+     * `false` reports without gating readiness, which is what memory and disk want: a
+     * disk at 91 percent is worth seeing and is not worth pulling the pod out of
+     * rotation for, since no other pod is any emptier.
+     */
+    readonly critical: boolean;
+    abstract check(): Promise<ProbeResult> | ProbeResult;
+}
+/**
+ * Enough of a client to answer "is it up". `RedisConnection` from
+ * `@dunx/infra/redis` satisfies it as written, and so does a bare
+ * `Bun.RedisClient`.
+ *
+ * Narrower than `@dunx/dashboard`'s `RedisProbe` on purpose, and they are not
+ * merged. That one also needs `connected` and `send`, because it renders an `INFO`
+ * panel; this needs a round trip and nothing else. Sharing one contract would
+ * oblige an app to hand a health check two members it never calls.
+ */
+export declare abstract class PingProbe {
+    abstract ping(message?: string): Promise<string>;
+}
+/**
+ * A database that can be asked for a round trip. `DbConnection` from
+ * `@dunx/infra/db` satisfies it once it grows `ping()`.
+ *
+ * Separate from {@link PingProbe} because the return types differ: a Redis `PING`
+ * answers `PONG` and a database round trip answers nothing worth reading.
+ */
+export declare abstract class QueryProbe {
+    abstract ping(): Promise<void>;
+}

package/dist/health/controller.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Two routes, not three. A startup probe is already answered by the port: `create()`
+ * finishes every `onInit` before `listen()` binds, so a connection refused *is* "not
+ * started yet" and a third endpoint would restate it.
+ *
+ * `@Public()` because a probe has no credentials, and `@ApiHidden()` because these
+ * are for the orchestrator rather than for an API consumer. Both are the existing
+ * route metadata; there is nothing health-specific about either.
+ */
+export declare class HealthController {
+    #private;
+    /**
+     * Is the process working. A failure here means restart me.
+     *
+     * Draining deliberately does not fail this: a pod shutting down does not need
+     * killing, and reporting `down` invites a SIGKILL mid-drain.
+     */
+    live(): Promise<Response>;
+    /** Should the process receive traffic. Fails from the moment the drain starts. */
+    ready(): Promise<Response>;
+}

package/dist/health/indicators.d.ts

@@ -0,0 +1,71 @@
+import { HealthIndicator, type PingProbe, type ProbeResult, type QueryProbe } from './contracts.js';
+/** Redis is up if it answers `PING`. */
+export declare class RedisIndicator extends HealthIndicator {
+    private readonly redis;
+    readonly name = "redis";
+    constructor(redis: PingProbe);
+    check(): Promise<ProbeResult>;
+}
+/** The database is up if a round trip completes. */
+export declare class DatabaseIndicator extends HealthIndicator {
+    private readonly db;
+    readonly name = "database";
+    constructor(db: QueryProbe);
+    check(): Promise<ProbeResult>;
+}
+export interface MemoryOptionsInit {
+    /** Report `down` above this resident set size. */
+    readonly maxRssBytes: number;
+}
+export declare class MemoryOptions {
+    readonly maxRssBytes: number;
+    constructor(init: MemoryOptionsInit);
+}
+/**
+ * Resident set size against a ceiling.
+ *
+ * `process.memoryUsage()` costs 5.96 us, which is what makes it safe on an endpoint
+ * scraped every two seconds. The alternatives were measured and rejected:
+ * `jsc.heapStats()` walks every live object at 2.2 ms and up,
+ * `v8.getHeapStatistics()` is 1 to 7.6 ms, and `Bun.generateHeapSnapshot()` is
+ * hundreds of milliseconds and megabytes. None belongs on this path.
+ *
+ * Not critical: a process near its ceiling is worth seeing, and shedding traffic
+ * from it does not make it use less memory. Liveness is where a ceiling belongs, so
+ * the orchestrator restarts it.
+ */
+export declare class MemoryIndicator extends HealthIndicator {
+    private readonly options;
+    readonly name = "memory";
+    readonly critical = false;
+    constructor(options: MemoryOptions);
+    check(): ProbeResult;
+}
+export interface DiskOptionsInit {
+    /** Any path on the filesystem to measure. */
+    readonly path: string;
+    /** Report `down` above this used fraction. `0.9` is 90 percent. */
+    readonly maxUsedFraction: number;
+}
+export declare class DiskOptions {
+    readonly path: string;
+    readonly maxUsedFraction: number;
+    constructor(init: DiskOptionsInit);
+}
+/**
+ * How full a filesystem is.
+ *
+ * Bun ships no disk API, so this is `node:fs`. The **async** `statfs` at 167 us,
+ * not `statfsSync` at 1.85 us, and the slower one is the right call: a stalled
+ * network mount blocks the event loop for as long as it stalls, and a health check
+ * is exactly what gets called while a mount is stalling.
+ *
+ * Not critical, for the same reason as memory: no other pod's disk is any emptier.
+ */
+export declare class DiskIndicator extends HealthIndicator {
+    private readonly options;
+    readonly name = "disk";
+    readonly critical = false;
+    constructor(options: DiskOptions);
+    check(): Promise<ProbeResult>;
+}

package/dist/health/module.d.ts

@@ -0,0 +1,40 @@
+import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
+import { type HealthOptionsInit } from './registry.js';
+/**
+ * Liveness and readiness, and the drain that makes readiness worth having.
+ *
+ * `Readiness` implements `OnDrain`, so readiness starts failing **before** the
+ * server stops accepting. Without that phase the flip was unexpressible: every
+ * `onShutdown` hook runs after `server.stop()` has resolved, so a probe answering
+ * from there answers on a closed port and the load balancer is still routing when
+ * the socket goes away.
+ *
+ * `routes: false` binds everything and mounts nothing, for an app that would rather
+ * answer on its own paths or from a sidecar.
+ */
+export declare class HealthModule {
+    static forRoot(init?: HealthOptionsInit): DynamicModule;
+    /**
+     * The same, with the indicators built from the container, which is the usual case:
+     * a database indicator needs the connection.
+     *
+     * ```ts
+     * HealthModule.forRootAsync({
+     *   useFactory: (db: DbConnection, redis: RedisConnection) => ({
+     *     readiness: [new DatabaseIndicator(db), new RedisIndicator(redis)],
+     *     drainDelayMs: 15_000,
+     *   }),
+     *   inject: [DbConnection, RedisConnection],
+     * });
+     * ```
+     *
+     * `routes` is read from the init here too, but the controller is mounted from the
+     * static shape rather than from the awaited options: a route table is folded into
+     * one closure per route when the server binds, so it cannot wait on a factory.
+     * Pass `routes: false` and mount your own if that matters.
+     */
+    static forRootAsync<const D extends Deps>(config: FactoryProvider<HealthOptionsInit, D> & {
+        readonly imports?: DynamicModule['imports'];
+        readonly routes?: boolean;
+    }): DynamicModule;
+}

package/dist/health/readiness.d.ts

@@ -0,0 +1,51 @@
+import type { OnDrain } from '@dunx/core';
+export interface ReadinessOptionsInit {
+    /**
+     * How long to keep failing readiness after the drain starts, before the server
+     * stops accepting. Default `0`.
+     *
+     * The window exists because a load balancer notices a failing probe on its own
+     * schedule: with a 2 second probe interval and a 3 failure threshold, traffic can
+     * arrive for 6 seconds after the pod has decided to go. Set it to a few probe
+     * intervals and the pod stops receiving before the socket closes, which is the
+     * whole reason this phase runs before `server.stop()`.
+     */
+    readonly drainDelayMs?: number;
+}
+/** A class, so it is a recordable constructor parameter type. */
+export declare class ReadinessOptions {
+    readonly drainDelayMs: number;
+    constructor(init?: ReadinessOptionsInit);
+}
+/**
+ * Whether this process wants traffic.
+ *
+ * Injectable, so a handler can pull the pod out of rotation for a migration and put
+ * it back. `hold` and `release` are for that; `onDrain` is for shutdown and does not
+ * release.
+ *
+ * This is what `OnDrain` was added to `@dunx/core` for. `HttpApplication.shutdown()`
+ * stopped the server before running any hook, so a readiness flip in `onShutdown`
+ * answered on a closed port, which is the wrong order: a load balancer has to see
+ * the probe fail while the port is still open.
+ */
+export declare class Readiness implements OnDrain {
+    #private;
+    private readonly options;
+    constructor(options: ReadinessOptions);
+    /** `true` once shutdown has begun, or while something holds the pod out. */
+    get draining(): boolean;
+    /** Why readiness is failing, for the report. */
+    get reason(): string | undefined;
+    /** Fail readiness until `release()`. Idempotent; the last reason wins. */
+    hold(reason: string): void;
+    release(): void;
+    /**
+     * Fails readiness, then waits, all before the server stops accepting.
+     *
+     * The wait is here rather than in the application because this is the thing that
+     * knows why it is waiting. `App.drain()` runs every hook under one `Promise.all`,
+     * so this window overlaps a queue worker's own drain instead of being added to it.
+     */
+    onDrain(): Promise<void>;
+}

package/dist/health/registry.d.ts

@@ -0,0 +1,64 @@
+import type { HealthIndicator, ProbeState } from './contracts.js';
+import type { Readiness } from './readiness.js';
+export interface HealthCheckReport {
+    readonly name: string;
+    readonly state: ProbeState;
+    readonly critical: boolean;
+    /** How long the check took, rounded to a millisecond. */
+    readonly ms: number;
+    readonly detail?: string;
+}
+/**
+ * The wire format, declared here and imported by anything that renders it.
+ *
+ * One list rather than terminus' four fields holding the same data partitioned
+ * three ways: a reader wants to know which check is unhappy, and partitioning by
+ * outcome means looking in three places to find out.
+ */
+export interface HealthReport {
+    readonly status: ProbeState;
+    readonly draining: boolean;
+    readonly uptimeMs: number;
+    readonly checks: readonly HealthCheckReport[];
+}
+export declare class HealthOptions {
+    readonly liveness: readonly HealthIndicator[];
+    readonly readiness: readonly HealthIndicator[];
+    readonly timeoutMs: number;
+    /** Mount `/health/live` and `/health/ready`. Default `true`. */
+    readonly routes: boolean;
+    /** How long to fail readiness before the server stops accepting. Default `0`. */
+    readonly drainDelayMs: number;
+    constructor(init?: HealthOptionsInit);
+}
+export interface HealthOptionsInit {
+    /** Checked by `/health/live`: is this process still working. */
+    readonly liveness?: readonly HealthIndicator[];
+    /** Checked by `/health/ready`: should it receive traffic. */
+    readonly readiness?: readonly HealthIndicator[];
+    /** Per-indicator budget. Default `2000`. */
+    readonly timeoutMs?: number;
+    readonly routes?: boolean;
+    /** Passed through to {@link ReadinessOptions}. */
+    readonly drainDelayMs?: number;
+}
+/** Runs the indicators and shapes the report. Never throws. */
+export declare class HealthRegistry {
+    #private;
+    private readonly options;
+    private readonly readiness_;
+    constructor(options: HealthOptions, readiness_: Readiness);
+    /**
+     * Concurrently, each bounded by `timeoutMs`, so the report costs the slowest
+     * check rather than their sum.
+     */
+    report(indicators: readonly HealthIndicator[]): Promise<HealthReport>;
+    /**
+     * Is the process working. **Draining does not fail liveness**: a pod that is
+     * shutting down is not a pod that needs killing, and reporting `down` here invites
+     * the orchestrator to SIGKILL it mid-drain.
+     */
+    liveness(): Promise<HealthReport>;
+    /** Should the process receive traffic. Draining fails it, before anything runs. */
+    readiness(): Promise<HealthReport>;
+}

package/dist/index.d.ts

@@ -27,3 +27,9 @@ export { defaultRelayUrl, RedisRelay, type RedisRelayOptions, } from './ws/redis
 export { decodeRelay, DEFAULT_RELAY_CHANNEL, encodeRelay, type PubSubRelay, type RelayFrame, type RelayOptions, type RelayPhase, } from './ws/relay.js';
 export { buildGateways, buildRuntime, type GatewayRuntime, } from './ws/runtime.js';
 export type { Socket, SocketData, SocketErrorHandler, SocketOptions, } from './ws/socket.js';
+export { HealthIndicator, PingProbe, QueryProbe, type ProbeResult, type ProbeState, } from './health/contracts.js';
+export { HealthController } from './health/controller.js';
+export { DatabaseIndicator, DiskIndicator, DiskOptions, MemoryIndicator, MemoryOptions, RedisIndicator, type DiskOptionsInit, type MemoryOptionsInit, } from './health/indicators.js';
+export { HealthModule } from './health/module.js';
+export { Readiness, ReadinessOptions } from './health/readiness.js';
+export { HealthOptions, HealthRegistry, type HealthCheckReport, type HealthOptionsInit, type HealthReport, } from './health/registry.js';