@dunx/http 2.3.1 → 2.4.0

package/dist/health/controller.d.ts

@@ -3,9 +3,9 @@
  * 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.
+ * `@Public()` because a probe has no credentials. Both routes are documented, under
+ * the `Health` tag; `HealthModule.forRoot({ documented: false })` mounts
+ * {@link HiddenHealthController} instead.
  */
 export declare class HealthController {
     #private;
@@ -19,3 +19,15 @@ export declare class HealthController {
     /** Should the process receive traffic. Fails from the moment the drain starts. */
     ready(): Promise<Response>;
 }
+/**
+ * The same two routes, kept out of the OpenAPI document.
+ *
+ * A subclass rather than a flag read when the module is registered, because
+ * `@ApiHidden()` writes to the class and a class is shared by every app in the
+ * process: `examples/full` boots a second container to demonstrate the websocket
+ * relay, so setting the flag at `forRoot` time would leak into the other one. The
+ * prefix and both handlers resolve through the prototype chain, so this is the
+ * whole implementation.
+ */
+export declare class HiddenHealthController extends HealthController {
+}

package/dist/health/module.d.ts

@@ -28,13 +28,14 @@ export declare class HealthModule {
      * });
      * ```
      *
-     * `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.
+     * `routes` and `documented` are 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;
+        readonly documented?: boolean;
     }): DynamicModule;
 }

package/dist/health/registry.d.ts

@@ -28,6 +28,8 @@ export declare class HealthOptions {
     readonly timeoutMs: number;
     /** Mount `/health/live` and `/health/ready`. Default `true`. */
     readonly routes: boolean;
+    /** Include the two routes in the OpenAPI document. Default `true`. */
+    readonly documented: boolean;
     /** How long to fail readiness before the server stops accepting. Default `0`. */
     readonly drainDelayMs: number;
     constructor(init?: HealthOptionsInit);
@@ -40,6 +42,12 @@ export interface HealthOptionsInit {
     /** Per-indicator budget. Default `2000`. */
     readonly timeoutMs?: number;
     readonly routes?: boolean;
+    /**
+     * `false` mounts `HiddenHealthController`, so the probes are served and left out
+     * of the document. They are documented by default: the paths and the report are
+     * worth finding in the reference, and an orchestrator reads neither.
+     */
+    readonly documented?: boolean;
     /** Passed through to {@link ReadinessOptions}. */
     readonly drainDelayMs?: number;
 }

package/dist/health/report-schema.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from '../route/schema.js';
+/**
+ * `HealthReport`, as a JSON Schema literal.
+ *
+ * A hand-written schema rather than a zod one, because `RouteSchemas.response`
+ * accepts either and this package has no validator dependency to spend on
+ * documenting two routes. `$id` hoists it into `components/schemas` once, so both
+ * probes and both statuses reference the same definition.
+ *
+ * It restates the `HealthReport` and `HealthCheckReport` interfaces, which is the
+ * one duplicate here: a type is erased and a document needs the shape at runtime.
+ * `health.test.ts` asserts the two agree.
+ */
+export declare const HEALTH_REPORT_SCHEMA: JsonSchema;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Controller, Delete, Get, Patch, Post, Put, } from './route/decorators.j
 export { discoverRoutes, joinPath, type DiscoveredRoute, } from './route/discover.js';
 export type { HttpMethod, RouteMeta, RoutePath } from './route/marker.js';
 export { ApiHidden, guardsOf, HIDDEN, meta, metaKey, metaOf, mergeMeta, Public, PUBLIC, Roles, ROLES, UNMATCHED, UseGuards, type MetaKey, type MetaRecord, } from './route/metadata.js';
-export type { InferOutput, Input, RouteInput, RouteSchemas, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from './route/schema.js';
+export type { InferOutput, Input, JsonSchema, RouteInput, RouteSchemas, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from './route/schema.js';
 export { gatewaysOf, routesOf, type GatewayHandler, type GatewayNode, type RouteInputs, type RouteNode, } from './inspect.js';
 export { ClientAddress } from './server/client-address.js';
 export { buildContext, type RouteContext } from './server/context.js';
@@ -36,8 +36,9 @@ export { decodeRelay, DEFAULT_RELAY_CHANNEL, encodeRelay, type PubSubRelay, type
 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 { HealthController, HiddenHealthController, } 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 { HEALTH_REPORT_SCHEMA } from './health/report-schema.js';
 export { Readiness, ReadinessOptions } from './health/readiness.js';
 export { HealthOptions, HealthRegistry, type HealthCheckReport, type HealthOptionsInit, type HealthReport, } from './health/registry.js';

package/dist/index.js

@@ -281,6 +281,7 @@ var buildContext = (route) => {
     handler: route.handlerName,
     method: route.method,
     path: route.path,
+    parsesBody: route.options?.body !== undefined,
     get: (key) => record.get(key.id)
   });
 };
@@ -970,6 +971,25 @@ import {
   RequestContext as RequestContext2
 } from "@dunx/core";
 
+// src/server/raw-body.ts
+var WANTED = Symbol.for("dunx.http.rawBody.wanted");
+var TEXT = Symbol.for("dunx.http.rawBody.text");
+
+class RawBody {
+  static want(req) {
+    req[WANTED] = true;
+  }
+  static wanted(req) {
+    return req[WANTED] === true;
+  }
+  static record(req, text) {
+    req[TEXT] = text;
+  }
+  static read(req) {
+    return req[TEXT];
+  }
+}
+
 // src/server/request-id.ts
 var REQUEST_ID_HEADER = "x-request-id";
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -1051,14 +1071,14 @@ class RequestLoggingMiddleware {
       flow: "http",
       context: `${ctx.controller}.${ctx.handler}`
     };
-    return this.#correlate ? this.context.runWithContext(scope, () => this.#begin(req, url, mark, path, requestId, started, next, undefined)) : this.#begin(req, url, mark, path, requestId, started, next, scope);
+    return this.#correlate ? this.context.runWithContext(scope, () => this.#begin(req, ctx, url, mark, path, requestId, started, next, undefined)) : this.#begin(req, ctx, url, mark, path, requestId, started, next, scope);
   }
