@bymax-one/nest-core 1.5.2 → 1.6.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import * as _nestjs_common from '@nestjs/common';
 import { NestModule, MiddlewareConsumer, DynamicModule, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, NestMiddleware } from '@nestjs/common';
 import { HttpAdapterHost } from '@nestjs/core';
+export { H as HealthTransition, a as HealthTransitionCause, I as IHealthTransitionSink } from './health.transition-B_IgXJTz.cjs';
 import { Observable } from 'rxjs';
 
 /** Error-envelope exception-filter configuration. */
@@ -430,9 +431,12 @@ declare class BymaxCoreModule extends BymaxCoreModuleBase implements NestModule
      * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
      * prescribes for "all routes" — stops matching the prefixed root once an
      * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-     * fixed by nest#14522, whose regression test covers Fastify; on
-     * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-     * reaches no middleware while resolving to `200`.
+     * fixed by nest#14522, whose regression test covers Fastify; on the Express
+     * adapter the prefixed root still reaches no middleware while resolving to
+     * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+     * 11.2.1 — a minor release is exactly where this would plausibly have been
+     * fixed, so the version this was last confirmed against is part of the
+     * claim rather than a footnote to it.
      *
      * On Fastify the same `'/'` is an exact match rather than a mount — one of
      * three requests reached the middleware — so the wildcard is the only form
@@ -553,6 +557,13 @@ declare const BYMAX_TIMING_SINK: unique symbol;
  * Defaults to an empty array.
  */
 declare const BYMAX_HEALTH_INDICATORS: unique symbol;
