@bymax-one/nest-core 1.5.3 → 1.6.0

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([
@@ -1590,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.
@@ -1608,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([
@@ -1624,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",