@ultimat3/core 27.6.0 → 27.7.0

package/README.md

@@ -494,7 +494,10 @@ match with `sealAll()`; uniqueness cannot be held across keys.
   **bound**. `ReadinessCheck` is `() => boolean` and must stay synchronous — a probe that awaits its
   dependency turns a slow dependency into a wedged endpoint and then a restart loop; keep a boolean
   fresh and let the check read it. It returns an unregister. `HealthReport.checks` is a map of name
-  → `'ok' | 'failing'`, so "alert on check failures by check name" is writable.
+  → `'ok' | 'degraded' | 'failing'`, so "alert on check failures by check name" is writable.
+  `registerReadinessCheck(name, check, { onFailure: 'degraded' })` is a dependency the role serves
+  without (the bus of a role that only publishes to it): its `false` is `'degraded'`, never a 503
+  on `/readyz` in either mode, and a 503 on `/readyz?deep=1`.
 - **`HealthReport.registered` is the third state.** `checks: {}` reads identically for "every check
   passed" and "nobody registered one", and an **empty registry is still ready** — reported, never
   enforced, so a role with no dependency does not have to invent a check to boot. Read `registered`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "27.6.0",
+  "version": "27.7.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "27.6.0"
+    "@ultimat3/schema": "27.7.0"
   }
 }

package/src/index.ts

@@ -646,7 +646,11 @@ export {
   READINESS_GRACE_DEFAULT_MS,
   READINESS_GRACE_MAX_MS,
 } from './lifecycle-grace';
-export type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
+export type {
+  ReadinessCheck,
+  ReadinessCheckOptions,
+  ReadinessStatus,
+} from './lifecycle-readiness';
 export type { SignalHandlerOptions } from './lifecycle-signals';
 export { drainSignals, installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';

package/src/lifecycle-readiness.ts

@@ -4,7 +4,22 @@
 
 import { UltimateError } from './errors';
 
-export type ReadinessStatus = 'ok' | 'failing';
+/**
+ * `'degraded'` is a failed check the role serves WITHOUT (`onFailure: 'degraded'`): reported by
+ * name, never a 503 on `/readyz` in either mode, and a 503 on `/readyz?deep=1` — the probe routes
+ * traffic on the first and a monitor alerts on the second.
+ */
+export type ReadinessStatus = 'ok' | 'degraded' | 'failing';
+
+export interface ReadinessCheckOptions {
+  /**
+   * What a `false` (or a throw) from this check is. `'failing'`, the default, is a dependency the
+   * role cannot serve without. `'degraded'` is one it can — the bus of a role that only publishes
+   * to it: pulling every replica from the ingress for a dependency no served request waits on is
+   * the outage the probe exists to prevent.
+   */
+  readonly onFailure?: 'failing' | 'degraded' | undefined;
+}
 
 /**
  * Synchronous, and that is the design, not a limitation. **Do not widen this to
@@ -23,13 +38,22 @@ export type ReadinessStatus = 'ok' | 'failing';
  */
 export type ReadinessCheck = () => boolean;
 
-const checks = new Map<string, ReadinessCheck>();
+interface Registered {
+  readonly check: ReadinessCheck;
+  readonly onFailure: 'failing' | 'degraded';
+}
+
+const checks = new Map<string, Registered>();
 
 /**
  * Register a named readiness check. Returns its unregister — the same shape as `onShutdown`, and
  * owned by whoever can be started twice, for the same reason.
  */
-export function registerReadinessCheck(name: string, check: ReadinessCheck): () => void {
+export function registerReadinessCheck(
+  name: string,
+  check: ReadinessCheck,
+  options: ReadinessCheckOptions = {},
+): () => void {
   if (checks.has(name)) {
     throw new UltimateError({
       code: 'X_READINESS_CHECK_DUPLICATE',
@@ -38,9 +62,10 @@ export function registerReadinessCheck(name: string, check: ReadinessCheck): ()
       meta: { name },
     });
   }
-  checks.set(name, check);
+  const registered: Registered = { check, onFailure: options.onFailure ?? 'failing' };
+  checks.set(name, registered);
   return () => {
-    if (checks.get(name) === check) checks.delete(name);
+    if (checks.get(name) === registered) checks.delete(name);
   };
 }
 
@@ -55,8 +80,8 @@ export function clearReadinessChecks(): void {
 }
 
 /**
- * Every check, run now, by name. A check that throws is `failing` — never an unhandled error —
- * and is handed to `onThrow`, which `lifecycle.ts` routes through its total `report`.
+ * Every check, run now, by name. A check that throws is its `onFailure` (`failing` unless it was
+ * registered degradable) — never an unhandled error — and is handed to `onThrow`, which `lifecycle.ts` routes through its total `report`.
  *
  * Built through `Object.fromEntries`, never by assigning `results[name]`: assignment to the one
  * name `__proto__` sets the PROTOTYPE instead of adding a key, so that check vanished from the
@@ -67,11 +92,11 @@ export function runReadinessChecks(
   onThrow: (name: string, thrown: unknown) => void,
 ): Readonly<Record<string, ReadinessStatus>> {
   const results: [string, ReadinessStatus][] = [];
-  for (const [name, check] of checks) {
+  for (const [name, { check, onFailure }] of checks) {
     try {
-      results.push([name, check() ? 'ok' : 'failing']);
+      results.push([name, check() ? 'ok' : onFailure]);
     } catch (thrown) {
-      results.push([name, 'failing']);
+      results.push([name, onFailure]);
       onThrow(name, thrown);
     }
   }

package/src/lifecycle.ts

@@ -374,9 +374,15 @@ export function drain(signal = 'manual'): Promise<void> {
   return drainPromise;
 }
 
-export function healthReport(mode: ReadinessMode = readinessMode): HealthReport {
+export function healthReport(
+  mode: ReadinessMode = readinessMode,
+  /** `/readyz?deep=1`: a `'degraded'` check is not ready either. Never the probe's reading. */
+  strict = false,
+): HealthReport {
   const checks = readinessChecks();
-  const dependencies = Object.values(checks).every((status) => status === 'ok');
+  const dependencies = Object.values(checks).every(
+    (status) => status === 'ok' || (!strict && status === 'degraded'),
+  );
   return {
     state,
     // `ready` is the same predicate `/readyz` answers on, so a body and its status can never
@@ -405,9 +411,11 @@ export function healthzPayload(): HealthPayload {
 /**
  * Readiness: may this instance receive traffic? 503 while starting or draining, and — in the
  * default `'dependencies'` mode, or always with `deep` (`/readyz?deep=1`) — while any check fails.
+ * A `'degraded'` check (`ReadinessCheckOptions.onFailure`) is a 503 under `deep` ALONE.
  */
 export function readyzPayload(options: { readonly deep?: boolean } = {}): HealthPayload {
-  const body = healthReport(options.deep === true ? 'dependencies' : readinessMode);
+  const deep = options.deep === true;
+  const body = healthReport(deep ? 'dependencies' : readinessMode, deep);
   return { ok: body.ready, status: body.ready ? 200 : 503, body };
 }