@bymax-one/nest-core 1.6.6 → 1.6.8

package/dist/index.cjs

@@ -18,6 +18,121 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
+// src/core.tokens.ts
+var BYMAX_CORE_OPTIONS = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:core-options");
+var BYMAX_CORRELATION_PROVIDER = /* @__PURE__ */ Symbol.for(
+  "@bymax-one/nest-core:correlation-provider"
+);
+var BYMAX_TIMING_SINK = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:timing-sink");
+var BYMAX_HEALTH_INDICATORS = /* @__PURE__ */ Symbol.for(
+  "@bymax-one/nest-core:health-indicators"
+);
+var BYMAX_HEALTH_TRANSITION_SINK = /* @__PURE__ */ Symbol.for(
+  "@bymax-one/nest-core:health-transition-sink"
+);
+var BYMAX_UNEXPECTED_ERROR_SINK = /* @__PURE__ */ Symbol.for(
+  "@bymax-one/nest-core:unexpected-error-sink"
+);
+var BYMAX_METRICS_REGISTRY = /* @__PURE__ */ Symbol.for(
+  "@bymax-one/nest-core:metrics-registry"
+);
+var BYMAX_TRACE_CONTEXT = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:trace-context");
+
+// src/envelope/error-codes.ts
+var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
+var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
+var BYMAX_UNAUTHORIZED = "BYMAX_UNAUTHORIZED";
+var BYMAX_FORBIDDEN = "BYMAX_FORBIDDEN";
+var BYMAX_NOT_FOUND = "BYMAX_NOT_FOUND";
+var BYMAX_CONFLICT = "BYMAX_CONFLICT";
+var BYMAX_PAYLOAD_TOO_LARGE = "BYMAX_PAYLOAD_TOO_LARGE";
+var BYMAX_UNSUPPORTED_MEDIA_TYPE = "BYMAX_UNSUPPORTED_MEDIA_TYPE";
+var BYMAX_UNPROCESSABLE_ENTITY = "BYMAX_UNPROCESSABLE_ENTITY";
+var BYMAX_TOO_MANY_REQUESTS = "BYMAX_TOO_MANY_REQUESTS";
+var BYMAX_CLIENT_ERROR = "BYMAX_CLIENT_ERROR";
+var BYMAX_INTERNAL_ERROR = "BYMAX_INTERNAL_ERROR";
+var BYMAX_NOT_IMPLEMENTED = "BYMAX_NOT_IMPLEMENTED";
+var BYMAX_BAD_GATEWAY = "BYMAX_BAD_GATEWAY";
+var BYMAX_SERVICE_UNAVAILABLE = "BYMAX_SERVICE_UNAVAILABLE";
+var BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
+var STATUS_CODES = /* @__PURE__ */ new Map([
+  [400, BYMAX_BAD_REQUEST],
+  [401, BYMAX_UNAUTHORIZED],
+  [403, BYMAX_FORBIDDEN],
+  [404, BYMAX_NOT_FOUND],
+  [409, BYMAX_CONFLICT],
+  [413, BYMAX_PAYLOAD_TOO_LARGE],
+  [415, BYMAX_UNSUPPORTED_MEDIA_TYPE],
+  [422, BYMAX_UNPROCESSABLE_ENTITY],
+  [429, BYMAX_TOO_MANY_REQUESTS],
+  [500, BYMAX_INTERNAL_ERROR],
+  [501, BYMAX_NOT_IMPLEMENTED],
+  [502, BYMAX_BAD_GATEWAY],
+  [503, BYMAX_SERVICE_UNAVAILABLE],
+  [504, BYMAX_GATEWAY_TIMEOUT]
+]);
+var CLIENT_ERROR_MIN = 400;
+var CLIENT_ERROR_MAX = 500;
+function codeForStatus(status) {
+  const catalogued = STATUS_CODES.get(status);
+  if (catalogued !== void 0) {
+    return catalogued;
+  }
+  if (status >= CLIENT_ERROR_MIN && status < CLIENT_ERROR_MAX) {
+    return BYMAX_CLIENT_ERROR;
+  }
+  return BYMAX_INTERNAL_ERROR;
+}
+
+// src/body-depth/body-depth.middleware.ts
+var BODY_TOO_DEEP_MESSAGE = "Request body is nested too deeply";
+function isContainer(node) {
+  if (typeof node !== "object" || node === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(node);
+  return Array.isArray(node) || proto === Object.prototype || proto === null;
+}
+function exceedsDepth(value, maxDepth) {
+  let level = [value];
+  for (let depth = 0; level.length > 0; depth += 1) {
+    const next = [];
+    for (const node of level) {
+      if (isContainer(node)) {
+        if (depth >= maxDepth) {
+          return true;
+        }
+        for (const child of Object.values(node)) {
+          next.push(child);
+        }
+      }
+    }
+    level = next;
+  }
+  return false;
+}
+exports.BymaxBodyDepthMiddleware = class BymaxBodyDepthMiddleware {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * @param req - The request, whose `body` the parser has already filled.
+   * @param _res - Unused.
+   * @param next - Continues the chain.
+   * @throws BadRequestException When the body is nested too deeply.
+   */
+  use(req, _res, next) {
+    if (exceedsDepth(req.body, this.options.bodyDepth.maxDepth)) {
+      throw new common.BadRequestException({ code: BYMAX_BAD_REQUEST, message: BODY_TOO_DEEP_MESSAGE });
+    }
+    next();
+  }
+};
+exports.BymaxBodyDepthMiddleware = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(BYMAX_CORE_OPTIONS))
+], exports.BymaxBodyDepthMiddleware);
+
 // src/route-defaults.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