+/**
+ * Provide the `IHealthTransitionSink` that receives one event per change of
+ * readiness state, per check. Nothing is bound by default; with no sink the
+ * aggregator writes its own transition lines to Nest's logger, and binding one
+ * stands that line down in favour of the sink.
+ */
+declare const BYMAX_HEALTH_TRANSITION_SINK: unique symbol;
 /**
  * Provide the `prom-client` `Registry` backing the metrics endpoint. Bound
  * lazily and only when the metrics feature is enabled.
@@ -894,9 +905,16 @@ interface RequestTimingSample {
     spanId?: string;
 }
 /**
- * Receive request-timing samples. Implementations must never throw: a sink
- * failure is caught and silenced by the recorder so timing never breaks a
- * request.
+ * Receive request-timing samples. Implementations should not fail, and a failure
+ * is absorbed by the recorder either way so timing never breaks a request.
+ *
+ * Both ways an implementation can fail are absorbed: a synchronous throw, and a
+ * rejection from an `async record()` — which compiles despite the `void` return
+ * type, because TypeScript accepts any return value in a void-returning
+ * position, and is the natural shape when the backend behind the sink is async.
+ * The failure is swallowed rather than logged, unlike `IHealthTransitionSink`:
+ * this runs on every request, so a sink failing systematically would turn one
+ * broken backend into a second flood beside it.
  */
 interface ITimingSink {
     /**
@@ -969,9 +987,8 @@ declare class TimingInterceptor implements NestInterceptor {
      */
     private readErrorStatus;
     /**
-     * Build the sample and deliver it to the sink inside a try/catch that
-     * silences any failure: a throwing sink must never affect the request it is
-     * observing.
+     * Build the sample and deliver it. `deliverSample` absorbs whatever the sink
+     * does with it: a broken sink must never affect the request it observes.
      *
      * @param method - HTTP method of the request.
      * @param route - Route template of the request.
@@ -1097,7 +1114,8 @@ declare class BymaxTimingMiddleware implements NestMiddleware {
      */
     use(request: RequestShape, response: ResponseShape, next: () => void): void;
     /**
-     * Build the sample and hand it to the sink, guarding both steps.
+     * Build the sample and deliver it. `deliverSample` absorbs whatever the sink
+     * does with it, so a broken sink never reaches the request it observes.
      *
      * @param request - The framework request object.
      * @param response - The framework response object.
@@ -1161,4 +1179,4 @@ 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_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_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+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_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as _nestjs_common from '@nestjs/common';
 import { NestModule, MiddlewareConsumer, DynamicModule, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, NestMiddleware } from '@nestjs/common';
 import { HttpAdapterHost } from '@nestjs/core';
+export { H as HealthTransition, a as HealthTransitionCause, I as IHealthTransitionSink } from './health.transition-B_IgXJTz.js';
 import { Observable } from 'rxjs';
 
 /** Error-envelope exception-filter configuration. */
@@ -430,9 +431,12 @@ declare class BymaxCoreModule extends BymaxCoreModuleBase implements NestModule
      * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
      * prescribes for "all routes" — stops matching the prefixed root once an
      * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-     * fixed by nest#14522, whose regression test covers Fastify; on
-     * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-     * reaches no middleware while resolving to `200`.
+     * fixed by nest#14522, whose regression test covers Fastify; on the Express
+     * adapter the prefixed root still reaches no middleware while resolving to
+     * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+     * 11.2.1 — a minor release is exactly where this would plausibly have been
+     * fixed, so the version this was last confirmed against is part of the
+     * claim rather than a footnote to it.
      *
      * On Fastify the same `'/'` is an exact match rather than a mount — one of
      * three requests reached the middleware — so the wildcard is the only form
@@ -553,6 +557,13 @@ declare const BYMAX_TIMING_SINK: unique symbol;
  * Defaults to an empty array.
  */
 declare const BYMAX_HEALTH_INDICATORS: unique symbol;
+/**
+ * Provide the `IHealthTransitionSink` that receives one event per change of
+ * readiness state, per check. Nothing is bound by default; with no sink the
+ * aggregator writes its own transition lines to Nest's logger, and binding one
+ * stands that line down in favour of the sink.
+ */
+declare const BYMAX_HEALTH_TRANSITION_SINK: unique symbol;
 /**
  * Provide the `prom-client` `Registry` backing the metrics endpoint. Bound
  * lazily and only when the metrics feature is enabled.
@@ -894,9 +905,16 @@ interface RequestTimingSample {
     spanId?: string;
 }
 /**
- * Receive request-timing samples. Implementations must never throw: a sink
- * failure is caught and silenced by the recorder so timing never breaks a
- * request.
+ * Receive request-timing samples. Implementations should not fail, and a failure
+ * is absorbed by the recorder either way so timing never breaks a request.
+ *
+ * Both ways an implementation can fail are absorbed: a synchronous throw, and a
+ * rejection from an `async record()` — which compiles despite the `void` return
+ * type, because TypeScript accepts any return value in a void-returning
+ * position, and is the natural shape when the backend behind the sink is async.
+ * The failure is swallowed rather than logged, unlike `IHealthTransitionSink`:
+ * this runs on every request, so a sink failing systematically would turn one
+ * broken backend into a second flood beside it.
  */
 interface ITimingSink {
     /**
@@ -969,9 +987,8 @@ declare class TimingInterceptor implements NestInterceptor {
      */
     private readErrorStatus;
     /**
-     * Build the sample and deliver it to the sink inside a try/catch that
-     * silences any failure: a throwing sink must never affect the request it is
-     * observing.
+     * Build the sample and deliver it. `deliverSample` absorbs whatever the sink
+     * does with it: a broken sink must never affect the request it observes.
      *
      * @param method - HTTP method of the request.
      * @param route - Route template of the request.
@@ -1097,7 +1114,8 @@ declare class BymaxTimingMiddleware implements NestMiddleware {
      */
     use(request: RequestShape, response: ResponseShape, next: () => void): void;
     /**
-     * Build the sample and hand it to the sink, guarding both steps.
+     * Build the sample and deliver it. `deliverSample` absorbs whatever the sink
+     * does with it, so a broken sink never reaches the request it observes.
      *
      * @param request - The framework request object.
      * @param response - The framework response object.
@@ -1161,4 +1179,4 @@ 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_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_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+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_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };

package/dist/index.mjs

@@ -155,6 +155,9 @@ var BYMAX_TIMING_SINK = /* @__PURE__ */ Symbol.for("@bymax-one/nest-core:timing-
 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_METRICS_REGISTRY = /* @__PURE__ */ Symbol.for(
   "@bymax-one/nest-core:metrics-registry"
 );
@@ -634,6 +637,13 @@ function selectAsyncExceptionFilter(options, correlation, adapterHost) {
   return options.envelope.enabled ? new BymaxExceptionFilter(options, correlation, adapterHost) : new PassThroughExceptionFilter(adapterHost);
 }
 
+// src/contain-rejection.ts
+function containRejection(returned, onFailure) {
+  if (typeof returned?.then === "function") {
+    Promise.resolve(returned).catch(onFailure);
+  }
+}
+
 // src/discovery.ts
 function labelFor(className, token) {
   return className === "" ? String(token) : className;
@@ -685,7 +695,7 @@ var TRUNCATION_ELLIPSIS = "...";
 function summarizeRejection(reason) {
   let message;
   try {
-    message = reason instanceof Error ? reason.message : String(reason);
+    message = String(reason instanceof Error ? reason.message : reason);
   } catch {
     message = "Unknown error";
   }
@@ -694,17 +704,27 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs, exposeErrors, logger) {
+async function runIndicator(indicator, timeoutMs, exposeErrors) {
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
-      resolve({ name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } });
+      resolve({
+        entry: { name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } },
+        isUp: false,
+        cause: { kind: "timed-out", timeoutMs }
+      });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => {
+  const checked = Promise.resolve().then(() => indicator.check()).then((result) => {
+    const entry = { ...result, name: indicator.name };
+    return result.status === "up" ? { entry, isUp: true } : { entry, isUp: false, cause: { kind: "reported-down" } };
+  }).catch((reason) => {
     const message = summarizeRejection(reason);
-    logger.warn(`Health indicator "${indicator.name}" reported down: ${message}`);
-    return exposeErrors ? { name: indicator.name, status: "down", details: { error: message } } : { name: indicator.name, status: "down" };
+    return {
+      entry: exposeErrors ? { name: indicator.name, status: "down", details: { error: message } } : { name: indicator.name, status: "down" },
+      isUp: false,
+      cause: { kind: "rejected", message }
+    };
   });
   try {
     return await Promise.race([checked, timedOut]);
@@ -712,6 +732,16 @@ async function runIndicator(indicator, timeoutMs, exposeErrors, logger) {
     clearTimeout(timer);
   }
 }
+function describeCause(cause) {
+  switch (cause.kind) {
+    case "rejected":
+      return `the indicator rejected: ${cause.message}`;
+    case "timed-out":
+      return `the indicator did not answer within ${cause.timeoutMs}ms`;
+    case "reported-down":
+      return "the indicator reported it down";
+  }
+}
 var HealthService = class {
   /**
    * @param indicators - Every explicitly registered indicator; empty when none
@@ -726,18 +756,169 @@ var HealthService = class {
    *   without it when the feature is off.
    * @param reflector - Nest's metadata reader, used to match the indicator
    *   marker. Optional for the same reason.
+   * @param transitionSink - Receives one event per change of readiness state.
+   *   `@Optional()` and bound to nothing by default, for the same reason as the
+   *   indicator array: a local default here would shadow a consumer's override.
    */
-  constructor(indicators = [], options, discovery, reflector) {
+  constructor(indicators = [], options, discovery, reflector, transitionSink) {
     this.indicators = indicators;
     this.options = options;
     this.discovery = discovery;
     this.reflector = reflector;
+    this.transitionSink = transitionSink;
     /**
      * Nest's own logger, scoped to this class. The failure reason of a `down`
      * indicator is written here rather than into the HTTP response, so the
      * diagnostic survives without being served to whoever can reach the probe.
      */
     this.logger = new Logger(HealthService.name);
+    /**
+     * The last state observed per check name, absent until the first observation,
+     * tagged with the probe that observed it. Keyed by name, so one map serves
+     * every check and one dependency can neither trigger nor suppress another's
+     * line. This is the state that makes the difference between a line per change
+     * and a line per probe.
+     */
+    this.lastState = /* @__PURE__ */ new Map();
+    /**
+     * Counts readiness probes, so an outcome can be ordered against what is
+     * already recorded. Readiness is not called one at a time: an orchestrator's
+     * probe and a load balancer's health check reach this concurrently, and this
+     * feature's own subject — a dependency that hangs until `indicatorTimeoutMs`
+     * elapses — is exactly what makes an earlier probe finish after a later one.
+     * Comparing states alone would then let the stale observation win.
+     */
+    this.probeSequence = 0;
+  }
+  /**
+   * Report one check's current state, emitting only when it differs from the
+   * last state observed for that name.
+   *
+   * The asymmetry on a first observation is deliberate. A first observation that
+   * is FAILING is a transition: a process that boots against a dependency
+   * already down would otherwise look healthy in the log forever. A first
+   * observation that is HEALTHY is not: that is the expected state, and
+   * announcing it would write one line per dependency on every boot — the noise
+   * the probe-path exclusion exists to keep out.
+   *
+   * A cause is recorded at the transition, so a dependency that stays down while
+   * its failure mode changes underneath keeps the first one. That is the cost of
+   * one line per outage instead of one per probe.
+   *
+   * @param outcome - The indicator's resolved outcome for this probe.
+   * @param seq - The probe that produced it, from {@link probeSequence}.
+   */
+  reportTransition(outcome, seq) {
+    const name = outcome.entry.name;
+    const previous = this.lastState.get(name);
+    if (previous !== void 0 && seq <= previous.seq) {
+      return;
+    }
+    const changed = previous?.isUp !== outcome.isUp;
+    this.lastState.set(name, { isUp: outcome.isUp, seq });
+    if (!changed) {
+      return;
+    }
+    if (outcome.isUp) {
+      if (previous === void 0) {
+        return;
+      }
+      this.describe(`Health check "${name}" recovered`, false);
+      this.emit({ name, isUp: true });
+      return;
+    }
+    this.describe(`Health check "${name}" went down: ${describeCause(outcome.cause)}`, true);
+    this.emit({ name, isUp: false, cause: outcome.cause });
+  }
+  /**
+   * Write a transition to this package's own logger, unless a sink is bound —
+   * the reasoning for standing down is on `IHealthTransitionSink`.
+   *
+   * Down is a warning, not an error: an unreachable dependency is what readiness
+   * exists to route around, while `error` is what pages someone.
+   *
+   * @param message - The line to write.
+   * @param isDown - Whether it describes a check going down, which sets the level.
+   */
+  describe(message, isDown) {
+    if (this.transitionSink !== void 0) {
+      return;
+    }
+    this.writeLine(message, isDown);
+  }
+  /**
+   * Write one line to this package's logger, absorbing a logger that fails.
+   *
+   * Nest's logger is replaceable, so what this calls is application code. It can
+   * throw — most plausibly for the very reason a transition is being reported at
+   * all, when the sink and the logger share a backend that is down. Uncontained
+   * that throw leaves the readiness path: synchronously it rejects the probe,
+   * and from the asynchronous sink handler it becomes an unhandled rejection.
+   * Either way a healthy deployment leaves rotation because its logging broke,
+   * which is the outcome this whole seam exists to prevent.
+   *
+   * The failure is swallowed rather than reported, because a logger is the last
+   * place a failure could be reported to. There is nowhere left to go.
+   *
+   * @param message - The line to write.
+   * @param asWarning - Whether to write it at warning level.
+   */
+  writeLine(message, asWarning) {
+    try {
+      if (asWarning) {
+        this.logger.warn(message);
+        return;
+      }
+      this.logger.log(message);
+    } catch {
+    }
+  }
+  /**
+   * Hand a transition to the consumer's sink, if one is bound. A failure is
+   * contained: readiness answering `500` because its own logging broke would
+   * take a healthy deployment out of rotation over an observability fault.
+   *
+   * Both ways a sink can fail are caught, for the same reason `runIndicator`
+   * defends against an indicator that throws synchronously — a public seam
+   * cannot assume the implementation behind it honors its own signature.
+   * `record` is declared to return `void`, but TypeScript accepts any return
+   * value in a void-returning position, so `async record()` compiles and is the
+   * shape a consumer reaches for when the logger it delegates to is async. Its
+   * rejection lands a microtask after the `try` block has exited, which is an
+   * unhandled rejection rather than the contained failure documented on the
+   * contract.
+   *
+   * Whatever comes back is assimilated with `Promise.resolve`, not tested with
+   * `instanceof Promise`: `Promise` is a per-realm binding, so an `async` sink
+   * defined in another realm returns a native promise that fails `instanceof`
+   * here, and a userland promise library's result is not an instance either.
+   * Assimilation is the language's own thenable test, and it is inert for the
+   * `undefined` an ordinary synchronous sink returns.
+   *
+   * @param transition - The event to deliver.
+   */
+  emit(transition) {
+    if (this.transitionSink === void 0) {
+      return;
+    }
+    try {
+      containRejection(this.transitionSink.record(transition), (error) => {
+        this.reportSinkFailure(error);
+      });
+    } catch (error) {
+      this.reportSinkFailure(error);
+    }
+  }
+  /**
+   * Log a sink failure, without letting it reach the probe.
+   *
+   * @param error - Whatever the sink threw or rejected with.
+   */
+  reportSinkFailure(error) {
+    this.writeLine(
+      `Health transition sink threw and was ignored: ${summarizeRejection(error)}`,
+      true
+    );
   }
   /**
    * Resolve the readiness set once the whole container is instantiated.
@@ -799,11 +980,14 @@ var HealthService = class {
   async checkReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
     const exposeErrors = this.options.health.exposeIndicatorErrors;
-    const checks = await Promise.all(
-      this.resolveIndicators().map(
-        (indicator) => runIndicator(indicator, timeoutMs, exposeErrors, this.logger)
-      )
+    const seq = ++this.probeSequence;
+    const outcomes = await Promise.all(
+      this.resolveIndicators().map((indicator) => runIndicator(indicator, timeoutMs, exposeErrors))
     );
+    for (const outcome of outcomes) {
+      this.reportTransition(outcome, seq);
+    }
+    const checks = outcomes.map((outcome) => outcome.entry);
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
     return { status, checks };
   }
@@ -816,7 +1000,9 @@ HealthService = __decorateClass([
   __decorateParam(2, Optional()),
   __decorateParam(2, Inject(DiscoveryService)),
   __decorateParam(3, Optional()),
-  __decorateParam(3, Inject(Reflector))
+  __decorateParam(3, Inject(Reflector)),
+  __decorateParam(4, Optional()),
+  __decorateParam(4, Inject(BYMAX_HEALTH_TRANSITION_SINK))
 ], HealthService);
 
 // src/health/health.controller.ts
@@ -1204,6 +1390,13 @@ function buildTimingSample(input) {
     ...trace !== void 0 ? { traceId: trace.traceId, spanId: trace.spanId } : {}
   };
 }
+function deliverSample(sink, sample) {
+  try {
+    containRejection(sink.record(sample), () => {
+    });
+  } catch {
+  }
+}
 
 // src/timing/timing.middleware.ts
 var BymaxTimingMiddleware = class {
@@ -1253,7 +1446,8 @@ var BymaxTimingMiddleware = class {
     next();
   }
   /**
-   * Build the sample and hand it to the sink, guarding both steps.
+   * Build the sample and deliver it. `deliverSample` absorbs whatever the sink
+   * does with it, so a broken sink never reaches the request it observes.
    *
    * @param request - The framework request object.
    * @param response - The framework response object.
@@ -1271,10 +1465,7 @@ var BymaxTimingMiddleware = class {
       threshold: this.options.timing.slowRequestThresholdMs,
       trace
     });
-    try {
-      this.sink.record(sample);
-    } catch {
-    }
+    deliverSample(this.sink, sample);
   }
 };
 BymaxTimingMiddleware = __decorateClass([
@@ -1395,9 +1586,12 @@ var BymaxCoreModule = class extends BymaxCoreModuleBase {
    * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
    * prescribes for "all routes" — stops matching the prefixed root once an
    * application calls `setGlobalPrefix`. That was reported as nest#14520 and
-   * fixed by nest#14522, whose regression test covers Fastify; on
-   * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
-   * reaches no middleware while resolving to `200`.
+   * fixed by nest#14522, whose regression test covers Fastify; on the Express
+   * adapter the prefixed root still reaches no middleware while resolving to
+   * `200`. Measured on `@nestjs/core` 11.1.28 and re-measured unchanged on
+   * 11.2.1 — a minor release is exactly where this would plausibly have been
+   * fixed, so the version this was last confirmed against is part of the
+   * claim rather than a footnote to it.
    *
    * On Fastify the same `'/'` is an exact match rather than a mount — one of
    * three requests reached the middleware — so the wildcard is the only form
@@ -1587,9 +1781,8 @@ var TimingInterceptor = class {
     return error instanceof HttpException ? error.getStatus() : UNKNOWN_ERROR_STATUS;
   }
   /**
-   * Build the sample and deliver it to the sink inside a try/catch that
-   * silences any failure: a throwing sink must never affect the request it is
-   * observing.
+   * Build the sample and deliver it. `deliverSample` absorbs whatever the sink
+   * does with it: a broken sink must never affect the request it observes.
    *
    * @param method - HTTP method of the request.
    * @param route - Route template of the request.
@@ -1605,10 +1798,7 @@ var TimingInterceptor = class {
       threshold: this.options.timing.slowRequestThresholdMs,
       trace: readTraceContext(this.traceContext)
     });
-    try {
-      this.sink.record(sample);
-    } catch {
-    }
+    deliverSample(this.sink, sample);
   }
 };
 TimingInterceptor = __decorateClass([
@@ -1621,4 +1811,4 @@ TimingInterceptor = __decorateClass([
   __decorateParam(3, Inject(BYMAX_TRACE_CONTEXT))
 ], TimingInterceptor);
 
-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_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_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+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_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };

package/dist/openapi/index.cjs

@@ -326,7 +326,7 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.document.ts
+// src/openapi/openapi.shape.ts
 var OPERATION_METHODS = [
   "get",
   "post",
@@ -337,21 +337,26 @@ var OPERATION_METHODS = [
   "options",
   "trace"
 ];
-var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
-var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
-var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
   }
   return value;
 }
-function mergeAbsent(existing, additions) {
-  return { ...additions, ...existing };
-}
 function operationsOf(item) {
   return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
 }
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.document.ts
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
+function mergeAbsent(existing, additions) {
+  return { ...additions, ...existing };
+}
 function mergeResponses(existing, additions) {
   const merged = new Map(Object.entries(existing));
   for (const [status, value] of Object.entries(additions)) {
@@ -377,21 +382,24 @@ function withoutDisabledRoutes(paths, options, routes) {
   });
   return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
 }
-function ownRouteSecurity(path, method, options, routes) {
+function inheritsRequirement(document, openapi) {
+  if (document.security === void 0) {
+    return openapi.security.length > 0;
+  }
+  return Array.isArray(document.security) && document.security.length > 0;
+}
+function ownRouteSecurity(path, method, options, routes, inherits) {
   if (method !== "get") {
     return void 0;
   }
   if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
     return [{ [METRICS_SCHEME_NAME]: [] }];
   }
-  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+  if (inherits && (routes.isHealth(path) || routes.isMetrics(path))) {
     return [];
   }
   return void 0;
 }
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
 function coreResponses(path, options, routes) {
   const responses = {};
   if (options.envelope.enabled) {
@@ -425,7 +433,7 @@ function mergeFragment(operation, fragment) {
   }
   return merged;
 }
-function augmentOperation(operation, path, method, options, routes, contributions) {
+function augmentOperation(operation, path, method, options, routes, contributions, inherits) {
   const declaredByDocument = operation["security"] !== void 0;
   let result = { ...operation };
   for (const fragment of fragmentsFor(result["operationId"], contributions)) {
@@ -434,7 +442,7 @@ function augmentOperation(operation, path, method, options, routes, contribution
   if (!declaredByDocument) {
     const override = options.openapi.operationSecurity[operationKey(method, path)];
     const describedByLibrary = result["security"] !== void 0;
-    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes, inherits));
     if (security !== void 0) {
       result["security"] = security;
     }
@@ -509,12 +517,20 @@ function assertOverridesMatch(paths, openapi) {
     `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
   );
 }
-function augmentPaths(paths, options, routes, contributions) {
+function augmentPaths(paths, options, routes, contributions, inherits) {
   return Object.fromEntries(
     Object.entries(paths).map(([path, item]) => {
       const augmented = operationsOf(item).map(([method, operation]) => [
         method,
-        augmentOperation(asRecord(operation), path, method, options, routes, contributions)
+        augmentOperation(
+          asRecord(operation),
+          path,
+          method,
+          options,
+          routes,
+          contributions,
+          inherits
+        )
       ]);
       return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
     })
@@ -552,7 +568,15 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
   assertOverridesMatch(served, openapi);
-  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes, contributions) };
+  const paths = document.paths === void 0 ? {} : {
+    paths: augmentPaths(
+      served,
+      options,
+      routes,
+      contributions,
+      inheritsRequirement(document, openapi)
+    )
+  };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
   return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }