@btravstack/core 0.14.0 → 0.15.0

package/dist/index.mjs

@@ -32,6 +32,26 @@ var HealthCheckFailed = class extends TaggedError("HealthCheckFailed") {};
 */
 var HealthChecks = class extends Port.many("HealthChecks") {};
 /**
+* A check that never settles, bounded. `unref`'d, so a pending probe is never
+* the reason a process stays alive, and cleared on the winning branch so a
+* slow-but-answering check leaves no timer behind.
+*
+* It bounds the WAIT, not the check: nothing here can cancel whatever the check
+* is blocked on. That is the same bargain the drain and the stop deadline make,
+* and it is why this reports rather than recovers.
+*/
+const answeringWithin = (health, ms) => {
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(Err(new HealthCheckFailed({ reason: `did not answer within ${String(ms)} ms` }))), ms);
+		timer.unref();
+	});
+	const answering = OkAsync().flatMap(() => health.check());
+	return fromSafePromise(Promise.race([answering, timeout]).finally(() => {
+		clearTimeout(timer);
+	})).flatMap((settled) => settled);
+};
+/**
 * Runs every check and folds the results into one report — the whole app is
 * unhealthy if any single component is.
 *
@@ -43,8 +63,15 @@ var HealthChecks = class extends Port.many("HealthChecks") {};
 * a defecting `AsyncResult` alike are recovered into an unhealthy line —
 * escaped, the first would reach the kernel's own `uncaughtException` handler
 * and the second would leave `/healthz` hanging with nothing written.
+*
+* **A check that never settles is the third case, and it needed a deadline
+* rather than a recovery.** Neither recovery above can see one: there is no
+* error and no defect, only silence, so `/healthz` held a socket open per hit
+* while kubelet timed out against a report that named nothing. Each check now
+* races {@link HealthOptions.timeoutMs}, and the component that hung is named
+* in the report like any other unhealthy one.
 */
