@ultimat3/core 22.4.0 → 22.5.0

package/package.json

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

package/src/config-health.ts

@@ -0,0 +1,58 @@
+// Single responsibility: the `health` and `drain` sections of `app.config.ts` — what `/readyz`
+// means and how a SIGTERM'd process leaves the load balancer — and the domain of the readiness
+// mode, so the config validator and `configureLifecycle` refuse the same values.
+
+import { UltimateError } from './errors';
+
+/**
+ * `'dependencies'` (the default): `/readyz` is 503 while starting, draining, or while ANY registered
+ * check fails. `'process'`: 503 only while starting or draining — a failing check is REPORTED in the
+ * body (`checks.database: 'failing'`) and the status stays 200.
+ *
+ * Why the second exists: every replica shares the dependency, so one database blip marks the WHOLE
+ * fleet unready at once and the ingress answers "no available server" for every URL — pages that
+ * never touch the database included — where the app itself would have served them, or answered its
+ * own 503 for the ones that do. `/readyz?deep=1` always answers in `'dependencies'` mode, so
+ * monitoring still sees the dependency fail.
+ */
+export type ReadinessMode = 'dependencies' | 'process';
+
+export const READINESS_MODES: readonly ReadinessMode[] = ['dependencies', 'process'];
+
+/** `app.config.ts`'s `health` section. Read by the production boot into `configureLifecycle`. */
+export interface HealthConfig {
+  readonly readiness: ReadinessMode;
+}
+
+/**
+ * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
+ * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
+ */
+export interface DrainConfig {
+  /**
+   * `/readyz` answers 503 for this long before the listener closes, so endpoints stop routing here
+   * first. Default 0 in development/test and 5000 everywhere else — a process naming NO environment
+   * included. A whole number, 0–60000. The chart's `terminationGracePeriodSeconds` must exceed it
+   * plus the drain budget.
+   */
+  readonly readinessGraceMs: number;
+}
+
+/** Why a value is not a readiness mode, or `undefined` when it is one. */
+export function readinessModeIssue(value: unknown): string | undefined {
+  if (READINESS_MODES.some((mode) => mode === value)) return undefined;
+  const said = typeof value === 'string' ? `"${value}"` : typeof value;
+  return `health.readiness ${said} is not one of ${READINESS_MODES.join(', ')}`;
+}
+
+/** `configureLifecycle`'s screen: the mode, or `X_CONFIG_INVALID` naming the key. */
+export function assertReadinessMode(value: unknown): ReadinessMode {
+  const issue = readinessModeIssue(value);
+  if (issue === undefined) return value as ReadinessMode;
+  throw new UltimateError({
+    code: 'X_CONFIG_INVALID',
+    cause: issue,
+    fix: "set health: { readiness: 'process' } (or 'dependencies', the default) in app.config.ts",
+    meta: { key: 'health.readiness' },
+  });
+}

package/src/config.ts

@@ -9,6 +9,8 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 import { countIssue } from './config-count';
 import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
+import type { DrainConfig, HealthConfig } from './config-health';
+import { readinessModeIssue } from './config-health';
 import { type Input, lastSaid, layered } from './config-merge';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
@@ -183,20 +185,6 @@ export interface AiConfig {
   readonly mcp: McpConfig;
 }
 
-/**
- * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
- * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
- */
-export interface DrainConfig {
-  /**
-   * `/readyz` answers 503 for this long before the listener closes, so endpoints stop routing here
-   * first. Default 0 in development/test and 5000 everywhere else — a process naming NO environment
-   * included. A whole number, 0–60000. The chart's `terminationGracePeriodSeconds` must exceed it
-   * plus the drain budget.
-   */
-  readonly readinessGraceMs: number;
-}
-
 export interface AppConfig {
   readonly name: string;
   readonly locales: readonly string[];
@@ -214,6 +202,7 @@ export interface AppConfig {
   readonly notify: NotifyConfig;
   readonly ai: AiConfig;
   readonly drain: DrainConfig;
+  readonly health: HealthConfig;
   readonly site: SiteConfig;
   readonly seo: SeoConfig;
 }
@@ -251,6 +240,7 @@ export interface AppConfigInput extends SiteSectionsInput {
   readonly notify?: Input<NotifyConfig> | undefined;
   readonly ai?: AiConfigInput | undefined;
   readonly drain?: Input<DrainConfig> | undefined;
+  readonly health?: Input<HealthConfig> | undefined;
 }
 
 /** An overlay from `config/<concern>.ts`. No `name` — the base owns it. */
@@ -308,6 +298,7 @@ function defaults(name: string): Omit<AppConfig, 'name' | 'site' | 'seo'> {
     ai: { mcp: { expose: true, path: '/mcp' } },
     // Read from the process env when the config is DEFINED — the same env the drain will run in.
     drain: { readinessGraceMs: defaultReadinessGraceMs() },
+    health: { readiness: 'dependencies' },
   };
 }
 