-  #begin(req, url, mark, path, requestId, started, next, scope) {
+  #begin(req, ctx, url, mark, path, requestId, started, next, scope) {
     const request = {};
     if (mark !== -1) {
       request["query"] = Object.fromEntries(new URLSearchParams(url.slice(mark + 1)));
     }
-    const body = this.#body(req);
+    const body = this.#body(req, ctx);
     if (body === undefined) {
       request["userAgent"] = req.headers.get("user-agent");
       return this.#dispatch(req, path, requestId, started, request, next, scope);
@@ -1070,6 +1090,18 @@ class RequestLoggingMiddleware {
       return this.#dispatch(req, path, requestId, started, request, next, scope);
     });
   }
+  #shared(req, request) {
+    if (!this.#requestBody)
+      return;
+    if (request["body"] !== undefined)
+      return;
+    const text = RawBody.read(req);
+    if (text === undefined)
+      return;
+    const value = parse(text, this.#limit);
+    if (value !== undefined)
+      request["body"] = value;
+  }
   #correlated(req, ctx, path, next) {
     const requestId = RequestIds.assign(req);
     const stamp = (response) => {
@@ -1100,6 +1132,7 @@ class RequestLoggingMiddleware {
     });
   }
   #failed(req, path, started, request, error, scope) {
+    this.#shared(req, request);
     const status = error instanceof HttpError ? error.status : HttpStatusCode.INTERNAL_SERVER_ERROR;
     const entry = {
       ...scope,
@@ -1116,6 +1149,7 @@ class RequestLoggingMiddleware {
     }
   }
   #succeeded(req, path, requestId, started, request, response, scope) {