-const runHealthChecks = (checks) => allAsync(checks.map((health) => OkAsync().flatMap(() => health.check()).map(() => ({
+const runHealthChecks = (checks, options = {}) => allAsync(checks.map((health) => answeringWithin(health, health.timeoutMs ?? options.timeoutMs ?? 800).map(() => ({
 	name: health.name,
 	status: "healthy"
 })).recoverErrCases((matcher) => matcher.with(P.tag("HealthCheckFailed"), (error) => ({
@@ -103,6 +130,24 @@ const observe = (observers, operation) => {
 		for (const settle of settlers) settle(settled);
 	};
 };
+/**
+* {@link observe}, wrapped around one call: every observer is started before
+* `call` runs and settled from whichever channel it comes back on — `ok` on
+* success, `error` carrying the `Err` or the defect as `cause` otherwise. The
+* wrapper is transparent to the `Result`: whatever `call` answers is what the
+* caller receives.
+*
+* `settled` replaces either default where a starter has more to say: `ok`
+* receives the value (a cache reports a hit or a miss), `failure` the
+* `FailureView` (a store reports a missing object as an ordinary answer).
+*/
+const observed = (observers, operation, call, settled = {}) => {
+	const settle = observe(observers, operation);
+	return call().tap((value) => settle(settled.ok?.(value) ?? { outcome: "ok" })).tapFailure((failure) => settle(settled.failure?.(failure) ?? {
+		outcome: "error",
+		cause: failure.tag === "Err" ? failure.error : failure.cause
+	}));
+};
 //#endregion
 //#region src/clock.ts
 const systemClock = {
@@ -335,7 +380,7 @@ const startProbeServer = (args) => fromSafePromise(new Promise((resolve) => {
 	const ignoreServingError = () => {};
 	server.once("error", onBindError);
 	try {
-		server.listen(args.port, "127.0.0.1", () => {
+		server.listen(args.port, args.hostname, () => {
 			server.removeListener("error", onBindError);
 			server.on("error", ignoreServingError);
 			const address = server.address();
@@ -442,6 +487,13 @@ const createUnitRegistry = () => {
 };
 //#endregion
 //#region src/start.ts
+/**
+* An arm of a race that has lost and has nothing to report: it never settles,
+* so the winner decides. It holds no timer and no handle, which is what makes
+* it safe — the alternative is an arm that answers a report no consumer reads,
+* and whose side effects then have to be guarded one by one.
+*/
+const withdrawn = () => fromSafePromise(new Promise(() => {}));
 const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === Env.portId) || module.imports.some(providesEnv);
 /**
 * What the kernel reads from the environment for itself. Each field is pinned
@@ -450,13 +502,21 @@ const providesEnv = (module) => module.provides.some((provider) => provider.port
 */
 const KERNEL_DEFAULTS = {
 	probePort: 9e3,
+	probeHost: "0.0.0.0",
 	preDrainDelayMs: 5e3,
-	drainTimeoutMs: 2e4
+	drainTimeoutMs: 2e4,
+	stopTimeoutMs: 5e3
 };
 const readKernelConfig = (options, env) => {
-	const probePort = options.probes === void 0 ? void 0 : options.probes === false ? KERNEL_DEFAULTS.probePort : options.probes.port;
+	const probes = options.probes === false ? {
+		port: KERNEL_DEFAULTS.probePort,
+		host: KERNEL_DEFAULTS.probeHost
+	} : options.probes;
+	const probePort = probes?.port;
+	const probeHost = probes?.host;
 	const result = Config.object({
 		probePort: Config.pinned(probePort, Config.port("PROBE_PORT", { default: KERNEL_DEFAULTS.probePort })),
+		probeHost: Config.pinned(probeHost, Config.string("PROBE_HOST", { default: KERNEL_DEFAULTS.probeHost })),
 		preDrainDelayMs: Config.pinned(options.preDrainDelayMs, Config.integer("PRE_DRAIN_DELAY_MS", {
 			default: KERNEL_DEFAULTS.preDrainDelayMs,
 			min: 0
@@ -464,6 +524,10 @@ const readKernelConfig = (options, env) => {
 		drainTimeoutMs: Config.pinned(options.drainTimeoutMs, Config.integer("DRAIN_TIMEOUT_MS", {
 			default: KERNEL_DEFAULTS.drainTimeoutMs,
 			min: 0
+		})),
+		stopTimeoutMs: Config.pinned(options.stopTimeoutMs, Config.integer("STOP_TIMEOUT_MS", {
+			default: KERNEL_DEFAULTS.stopTimeoutMs,
+			min: 0
 		}))
 	})["~standard"].validate(env);
 	return result.issues === void 0 ? Ok(result.value) : Err(new RuntimeStartFailed({
@@ -496,8 +560,14 @@ const start = (module, options = {}) => {
 	const teardownErrors = [];
 	const startedAt = clock.now();
 	const kernelConfig = readKernelConfig(options, env);
-	const { preDrainDelayMs, drainTimeoutMs } = kernelConfig.getOrElse(() => KERNEL_DEFAULTS);
+	const { preDrainDelayMs, drainTimeoutMs, stopTimeoutMs } = kernelConfig.getOrElse(() => KERNEL_DEFAULTS);
 	const skipDrain = new AbortController();
+	const stopSettled = new AbortController();
+	let lifecycleSettled = false;
+	const onLifecycleSettled = () => {
+		lifecycleSettled = true;
+		stopSettled.abort();
+	};
 	let shutdownRequestedAt = startedAt;
 	let shutdownRequested = false;
 	const sinceShutdownRequested = () => clock.now() - shutdownRequestedAt;
@@ -516,7 +586,11 @@ const start = (module, options = {}) => {
 	const ready = () => tracker.current() === "serving" && !forcedUnready;
 	const disposeSignals = options.signals === false ? () => {} : installSignalHandlers({
 		onFirst: () => requestShutdown("signal"),
-		onSecond: () => skipDrain.abort()
+		onSecond: () => {
+			skipDrain.abort();
+			stopSettled.abort();
+			abandonBuild("signal");
+		}
 	});
 	const disposeUncaught = options.signals === false ? () => {} : installUncaughtHandlers((cause) => {
 		emit({
@@ -526,17 +600,63 @@ const start = (module, options = {}) => {
 		onUnready();
 		skipDrain.abort();
 		requestShutdown("uncaught");
+		abandonBuild("uncaught");
 	});
 	let disposeProbes = () => {};
+	const disposeAll = () => {
+		disposeSignals();
+		disposeUncaught();
+		tracker.advanceTo("exited");
+		disposeProbes();
+	};
+	const reportOf = (reason, drain, abandonedAt) => ({
+		reason,
+		drain,
+		teardownErrors,
+		uptimeMs: clock.now() - startedAt,
+		...abandonedAt === void 0 ? {} : { abandonedAt }
+	});
 	let healthChecks = [];
 	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
+	const stopping = Promise.withResolvers();
+	const stopAbandoned = () => fromSafePromise(stopping.promise).flatMap(({ reason, drain }) => clock.sleep(stopTimeoutMs, stopSettled.signal).flatMap(() => lifecycleSettled ? withdrawn() : OkAsync(abandonStop(reason, drain))));
+	const abandonStop = (reason, drain) => {
+		emit({
+			type: "stoppedWaiting",
+			phase: "stop",
+			afterMs: stopSettled.signal.aborted ? void 0 : stopTimeoutMs
+		});
+		disposeAll();
+		return reportOf(reason, drain, "stop");
+	};
+	const abandoningBuild = Promise.withResolvers();
+	const buildAbandoned = () => fromSafePromise(abandoningBuild.promise).map((reason) => {
+		emit({
+			type: "stoppedWaiting",
+			phase: "build",
+			afterMs: void 0
+		});
+		registry.abortAll();
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+		disposeAll();
+		return reportOf(reason, void 0, "build");
+	});
+	const abandonBuild = (reason) => {
+		const phase = tracker.current();
+		if (phase === "building" || phase === "starting") abandoningBuild.resolve(reason);
+	};
 	emit({ type: "building" });
-	const probesOptions = kernelConfig.map(({ probePort }) => options.probes === false ? false : { port: probePort });
+	const probesOptions = kernelConfig.map(({ probePort, probeHost }) => options.probes === false ? false : {
+		port: probePort,
+		hostname: probeHost
+	});
 	if (options.probes === false) probeBound.resolve(void 0);
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? OkAsync() : startProbeServer({
 		port: probes.port,
+		hostname: probes.hostname,
 		live,
 		ready,
 		health
@@ -591,97 +711,98 @@ const start = (module, options = {}) => {
 		if (reason !== "signal") registry.abortAll();
 		return (reason === "signal" ? runDrain(serving) : OkAsync(void 0)).flatMap((report) => {
 			tracker.advanceTo("stopping");
+			stopping.resolve({
+				reason,
+				drain: report
+			});
 			return serving.stop().map(() => {
-				disposeSignals();
-				disposeUncaught();
-				tracker.advanceTo("exited");
-				disposeProbes();
-				return {
-					reason,
-					drain: report,
-					teardownErrors,
-					uptimeMs: clock.now() - startedAt
-				};
+				disposeAll();
+				return reportOf(reason, report);
 			});
 		});
 	};
-	return {
-		exited: probesStarted.flatMap(() => Module.scoped(root, (ctx) => {
-			tracker.advanceTo("starting");
-			const runtime = ctx.get(RuntimePort);
-			runtimeName = runtime.name;
-			healthChecks = ctx.get(HealthChecks);
-			const runtimeCtx = ctx;
-			const run = (meta, work) => registry.run(meta, (signal) => {
-				const settled = Promise.withResolvers();
-				let closing;
-				let hasSettled = false;
-				const fork = (module, seed) => {
-					if (hasSettled) return fromSafePromise(Promise.reject(/* @__PURE__ */ new Error("a unit forks after it has already settled")));
-					if (closing !== void 0) return fromSafePromise(Promise.reject(/* @__PURE__ */ new Error("a unit forks its scope once")));
-					const ready = Promise.withResolvers();
-					closing = Module.forkScope(ctx, module, (forked) => {
-						ready.resolve(forked);
-						return fromSafePromise(settled.promise);
-					}, {
-						seed,
-						onTeardownError: (port, cause) => emit({
-							type: "teardownError",
-							port,
-							cause
-						})
-					}).recoverDefect((cause) => {
-						ready.reject(cause);
-						return Ok();
-					}).get();
-					return fromSafePromise(ready.promise);
-				};
-				const outcome = (async () => {
-					try {
-						return await work({
-							ctx: runtimeCtx,
-							fork
-						}, signal);
-					} finally {
-						hasSettled = true;
-						settled.resolve();
-						if (closing !== void 0) await closing;
-					}
-				})();
-				return fromSafePromise(outcome).flatMap((result) => result);
-			});
-			const host = {
-				ctx: runtimeCtx,
-				run
+	const built = () => Module.scoped(root, (ctx) => {
+		tracker.advanceTo("starting");
+		const runtime = ctx.get(RuntimePort);
+		runtimeName = runtime.name;
+		healthChecks = ctx.get(HealthChecks);
+		const runtimeCtx = ctx;
+		const run = (meta, work) => registry.run(meta, (signal) => {
+			const settled = Promise.withResolvers();
+			let closing;
+			let hasSettled = false;
+			const fork = (module, seed) => {
+				if (hasSettled) return fromSafePromise(Promise.reject(/* @__PURE__ */ new Error("a unit forks after it has already settled")));
+				if (closing !== void 0) return fromSafePromise(Promise.reject(/* @__PURE__ */ new Error("a unit forks its scope once")));
+				const ready = Promise.withResolvers();
+				closing = Module.forkScope(ctx, module, (forked) => {
+					ready.resolve(forked);
+					return fromSafePromise(settled.promise);
+				}, {
+					seed,
+					onTeardownError: (port, cause) => emit({
+						type: "teardownError",
+						port,
+						cause
+					})
+				}).recoverDefect((cause) => {
+					ready.reject(cause);
+					return Ok();
+				}).get();
+				return fromSafePromise(ready.promise);
 			};
-			return runtime.start(host).flatMap((serving) => {
-				servingInfo = serving.info;
-				tracker.advanceTo("serving");
-				runtimePublished.resolve(serving.info);
-				return fromSafePromise(shutdown.promise).flatMap((reason) => finish(serving, reason));
-			});
-		}, { onTeardownError: (port, cause) => {
-			teardownErrors.push({
-				port,
-				cause
-			});
-			emit({
-				type: "teardownError",
-				port,
-				cause
-			});
-		} }).tapFailure((failure) => {
-			if (tracker.current() !== "stopping") emit({
-				type: "startFailed",
-				cause: failure.tag === "Err" ? failure.error : failure.cause
+			const outcome = (async () => {
+				try {
+					return await work({
+						ctx: runtimeCtx,
+						fork
+					}, signal);
+				} finally {
+					hasSettled = true;
+					settled.resolve();
+					if (closing !== void 0) await closing;
+				}
+			})();
+			return fromSafePromise(outcome).flatMap((result) => result);
+		});
+		const host = {
+			ctx: runtimeCtx,
+			run
+		};
+		return runtime.start(host).flatMap((serving) => {
+			servingInfo = serving.info;
+			tracker.advanceTo("serving");
+			runtimePublished.resolve(serving.info);
+			serving.stopped?.().map(() => {
+				requestShutdown("runtimeStopped");
 			});
-			runtimePublished.resolve(void 0);
-			tracker.advanceTo("stopping");
-			disposeSignals();
-			disposeUncaught();
-			tracker.advanceTo("exited");
-			disposeProbes();
-		})),
+			return fromSafePromise(shutdown.promise).flatMap((reason) => finish(serving, reason));
+		});
+	}, { onTeardownError: (port, cause) => {
+		teardownErrors.push({
+			port,
+			cause
+		});
+		emit({
+			type: "teardownError",
+			port,
+			cause
+		});
+	} }).tapFailure((failure) => {
+		if (tracker.current() !== "stopping") emit({
+			type: "startFailed",
+			cause: failure.tag === "Err" ? failure.error : failure.cause
+		});
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+		disposeAll();
+	}).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
+	return {
+		exited: probesStarted.flatMap(() => fromSafePromise(Promise.race([
+			built(),
+			stopAbandoned(),
+			buildAbandoned()
+		])).flatMap((settled) => settled)),
 		stop: () => requestShutdown("runtimeStopped"),
 		requestDrain: () => requestShutdown("signal"),
 		phase: tracker.current,
@@ -697,7 +818,7 @@ const EX_CONFIG = 78;
 const isConfig = (error) => error instanceof ConfigInvalid || error instanceof RuntimeStartFailed && error.cause instanceof ConfigInvalid;
 const codeFor = (report) => {
 	if (report.reason === "uncaught") return EX_SOFTWARE;
-	return (report.drain?.abandoned ?? 0) > 0 || report.teardownErrors.length > 0 ? 2 : 0;
+	return (report.drain?.abandoned ?? 0) > 0 || report.teardownErrors.length > 0 || report.abandonedAt !== void 0 ? 2 : 0;
 };
 /**
 * The exit-code half of `runMain`, on its own so the code table can be asserted
@@ -730,6 +851,7 @@ const awaitExit = async (app, exit) => {
 * | a configuration port that could not be bound (`ConfigInvalid`, `PROBE_PORT` included) | `78` |
 * | drained with work abandoned | `2` |
 * | exited with teardown errors | `2` |
+* | stopped waiting for the teardown or a build (`ExitReport.abandonedAt`) | `2` |
 * | stopped by an uncaught exception or unhandled rejection | `70` |
 * | a defect | `70` |
 *
@@ -749,4 +871,4 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
-export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, noObserver, observe, observed, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,6 +45,8 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
+    "@btravstack/config": "0.15.0",
+    "@btravstack/di": "0.15.0",
     "@btravstack/tsconfig": "0.4.0",
     "@types/node": "26.4.1",
     "@unthrown/vitest": "5.8.0",
@@ -52,14 +54,12 @@
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
     "unthrown": "5.8.0",
-    "vitest": "4.1.11",
-    "@btravstack/config": "0.14.0",
-    "@btravstack/di": "0.14.0"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
-    "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.14.0",
-    "@btravstack/di": "^0.14.0"
+    "@btravstack/config": "^0.15.0",
+    "@btravstack/di": "^0.15.0",
+    "unthrown": "^5.0.0"
   },
   "engines": {
     "node": ">=22"
@@ -69,7 +69,6 @@
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch --tsconfig tsconfig.build.json",
     "generate": "node ../../docs/scripts/extract-doc-samples.ts --group core --out src/generated/doc-samples",
     "test": "vitest run --coverage",
-    "test:types": "tsc --noEmit -p tsconfig.test-d.json",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
   }
 }