@@ -40,6 +155,8 @@ function runtimeEnvironmentName(declared) {
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
+var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+var DEFAULT_READINESS_CACHE_MS = 1e3;
 var DEFAULT_OPENAPI_PATH = "docs";
 var DEFAULT_OPENAPI_JSON_PATH = "docs-json";
 var DEFAULT_OPENAPI_TITLE = "API";
@@ -59,17 +176,48 @@ function resolveEnvelope(raw) {
     exposeInternals: raw?.exposeInternals ?? false
   };
 }
+function positiveSafeInteger(name, value, max) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive safe integer, received ${String(value)}`);
+  }
+  if (max !== void 0 && value > max) {
+    throw new Error(`${name} must be a positive integer of at most ${max}, received ${value}`);
+  }
+  return value;
+}
 function resolveTiming(raw) {
   const enabled = raw?.enabled ?? true;
   const threshold = raw?.slowRequestThresholdMs;
-  return threshold === void 0 ? { enabled } : { enabled, slowRequestThresholdMs: threshold };
+  return threshold === void 0 ? { enabled } : {
+    enabled,
+    slowRequestThresholdMs: positiveSafeInteger("timing.slowRequestThresholdMs", threshold)
+  };
+}
+var DEFAULT_MAX_BODY_DEPTH = 32;
+function resolveBodyDepth(raw) {
+  const maxDepth = positiveSafeInteger(
+    "bodyDepth.maxDepth",
+    raw?.maxDepth ?? DEFAULT_MAX_BODY_DEPTH
+  );
+  return { enabled: raw?.enabled ?? false, maxDepth };
 }
 function resolveHealth(raw) {
+  const readinessCacheMs = raw?.readinessCacheMs ?? DEFAULT_READINESS_CACHE_MS;
+  if (!Number.isSafeInteger(readinessCacheMs) || readinessCacheMs < 0) {
+    throw new Error(
+      `health.readinessCacheMs must be a non-negative safe integer, received ${String(readinessCacheMs)}`
+    );
+  }
   return {
+    readinessCacheMs,
     enabled: raw?.enabled ?? true,
     path: raw?.path ?? DEFAULT_HEALTH_PATH,
     exposeIndicatorErrors: raw?.exposeIndicatorErrors ?? false,
-    indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+    indicatorTimeoutMs: positiveSafeInteger(
+      "health.indicatorTimeoutMs",
+      raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+      MAX_TIMER_DELAY_MS
+    ),
     autoDiscover: raw?.autoDiscover ?? false
   };
 }
@@ -136,6 +284,7 @@ function normalizeCoreOptions(raw) {
   return deepFreeze({
     envelope: resolveEnvelope(raw?.envelope),
     timing: resolveTiming(raw?.timing),
+    bodyDepth: resolveBodyDepth(raw?.bodyDepth),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
     openapi: resolveOpenApi(raw?.openapi, raw?.environment),
@@ -148,26 +297,6 @@ function normalizeCoreOptions(raw) {
 }
 normalizeCoreOptions();
 
-// src/core.tokens.ts
-var BYMAX_CORE_OPTIONS = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:core-options");
-var BYMAX_CORRELATION_PROVIDER = /* @__PURE__ */ Symbol.for(
-  "@bymax-one/nest-core:correlation-provider"
-);
-var BYMAX_TIMING_SINK = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:timing-sink");
-var BYMAX_HEALTH_INDICATORS = /* @__PURE__ */ Symbol.for(
-  "@bymax-one/nest-core:health-indicators"
-);
-var BYMAX_HEALTH_TRANSITION_SINK = /* @__PURE__ */ Symbol.for(
-  "@bymax-one/nest-core:health-transition-sink"
-);
-var BYMAX_UNEXPECTED_ERROR_SINK = /* @__PURE__ */ Symbol.for(
-  "@bymax-one/nest-core:unexpected-error-sink"
-);
-var BYMAX_METRICS_REGISTRY = /* @__PURE__ */ Symbol.for(
-  "@bymax-one/nest-core:metrics-registry"
-);
-var BYMAX_TRACE_CONTEXT = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:trace-context");
-
 // src/optional-peer.ts
 function isMissingModuleError(cause) {
   const code = cause.code;
@@ -275,52 +404,6 @@ function containRejection(returned, onFailure) {
   }
 }
 
-// src/envelope/error-codes.ts
-var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
-var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
-var BYMAX_UNAUTHORIZED = "BYMAX_UNAUTHORIZED";
-var BYMAX_FORBIDDEN = "BYMAX_FORBIDDEN";
-var BYMAX_NOT_FOUND = "BYMAX_NOT_FOUND";
-var BYMAX_CONFLICT = "BYMAX_CONFLICT";
-var BYMAX_PAYLOAD_TOO_LARGE = "BYMAX_PAYLOAD_TOO_LARGE";
-var BYMAX_UNSUPPORTED_MEDIA_TYPE = "BYMAX_UNSUPPORTED_MEDIA_TYPE";
-var BYMAX_UNPROCESSABLE_ENTITY = "BYMAX_UNPROCESSABLE_ENTITY";
-var BYMAX_TOO_MANY_REQUESTS = "BYMAX_TOO_MANY_REQUESTS";
-var BYMAX_CLIENT_ERROR = "BYMAX_CLIENT_ERROR";
-var BYMAX_INTERNAL_ERROR = "BYMAX_INTERNAL_ERROR";
-var BYMAX_NOT_IMPLEMENTED = "BYMAX_NOT_IMPLEMENTED";
-var BYMAX_BAD_GATEWAY = "BYMAX_BAD_GATEWAY";
-var BYMAX_SERVICE_UNAVAILABLE = "BYMAX_SERVICE_UNAVAILABLE";
-var BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
-var STATUS_CODES = /* @__PURE__ */ new Map([
-  [400, BYMAX_BAD_REQUEST],
-  [401, BYMAX_UNAUTHORIZED],
-  [403, BYMAX_FORBIDDEN],
-  [404, BYMAX_NOT_FOUND],
-  [409, BYMAX_CONFLICT],
-  [413, BYMAX_PAYLOAD_TOO_LARGE],
-  [415, BYMAX_UNSUPPORTED_MEDIA_TYPE],
-  [422, BYMAX_UNPROCESSABLE_ENTITY],
-  [429, BYMAX_TOO_MANY_REQUESTS],
-  [500, BYMAX_INTERNAL_ERROR],
-  [501, BYMAX_NOT_IMPLEMENTED],
-  [502, BYMAX_BAD_GATEWAY],
-  [503, BYMAX_SERVICE_UNAVAILABLE],
-  [504, BYMAX_GATEWAY_TIMEOUT]
-]);
-var CLIENT_ERROR_MIN = 400;
-var CLIENT_ERROR_MAX = 500;
-function codeForStatus(status) {
-  const catalogued = STATUS_CODES.get(status);
-  if (catalogued !== void 0) {
-    return catalogued;
-  }
-  if (status >= CLIENT_ERROR_MIN && status < CLIENT_ERROR_MAX) {
-    return BYMAX_CLIENT_ERROR;
-  }
-  return BYMAX_INTERNAL_ERROR;
-}
-
 // src/envelope/error-envelope.ts
 function buildErrorEnvelope(input) {
   const base = {
@@ -793,10 +876,12 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs, exposeErrors) {
+function startTimeout(indicator, timeoutMs) {
+  const controller = new AbortController();
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
+      controller.abort();
       resolve({
         entry: { name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } },
         isUp: false,
@@ -804,8 +889,12 @@ async function runIndicator(indicator, timeoutMs, exposeErrors) {
       });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => {
-    const entry = { ...result, name: indicator.name };
+  return { signal: controller.signal, timedOut, clear: () => clearTimeout(timer) };
+}
+async function runIndicator(indicator, timeoutMs, exposeErrors) {
+  const { signal, timedOut, clear } = startTimeout(indicator, timeoutMs);
+  const checked = Promise.resolve().then(() => indicator.check(signal)).then((result) => {
+    const entry = exposeErrors ? { ...result, name: indicator.name } : { name: indicator.name, status: result.status };
     return result.status === "up" ? { entry, isUp: true } : { entry, isUp: false, cause: { kind: "reported-down" } };
   }).catch((reason) => {
     const message = summarizeRejection(reason);
@@ -818,7 +907,7 @@ async function runIndicator(indicator, timeoutMs, exposeErrors) {
   try {
     return await Promise.race([checked, timedOut]);
   } finally {
-    clearTimeout(timer);
+    clear();
   }
 }
 function describeCause(cause) {
@@ -878,6 +967,8 @@ var HealthService = class {
      * Comparing states alone would then let the stale observation win.
      */
     this.probeSequence = 0;
+    /** Set once shutdown begins, after which readiness answers not ready without running anything. */
+    this.draining = false;
   }
   /**
    * Report one check's current state, emitting only when it differs from the
@@ -1050,6 +1141,14 @@ var HealthService = class {
     );
     return this.effectiveIndicators;
   }
+  /**
+   * Stop reporting ready the moment shutdown begins, so a load balancer stops routing here while
+   * the process drains. Nothing cached or in progress is consulted again: every later probe is answered
+   * before either is read.
+   */
+  beforeApplicationShutdown() {
+    this.draining = true;
+  }
   /**
    * Liveness check: the process is up and able to respond. Runs no
    * indicators, so it never depends on the health of anything else.
@@ -1064,9 +1163,33 @@ var HealthService = class {
    * aggregate the results. `status` is `'ok'` only when every indicator
    * reports `up`; an empty indicator list is vacuously `'ok'`.
    *
+   * Probes share the work: one that arrives while a run is in progress awaits it, and for
+   * `health.readinessCacheMs` after it ends the answer is returned without running anything.
+   * The endpoint is usually unauthenticated, so probe volume must not set dependency volume.
+   * Once shutdown has begun the answer is always not ready. The returned object is shared between
+   * callers and must not be mutated.
+   *
+   * @returns The aggregated health response.
+   */
+  checkReadiness() {
+    if (this.draining) {
+      return Promise.resolve({ status: "error", checks: [{ name: "shutdown", status: "down" }] });
+    }
+    const cached = this.cached;
+    if (cached !== void 0 && performance.now() - cached.at < this.options.health.readinessCacheMs) {
+      return Promise.resolve(cached.response);
+    }
+    this.inflight ??= this.runReadiness().finally(() => {
+      this.inflight = void 0;
+    });
+    return this.inflight;
+  }
+  /**
+   * Run every indicator once and record the answer.
+   *
    * @returns The aggregated health response.
    */
-  async checkReadiness() {
+  async runReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
     const exposeErrors = this.options.health.exposeIndicatorErrors;
     const seq = ++this.probeSequence;
@@ -1078,7 +1201,9 @@ var HealthService = class {
     }
     const checks = outcomes.map((outcome) => outcome.entry);
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
-    return { status, checks };
+    const response = { status, checks };
+    this.cached = { at: performance.now(), response };
+    return response;
   }
 };
 HealthService = __decorateClass([
@@ -1697,12 +1822,14 @@ exports.BymaxCoreModule = class BymaxCoreModule extends BymaxCoreModuleBase {
    * @param consumer - Nest's middleware consumer.
    */
   configure(consumer) {
-    if (!this.resolved.timing.enabled) {
-      return;
-    }
     const adapter = this.adapterHost?.httpAdapter;
-    const onFastify = bridgeFastifyRouteMetadata(adapter);
-    consumer.apply(exports.BymaxTimingMiddleware).forRoutes(onFastify ? "{*splat}" : "/");
+    if (this.resolved.timing.enabled) {
+      const onFastify = bridgeFastifyRouteMetadata(adapter);
+      consumer.apply(exports.BymaxTimingMiddleware).forRoutes(onFastify ? "{*splat}" : "/");
+    }
+    if (this.resolved.bodyDepth.enabled && adapter?.getType?.() !== "fastify") {
+      consumer.apply(exports.BymaxBodyDepthMiddleware).forRoutes("/");
+    }
   }
   /**
    * Register the module synchronously. Options are known now, so disabled

package/dist/index.d.cts

@@ -19,17 +19,45 @@ interface EnvelopeOptions {
 interface TimingOptions {
     /** Register the request-timing middleware (`BymaxTimingMiddleware`). Default: `true`. */
     enabled?: boolean;
-    /** Samples above this threshold are flagged as slow. No default (unset). */
+    /** Samples above this threshold are flagged as slow. Positive integer. No default (unset). */
     slowRequestThresholdMs?: number;
 }
+/** Request-body nesting limit, applied before the application's own validation runs. */
+interface BodyDepthOptions {
+    /**
+     * Refuse a parsed request body nested deeper than {@link BodyDepthOptions.maxDepth} with a
+     * `400` through the error envelope. Default: `false`.
+     *
+     * Off by default because turning it on rejects bodies that are accepted today. Enable it:
+     * a body of a few thousand nested arrays is only a few kilobytes, and a recursive validator
+     * or transformer overflows the stack on it, so the request is answered `500`, with no
+     * credential needed. The check runs before routing, on the body the parser already produced, so it covers the Express adapter and a body parsed by
+     * Nest's own parsers; it does not cover Fastify.
+     */
+    enabled?: boolean;
+    /**
+     * The deepest nesting a body may have: `[[1]]` is depth 2, a flat object or array is depth 1,
+     * and a scalar is depth 0. Must be a positive safe integer. Default: `32`.
+     */
+    maxDepth?: number;
+}
 /** Liveness and readiness endpoint configuration. */
 interface HealthOptions {
     /** Register the health controller. Default: `true`. */
     enabled?: boolean;
     /** Route prefix for the health endpoints. Default: `'health'`. */
     path?: string;
-    /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
+    /** Per-indicator timeout before a check is reported as down. Positive integer up to 2147483647. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * How long a finished readiness answer is reused, in milliseconds. `0` turns the cache off.
+     * Default: `1000`.
+     *
+     * Readiness is usually reachable without credentials, and every probe would otherwise reach
+     * every dependency. Probes that arrive while one is running always share it, whatever this is set to;
+     * this is only how long its answer outlives it.
+     */
+    readinessCacheMs?: number;
     /**
      * Aggregate every provider marked with `@BymaxHealthIndicator()`, anywhere in
      * the application, in addition to those registered under
@@ -43,15 +71,16 @@ interface HealthOptions {
      */
     autoDiscover?: boolean;
     /**
-     * Include the failing indicator's message in the readiness response under
-     * `details.error`. Never enable in production. Default: `false`.
+     * Serve what an indicator returned in `details`, and the failing indicator's
+     * message under `details.error`, in the readiness response. Never enable in
+     * production. Default: `false`.
      *
      * Readiness is typically unauthenticated and reachable by whatever probes it,
      * and an indicator usually does not author its own failure message — it lets a
      * driver's error propagate, and driver errors carry hosts, ports and sometimes
-     * credentials. With this off, the response names which indicator is down and
-     * nothing else; the message goes to the logger, where access is already
-     * controlled.
+     * credentials. With this off, the response carries each indicator's name and
+     * status and nothing else, except the timeout the aggregator itself reports;
+     * the message goes to the logger, where access is already controlled.
      */
     exposeIndicatorErrors?: boolean;
 }
@@ -267,6 +296,8 @@ interface BymaxCoreModuleOptions {
     envelope?: EnvelopeOptions;
     /** Request-timing middleware. Default: enabled. */
     timing?: TimingOptions;
+    /** Request-body nesting limit. Default: disabled. */
+    bodyDepth?: BodyDepthOptions;
     /** Liveness and readiness endpoints. Default: enabled. */
     health?: HealthOptions;
     /** Prometheus metrics endpoint. Default: disabled. */
@@ -308,11 +339,17 @@ interface ResolvedTimingOptions {
     enabled: boolean;
     slowRequestThresholdMs?: number;
 }
+/** Fully-resolved body-depth options. */
+interface ResolvedBodyDepthOptions {
+    enabled: boolean;
+    maxDepth: number;
+}
 /** Fully-resolved health options. */
 interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    readinessCacheMs: number;
     exposeIndicatorErrors: boolean;
     autoDiscover: boolean;
 }
@@ -365,6 +402,7 @@ interface ResolvedOpenApiOptions {
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
     timing: ResolvedTimingOptions;
+    bodyDepth: ResolvedBodyDepthOptions;
     health: ResolvedHealthOptions;
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
@@ -1115,6 +1153,21 @@ declare class TimingInterceptor implements NestInterceptor {
     private recordSample;
 }
 
+/** Refuses a body nested deeper than `bodyDepth.maxDepth` with a coded `400`. */
+declare class BymaxBodyDepthMiddleware implements NestMiddleware {
+    private readonly options;
+    constructor(options: ResolvedCoreOptions);
+    /**
+     * @param req - The request, whose `body` the parser has already filled.
+     * @param _res - Unused.
+     * @param next - Continues the chain.
+     * @throws BadRequestException When the body is nested too deeply.
+     */
+    use(req: {
+        body?: unknown;
+    }, _res: unknown, next: () => void): void;
+}
+
 /**
  * @fileoverview Neutral request-info accessor for request timing. Reads the
  * HTTP method and the route template off a request without assuming Express or
@@ -1296,5 +1349,5 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
-export type { BuildErrorEnvelopeInput, BymaxCoreModuleOptions, EnvelopeOptions, ErrorDetails, ErrorEnvelope, FilterErrorContext, HealthOptions, ICorrelationIdProvider, ITimingSink, ITraceContextProvider, IUnexpectedErrorSink, MetricsOptions, OpenApiHttpMethod, OpenApiOperationIdFactory, OpenApiOperationKey, OpenApiOptions, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiServerDescriptor, OperationSecurityMap, RequestTimingSample, ResolvedCoreOptions, TelemetryOptions, TimingOptions, TraceContext, UnexpectedErrorReport };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxBodyDepthMiddleware, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+export type { BodyDepthOptions, BuildErrorEnvelopeInput, BymaxCoreModuleOptions, EnvelopeOptions, ErrorDetails, ErrorEnvelope, FilterErrorContext, HealthOptions, ICorrelationIdProvider, ITimingSink, ITraceContextProvider, IUnexpectedErrorSink, MetricsOptions, OpenApiHttpMethod, OpenApiOperationIdFactory, OpenApiOperationKey, OpenApiOptions, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiServerDescriptor, OperationSecurityMap, RequestTimingSample, ResolvedCoreOptions, TelemetryOptions, TimingOptions, TraceContext, UnexpectedErrorReport };

package/dist/index.d.ts

@@ -19,17 +19,45 @@ interface EnvelopeOptions {
 interface TimingOptions {
     /** Register the request-timing middleware (`BymaxTimingMiddleware`). Default: `true`. */
     enabled?: boolean;
-    /** Samples above this threshold are flagged as slow. No default (unset). */
+    /** Samples above this threshold are flagged as slow. Positive integer. No default (unset). */
     slowRequestThresholdMs?: number;
 }
+/** Request-body nesting limit, applied before the application's own validation runs. */
+interface BodyDepthOptions {
+    /**
+     * Refuse a parsed request body nested deeper than {@link BodyDepthOptions.maxDepth} with a
+     * `400` through the error envelope. Default: `false`.
+     *
+     * Off by default because turning it on rejects bodies that are accepted today. Enable it:
+     * a body of a few thousand nested arrays is only a few kilobytes, and a recursive validator
+     * or transformer overflows the stack on it, so the request is answered `500`, with no
+     * credential needed. The check runs before routing, on the body the parser already produced, so it covers the Express adapter and a body parsed by
+     * Nest's own parsers; it does not cover Fastify.
+     */
+    enabled?: boolean;
+    /**
+     * The deepest nesting a body may have: `[[1]]` is depth 2, a flat object or array is depth 1,
+     * and a scalar is depth 0. Must be a positive safe integer. Default: `32`.
+     */
+    maxDepth?: number;
+}
 /** Liveness and readiness endpoint configuration. */
 interface HealthOptions {
     /** Register the health controller. Default: `true`. */
     enabled?: boolean;
     /** Route prefix for the health endpoints. Default: `'health'`. */
     path?: string;
-    /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
+    /** Per-indicator timeout before a check is reported as down. Positive integer up to 2147483647. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * How long a finished readiness answer is reused, in milliseconds. `0` turns the cache off.
+     * Default: `1000`.
+     *
+     * Readiness is usually reachable without credentials, and every probe would otherwise reach
+     * every dependency. Probes that arrive while one is running always share it, whatever this is set to;
+     * this is only how long its answer outlives it.
+     */
+    readinessCacheMs?: number;
     /**
      * Aggregate every provider marked with `@BymaxHealthIndicator()`, anywhere in
      * the application, in addition to those registered under
@@ -43,15 +71,16 @@ interface HealthOptions {
      */
     autoDiscover?: boolean;
     /**
-     * Include the failing indicator's message in the readiness response under
-     * `details.error`. Never enable in production. Default: `false`.
+     * Serve what an indicator returned in `details`, and the failing indicator's
+     * message under `details.error`, in the readiness response. Never enable in
+     * production. Default: `false`.
      *
      * Readiness is typically unauthenticated and reachable by whatever probes it,
      * and an indicator usually does not author its own failure message — it lets a
      * driver's error propagate, and driver errors carry hosts, ports and sometimes
-     * credentials. With this off, the response names which indicator is down and
-     * nothing else; the message goes to the logger, where access is already
-     * controlled.
+     * credentials. With this off, the response carries each indicator's name and
+     * status and nothing else, except the timeout the aggregator itself reports;
+     * the message goes to the logger, where access is already controlled.
      */
     exposeIndicatorErrors?: boolean;
 }
@@ -267,6 +296,8 @@ interface BymaxCoreModuleOptions {
     envelope?: EnvelopeOptions;
     /** Request-timing middleware. Default: enabled. */
     timing?: TimingOptions;
+    /** Request-body nesting limit. Default: disabled. */
+    bodyDepth?: BodyDepthOptions;
     /** Liveness and readiness endpoints. Default: enabled. */
     health?: HealthOptions;
     /** Prometheus metrics endpoint. Default: disabled. */
@@ -308,11 +339,17 @@ interface ResolvedTimingOptions {
     enabled: boolean;
     slowRequestThresholdMs?: number;
 }
+/** Fully-resolved body-depth options. */
+interface ResolvedBodyDepthOptions {
+    enabled: boolean;
+    maxDepth: number;
+}
 /** Fully-resolved health options. */
 interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    readinessCacheMs: number;
     exposeIndicatorErrors: boolean;
     autoDiscover: boolean;
 }
@@ -365,6 +402,7 @@ interface ResolvedOpenApiOptions {
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
     timing: ResolvedTimingOptions;
+    bodyDepth: ResolvedBodyDepthOptions;
     health: ResolvedHealthOptions;
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
@@ -1115,6 +1153,21 @@ declare class TimingInterceptor implements NestInterceptor {
     private recordSample;
 }
 
+/** Refuses a body nested deeper than `bodyDepth.maxDepth` with a coded `400`. */
+declare class BymaxBodyDepthMiddleware implements NestMiddleware {
+    private readonly options;
+    constructor(options: ResolvedCoreOptions);
+    /**
+     * @param req - The request, whose `body` the parser has already filled.
+     * @param _res - Unused.
+     * @param next - Continues the chain.
+     * @throws BadRequestException When the body is nested too deeply.
+     */
+    use(req: {
+        body?: unknown;
+    }, _res: unknown, next: () => void): void;
+}
+
 /**
  * @fileoverview Neutral request-info accessor for request timing. Reads the
  * HTTP method and the route template off a request without assuming Express or
@@ -1296,5 +1349,5 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
-export type { BuildErrorEnvelopeInput, BymaxCoreModuleOptions, EnvelopeOptions, ErrorDetails, ErrorEnvelope, FilterErrorContext, HealthOptions, ICorrelationIdProvider, ITimingSink, ITraceContextProvider, IUnexpectedErrorSink, MetricsOptions, OpenApiHttpMethod, OpenApiOperationIdFactory, OpenApiOperationKey, OpenApiOptions, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiServerDescriptor, OperationSecurityMap, RequestTimingSample, ResolvedCoreOptions, TelemetryOptions, TimingOptions, TraceContext, UnexpectedErrorReport };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxBodyDepthMiddleware, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+export type { BodyDepthOptions, BuildErrorEnvelopeInput, BymaxCoreModuleOptions, EnvelopeOptions, ErrorDetails, ErrorEnvelope, FilterErrorContext, HealthOptions, ICorrelationIdProvider, ITimingSink, ITraceContextProvider, IUnexpectedErrorSink, MetricsOptions, OpenApiHttpMethod, OpenApiOperationIdFactory, OpenApiOperationKey, OpenApiOptions, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiServerDescriptor, OperationSecurityMap, RequestTimingSample, ResolvedCoreOptions, TelemetryOptions, TimingOptions, TraceContext, UnexpectedErrorReport };