@@ -352,6 +343,7 @@ function validate(config: AppConfig): void {
     countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
     countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
     readinessGraceIssue(config.drain.readinessGraceMs),
+    readinessModeIssue(config.health.readiness),
   ];
   for (const issue of counts) if (issue !== undefined) issues.push(issue);
   if (config.jobs.queues.length === 0) issues.push('jobs.queues must list at least one queue');
@@ -492,6 +484,10 @@ export function defineConfig(
       base.drain,
       layers.map((layer) => layer.drain),
     ),
+    health: layered(
+      base.health,
+      layers.map((layer) => layer.health),
+    ),
     ...mergeSite(layers),
   };
 

package/src/index.ts

@@ -98,7 +98,6 @@ export type {
   AuthConfig,
   CacheConfig,
   DatabaseConfig,
-  DrainConfig,
   JobsConfig,
   McpConfig,
   NotifyConfig,
@@ -109,6 +108,8 @@ export type {
   ThemeMode,
 } from './config';
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
+export type { DrainConfig, HealthConfig, ReadinessMode } from './config-health';
+export { READINESS_MODES } from './config-health';
 export type {
   PwaColors,
   PwaConfig,
@@ -515,8 +516,6 @@ export type {
   LifecycleOptions,
   OnShutdownOptions,
   ProcessSignal,
-  ReadinessCheck,
-  ReadinessStatus,
   ShutdownHook,
   ShutdownPhase,
   ShutdownReason,
@@ -548,6 +547,7 @@ export {
   READINESS_GRACE_DEFAULT_MS,
   READINESS_GRACE_MAX_MS,
 } from './lifecycle-grace';
+export type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
 export type { SignalHandlerOptions } from './lifecycle-signals';
 export { installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';

package/src/lifecycle-readiness.ts

@@ -0,0 +1,21 @@
+// Single responsibility: the readiness CHECK — its signature and its two answers. The mode that
+// decides what a failing one does to `/readyz` is `config-health.ts`'s.
+
+export type ReadinessStatus = 'ok' | 'failing';
+
+/**
+ * Synchronous, and that is the design, not a limitation. **Do not widen this to
+ * `() => Promise<boolean>`** — the signature is the mechanism.
+ *
+ * A readiness endpoint that does I/O is a liveness bomb. A probe that awaits a network call takes
+ * as long as the dependency does, so a slow database makes the endpoint miss its `timeoutSeconds`,
+ * the kubelet reads that as unready, and capacity is pulled from an already-struggling system —
+ * the outage the probe existed to prevent, caused by the probe. Worse under a liveness probe
+ * sharing the handler: the pod is killed and restarts into the same slow database, cold.
+ *
+ * So the owner of the dependency keeps a boolean fresh — a pool exposes `isOpen`, a background
+ * poller flips a flag on its own schedule with its own timeout — and this reads it. That puts the
+ * waiting where a timeout can be tuned, and leaves this path unable to block. A check that throws
+ * is `failing`.
+ */
+export type ReadinessCheck = () => boolean;

package/src/lifecycle.ts

@@ -3,11 +3,14 @@
 // and reports the same /healthz + /readyz state.
 
 import { type Clock, systemClock } from './clock';
+import type { ReadinessMode } from './config-health';
+import { assertReadinessMode } from './config-health';
 import { UltimateError } from './errors';
 import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
 import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
+import type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
@@ -64,29 +67,12 @@ export interface LifecycleOptions {
    * A whole number from 0 to 60000; 0 is no grace.
    */
   readonly readinessGraceMs?: number | undefined;
+  /** What a failing check does to `/readyz` — see `ReadinessMode`. Default `'dependencies'`. */
+  readonly readiness?: ReadinessMode | undefined;
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
 }
 
-export type ReadinessStatus = 'ok' | 'failing';
-
-/**
- * Synchronous, and that is the design, not a limitation. **Do not widen this to
- * `() => Promise<boolean>`** — the signature is the mechanism.
- *
- * A readiness endpoint that does I/O is a liveness bomb. A probe that awaits a network call takes
- * as long as the dependency does, so a slow database makes the endpoint miss its `timeoutSeconds`,
- * the kubelet reads that as unready, and capacity is pulled from an already-struggling system —
- * the outage the probe existed to prevent, caused by the probe. Worse under a liveness probe
- * sharing the handler: the pod is killed and restarts into the same slow database, cold.
- *
- * So the owner of the dependency keeps a boolean fresh — a pool exposes `isOpen`, a background
- * poller flips a flag on its own schedule with its own timeout — and this reads it. That puts the
- * waiting where a timeout can be tuned, and leaves this path unable to block. A check that throws
- * is `failing`.
- */
-export type ReadinessCheck = () => boolean;
-
 export interface HealthReport {
   readonly state: HealthState;
   readonly ready: boolean;
@@ -123,6 +109,7 @@ const DEFAULT_DEADLINE_MS = 25_000;
 let deadlineMs = DEFAULT_DEADLINE_MS;
 /** `undefined` means "the environment's default", read when a drain starts, not at import. */
 let graceMs: number | undefined;
+let readinessMode: ReadinessMode = 'dependencies';
 let clock: Clock = systemClock;
 let log: Logger = rootLogger;
 let state: HealthState = 'starting';
@@ -155,6 +142,7 @@ export function configureLifecycle(options: LifecycleOptions): void {
     }
     graceMs = options.readinessGraceMs;
   }
+  if (options.readiness !== undefined) readinessMode = assertReadinessMode(options.readiness);
   if (options.clock !== undefined) {
     clock = options.clock;
     startedAtMono = clock.monotonic();
@@ -451,13 +439,15 @@ export function drain(signal = 'manual'): Promise<void> {
   return drainPromise;
 }
 
-export function healthReport(): HealthReport {
+export function healthReport(mode: ReadinessMode = readinessMode): HealthReport {
   const checks = readinessChecks();
+  const dependencies = Object.values(checks).every((status) => status === 'ok');
   return {
     state,
     // `ready` is the same predicate `/readyz` answers on, so a body and its status can never
     // disagree — a 200 whose body says `ready: false` is the bug this shares one source to avoid.
-    ready: state === 'ready' && Object.values(checks).every((status) => status === 'ok'),
+    // `'process'` mode leaves the checks OUT of it, and still reports every one of them below.
+    ready: state === 'ready' && (mode === 'process' || dependencies),
     uptimeMs: Math.round(clock.monotonic() - startedAtMono),
     inflight,
     buildId: process.env['BUILD_ID'] ?? 'dev',
@@ -477,9 +467,12 @@ export function healthzPayload(): HealthPayload {
   return { ok, status: ok ? 200 : 503, body };
 }
 
-/** Readiness: may this instance receive traffic? 503 while starting, draining or any check fails. */
-export function readyzPayload(): HealthPayload {
-  const body = healthReport();
+/**
+ * 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.
+ */
+export function readyzPayload(options: { readonly deep?: boolean } = {}): HealthPayload {
+  const body = healthReport(options.deep === true ? 'dependencies' : readinessMode);
   return { ok: body.ready, status: body.ready ? 200 : 503, body };
 }
 
@@ -487,6 +480,7 @@ export function readyzPayload(): HealthPayload {
 export function resetLifecycle(): void {
   deadlineMs = DEFAULT_DEADLINE_MS;
   graceMs = undefined;
+  readinessMode = 'dependencies';
   clock = systemClock;
   log = rootLogger;
   state = 'starting';