+    this.#shared(req, request);
     const body = this.#responseFields(response);
     if (body === undefined) {
       this.logger.info(`${req.method} ${path} ${response.status}`, {
@@ -1139,7 +1173,7 @@ class RequestLoggingMiddleware {
       return response;
     });
   }
-  #body(req) {
+  #body(req, ctx) {
     if (!this.#requestBody)
       return;
     if (req.method === "GET" || req.method === "HEAD")
@@ -1147,6 +1181,10 @@ class RequestLoggingMiddleware {
     if (!(req.headers.get("content-type") ?? "").includes("application/json")) {
       return;
     }
+    if (ctx.parsesBody) {
+      RawBody.want(req);
+      return;
+    }
     return req.clone().text().then((text) => parse(text, this.#limit));
   }
   #responseFields(response) {
@@ -1230,7 +1268,11 @@ var bodyFill = (schema) => (draft) => {
   if (parse2 === undefined) {
     throw new HttpError(HttpStatusCode.UNSUPPORTED_MEDIA_TYPE, `Unsupported content type "${media}". Declared bodies accept ` + "application/json, application/x-www-form-urlencoded, multipart/form-data or text/*.");
   }
-  return parse2(draft.req).then((value) => fillWith(draft, "body", schema, value), (error) => {
+  const read = parse2 === asJson && RawBody.wanted(draft.req) ? draft.req.text().then((text) => {
+    RawBody.record(draft.req, text);
+    return JSON.parse(text);
+  }) : parse2(draft.req);
+  return read.then((value) => fillWith(draft, "body", schema, value), (error) => {
     throw new HttpError(HttpStatusCode.BAD_REQUEST, `Malformed ${media} body`, { cause: error });
   });
 };
@@ -1309,6 +1351,7 @@ var unmatchedContext = (req, isPublic) => Object.freeze({
   handler: "(none)",
   method: req.method,
   path: new URL(req.url).pathname,
+  parsesBody: false,
   get: (key) => {
     if (key.id === UNMATCHED.id)
       return true;
@@ -2128,6 +2171,50 @@ class QueryProbe {
 // src/health/controller.ts
 import { inject } from "@dunx/core";
 
+// src/health/report-schema.ts
+var state = {
+  type: "string",
+  enum: ["up", "down", "unknown"],
+  description: "`unknown` is not `down`: a probe that timed out has told you nothing."
+};
+var HEALTH_REPORT_SCHEMA = Object.freeze({
+  $id: "HealthReport",
+  type: "object",
+  description: "What the probe found. `up` answers 200 and anything else answers 503.",
+  properties: {
+    status: state,
+    draining: {
+      type: "boolean",
+      description: "The process is shutting down, or something holds it out."
+    },
+    uptimeMs: {
+      type: "integer",
+      description: "Measured on a monotonic clock, so it never goes backwards."
+    },
+    checks: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          state,
+          critical: {
+            type: "boolean",
+            description: "A failure here sheds traffic. Memory and disk do not."
+          },
+          ms: { type: "integer", description: "How long the check took." },
+          detail: {
+            type: "string",
+            description: "A latency, a version, or a failure message."
+          }
+        },
+        required: ["name", "state", "critical", "ms"]
+      }
+    }
+  },
+  required: ["status", "draining", "uptimeMs", "checks"]
+});
+
 // src/health/registry.ts
 var bounded = async (indicator, timeoutMs) => {
   let timer;
@@ -2162,12 +2249,14 @@ class HealthOptions {
   readiness;
   timeoutMs;
   routes;
+  documented;
   drainDelayMs;
   constructor(init = {}) {
     this.liveness = init.liveness ?? [];
     this.readiness = init.readiness ?? [];
     this.timeoutMs = init.timeoutMs ?? 2000;
     this.routes = init.routes ?? true;
+    this.documented = init.documented ?? true;
     this.drainDelayMs = Math.max(0, init.drainDelayMs ?? 0);
   }
 }
@@ -2230,18 +2319,20 @@ Object.defineProperty(HealthRegistry, Symbol.for("dunx.deps"), {
 });
 
 // src/health/controller.ts
+var probeResponses = {
+  response: { 200: HEALTH_REPORT_SCHEMA, 503: HEALTH_REPORT_SCHEMA }
+};
 var answer = (report) => Response.json(report, { status: report.status === "up" ? 200 : 503 });
 var _dec = [
-  Controller("health"),
-  ApiHidden()
+  Controller("health")
 ];
 var _dec2 = [
   Public(),
-  Get("/live")
+  Get("/live", probeResponses)
 ];
 var _dec3 = [
   Public(),
-  Get("/ready")
+  Get("/ready", probeResponses)
 ];
 var _health = new WeakMap;
 var _init = __decoratorStart(undefined);
@@ -2264,6 +2355,18 @@ HealthController = __decorateElement(_init, 0, "HealthController", _dec, HealthC
 __runInitializers(_init, 1, HealthController);
 __decoratorMetadata(_init, HealthController);
 let _HealthController = HealthController;
+var _dec = [
+  ApiHidden()
+];
+var _base = HealthController;
+var _init = __decoratorStart(_base);
+
+class HiddenHealthController extends _base {
+}
+HiddenHealthController = __decorateElement(_init, 0, "HiddenHealthController", _dec, HiddenHealthController);
+__runInitializers(_init, 1, HiddenHealthController);
+__decoratorMetadata(_init, HiddenHealthController);
+let _HiddenHealthController = HiddenHealthController;
 // src/health/indicators.ts
 import { statfs } from "fs/promises";
 var ms = (started) => Math.round(performance.now() - started);
@@ -2430,6 +2533,7 @@ var wiring = (options) => [
   })
 ];
 var surface = [HealthOptions, HealthRegistry, Readiness];
+var controllerFor = (documented) => documented ? HealthController : HiddenHealthController;
 var _dec = [
   Module3({})
 ];
@@ -2440,7 +2544,7 @@ class HealthModule {
     const options = new HealthOptions(init);
     return {
       module: HealthModule,
-      ...options.routes ? { controllers: [HealthController] } : {},
+      ...options.routes ? { controllers: [controllerFor(options.documented)] } : {},
       exports: surface,
       providers: wiring([provide4(HealthOptions, { useValue: options })])
     };
@@ -2449,7 +2553,7 @@ class HealthModule {
     return {
       module: HealthModule,
       ...config.imports ? { imports: config.imports } : {},
-      ...config.routes ?? true ? { controllers: [HealthController] } : {},
+      ...config.routes ?? true ? { controllers: [controllerFor(config.documented ?? true)] } : {},
       exports: surface,
       providers: wiring([
         provide4(HealthOptions, {
@@ -2476,6 +2580,7 @@ export {
   ErrorFilter,
   Gateway,
   Get,
+  HEALTH_REPORT_SCHEMA,
   HIDDEN,
   HandlerKind,
   HealthController,
@@ -2483,6 +2588,7 @@ export {
   HealthModule,
   HealthOptions,
   HealthRegistry,
+  HiddenHealthController,
   HttpError,
   HttpFactory,
   HttpStatusCode,
@@ -2566,5 +2672,5 @@ export {
   withUpgradeRoutes
 };
 
-//# debugId=30A653C61AAD581564756E2164756E21
+//# debugId=1A8278039B82BC0664756E2164756E21
 //# sourceMappingURL=index.js.map