@btravstack/core 0.45.0 → 0.46.0

package/README.md

@@ -166,6 +166,12 @@ ports hidden. Application starters use it alongside their own runtime exports.
 - **Probes from the state machine.** `GET /livez` and `GET /readyz` on
   `PROBE_PORT` (default `9000`) and `PROBE_HOST` (default `0.0.0.0`, so a
   kubelet `httpGet` probe reaches them), up before the graph is built.
+  A `HealthCheck` can opt into gating `/readyz` with `readiness: true`
+  (1000 ms cache) or `readiness: { intervalMs: 5000 }`. Concurrent probes and
+  `/healthz` share that check's cache; ordinary checks only affect `/healthz`.
+  Failed checks can recover without a restart; drain and crash readiness
+  remain latched. `RunningApp.ready()` reads only the lifecycle.
+  See [probes](https://btravstack.github.io/btravstack/reference/core/probes).
 - **Configuration from the environment, typed.** The kernel provides
   [`@btravstack/config`](../config)'s `Env` port to every graph it boots; a
   bad value is a `ConfigInvalid` naming every fault at once, and exit `78`.

package/dist/index.cjs

@@ -332,6 +332,46 @@ const drainApp = (args) => {
 	});
 };
 //#endregion
+//#region src/health-monitor.ts
+const cachedCheck = (check, clock) => {
+	const interval = typeof check.readiness === "object" ? check.readiness.intervalMs : 1e3;
+	let cached;
+	let expiresAt = 0;
+	let pending;
+	return () => {
+		if (!Number.isFinite(interval) || interval <= 0) return (0, unthrown.OkAsync)({
+			status: "unhealthy",
+			components: [{
+				name: check.name,
+				status: "unhealthy",
+				reason: "readiness interval must be a positive finite number"
+			}]
+		});
+		if (cached !== void 0 && clock.now() < expiresAt) return (0, unthrown.OkAsync)(cached);
+		pending ??= runHealthChecks([check]).map((report) => {
+			cached = report;
+			expiresAt = clock.now() + interval;
+			pending = void 0;
+			return report;
+		});
+		return pending;
+	};
+};
+/** Per-application checks; only readiness contributors retain a cached report. */
+const healthMonitor = (checks, clock) => {
+	const entries = checks.map((check) => ({
+		readiness: Boolean(check.readiness),
+		run: check.readiness ? cachedCheck(check, clock) : () => runHealthChecks([check])
+	}));
+	return {
+		health: () => (0, unthrown.allAsync)(entries.map((entry) => entry.run())).map((reports) => ({
+			status: reports.every((report) => report.status === "healthy") ? "healthy" : "unhealthy",
+			components: reports.flatMap((report) => report.components)
+		})),
+		readiness: () => (0, unthrown.allAsync)(entries.filter((entry) => entry.readiness).map((entry) => entry.run())).map((reports) => reports.every((report) => report.status === "healthy"))
+	};
+};
+//#endregion
 //#region src/phase.ts
 const ORDER = [
 	"building",
@@ -363,7 +403,11 @@ const startProbeServer = (args) => (0, unthrown.fromSafePromise)(new Promise((re
 			return;
 		}
 		if (request.url === "/readyz") {
-			respond(response, args.ready(), "ready");
+			if (!args.ready() || args.readiness === void 0) {
+				respond(response, args.ready(), "ready");
+				return;
+			}
+			args.readiness().map((healthy) => respond(response, args.ready() && healthy, "ready"));
 			return;
 		}
 		if (request.url === "/healthz") {
@@ -716,8 +760,9 @@ const start = (module, options = {}) => {
 		uptimeMs: clock.now() - startedAt,
 		...abandonedAt === void 0 ? {} : { abandonedAt }
 	});
-	let healthChecks = [];
-	const health = () => runHealthChecks(healthChecks);
+	let monitor = healthMonitor([], clock);
+	const health = () => monitor.health();
+	const readiness = () => monitor.readiness();
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	const leaveStartup = () => {
@@ -774,6 +819,7 @@ const start = (module, options = {}) => {
 		hostname: probes.hostname,
 		live,
 		ready,
+		readiness,
 		health
 	}).tap((server) => {
 		probeBoundPort = server.port;
@@ -840,7 +886,7 @@ const start = (module, options = {}) => {
 		tracker.advanceTo("starting");
 		const runtime = ctx.get(RuntimePort);
 		runtimeName = runtime.name;
-		healthChecks = ctx.get(HealthChecks);
+		monitor = healthMonitor(ctx.get(HealthChecks), clock);
 		const runtimeCtx = ctx;
 		const rebuilt = rebuildGuard(runtime.name, root);
 		for (const unit of Object.values(runtime.units ?? {})) {

package/dist/index.d.cts

@@ -58,6 +58,15 @@ type HealthCheck = {
    * its own latency omits it.
    */
   readonly timeoutMs?: number;
+  /**
+   * Opt into gating `/readyz`. `true` caches the result for 1000 ms;
+   * an object selects a positive, finite interval. Concurrent probes share
+   * one evaluation, and `/healthz` uses the same cache for this check.
+   * Omitted or `false` leaves readiness independent of this component.
+   */
+  readonly readiness?: boolean | {
+    readonly intervalMs: number;
+  };
 };
 declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
 /**
@@ -864,9 +873,9 @@ type RunningApp<E, Info = never> = {
   readonly requestDrain: () => void;
   readonly phase: () => Phase;
   /**
-   * The predicate `/readyz` answers from — serving, and not forced unready by
-   * a drain or an uncaught exception — read synchronously, which the probe
-   * endpoint is not.
+   * The synchronous lifecycle predicate: serving, and not forced unready by
+   * a drain or an uncaught exception. `/readyz` additionally consults opted-in
+   * dependency checks; this method does not evaluate them.
    */
   readonly ready: () => boolean;
   /**

package/dist/index.d.mts

@@ -58,6 +58,15 @@ type HealthCheck = {
    * its own latency omits it.
    */
   readonly timeoutMs?: number;
+  /**
+   * Opt into gating `/readyz`. `true` caches the result for 1000 ms;
+   * an object selects a positive, finite interval. Concurrent probes share
+   * one evaluation, and `/healthz` uses the same cache for this check.
+   * Omitted or `false` leaves readiness independent of this component.
+   */
+  readonly readiness?: boolean | {
+    readonly intervalMs: number;
+  };
 };
 declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
 /**
@@ -864,9 +873,9 @@ type RunningApp<E, Info = never> = {
   readonly requestDrain: () => void;
   readonly phase: () => Phase;
   /**
-   * The predicate `/readyz` answers from — serving, and not forced unready by
-   * a drain or an uncaught exception — read synchronously, which the probe
-   * endpoint is not.
+   * The synchronous lifecycle predicate: serving, and not forced unready by
+   * a drain or an uncaught exception. `/readyz` additionally consults opted-in
+   * dependency checks; this method does not evaluate them.
    */
   readonly ready: () => boolean;
   /**

package/dist/index.mjs

@@ -331,6 +331,46 @@ const drainApp = (args) => {
 	});
 };
 //#endregion
+//#region src/health-monitor.ts
+const cachedCheck = (check, clock) => {
+	const interval = typeof check.readiness === "object" ? check.readiness.intervalMs : 1e3;
+	let cached;
+	let expiresAt = 0;
+	let pending;
+	return () => {
+		if (!Number.isFinite(interval) || interval <= 0) return OkAsync({
+			status: "unhealthy",
+			components: [{
+				name: check.name,
+				status: "unhealthy",
+				reason: "readiness interval must be a positive finite number"
+			}]
+		});
+		if (cached !== void 0 && clock.now() < expiresAt) return OkAsync(cached);
+		pending ??= runHealthChecks([check]).map((report) => {
+			cached = report;
+			expiresAt = clock.now() + interval;
+			pending = void 0;
+			return report;
+		});
+		return pending;
+	};
+};
+/** Per-application checks; only readiness contributors retain a cached report. */
+const healthMonitor = (checks, clock) => {
+	const entries = checks.map((check) => ({
+		readiness: Boolean(check.readiness),
+		run: check.readiness ? cachedCheck(check, clock) : () => runHealthChecks([check])
+	}));
+	return {
+		health: () => allAsync(entries.map((entry) => entry.run())).map((reports) => ({
+			status: reports.every((report) => report.status === "healthy") ? "healthy" : "unhealthy",
+			components: reports.flatMap((report) => report.components)
+		})),
+		readiness: () => allAsync(entries.filter((entry) => entry.readiness).map((entry) => entry.run())).map((reports) => reports.every((report) => report.status === "healthy"))
+	};
+};
+//#endregion
 //#region src/phase.ts
 const ORDER = [
 	"building",
@@ -362,7 +402,11 @@ const startProbeServer = (args) => fromSafePromise(new Promise((resolve) => {
 			return;
 		}
 		if (request.url === "/readyz") {
-			respond(response, args.ready(), "ready");
+			if (!args.ready() || args.readiness === void 0) {
+				respond(response, args.ready(), "ready");
+				return;
+			}
+			args.readiness().map((healthy) => respond(response, args.ready() && healthy, "ready"));
 			return;
 		}
 		if (request.url === "/healthz") {
@@ -715,8 +759,9 @@ const start = (module, options = {}) => {
 		uptimeMs: clock.now() - startedAt,
 		...abandonedAt === void 0 ? {} : { abandonedAt }
 	});
-	let healthChecks = [];
-	const health = () => runHealthChecks(healthChecks);
+	let monitor = healthMonitor([], clock);
+	const health = () => monitor.health();
+	const readiness = () => monitor.readiness();
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	const leaveStartup = () => {
@@ -773,6 +818,7 @@ const start = (module, options = {}) => {
 		hostname: probes.hostname,
 		live,
 		ready,
+		readiness,
 		health
 	}).tap((server) => {
 		probeBoundPort = server.port;
@@ -839,7 +885,7 @@ const start = (module, options = {}) => {
 		tracker.advanceTo("starting");
 		const runtime = ctx.get(RuntimePort);
 		runtimeName = runtime.name;
-		healthChecks = ctx.get(HealthChecks);
+		monitor = healthMonitor(ctx.get(HealthChecks), clock);
 		const runtimeCtx = ctx;
 		const rebuilt = rebuildGuard(runtime.name, root);
 		for (const unit of Object.values(runtime.units ?? {})) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,8 +45,8 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.45.0",
-    "@btravstack/di": "0.45.0",
+    "@btravstack/config": "0.46.0",
+    "@btravstack/di": "0.46.0",
     "@btravstack/tsconfig": "0.4.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
@@ -60,8 +60,8 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.45.0",
-    "@btravstack/di": "^0.45.0",
+    "@btravstack/config": "^0.46.0",
+    "@btravstack/di": "^0.46.0",
     "unthrown": "^5.0.0"
   },
   "engines": {