@btravstack/core 0.6.0 → 0.8.0

package/README.md

@@ -112,10 +112,13 @@ is a module that exports no runtime port at all.
 ## What you get
 
 - **A drain that survives Kubernetes.** On SIGTERM: readiness flips false, the
-  kernel waits `preDrainDelayMs` (default `5_000`) before telling the runtime
-  to stop accepting — endpoint removal is eventually consistent — then
-  in-flight work gets `drainTimeoutMs` (default `20_000`); whatever is still
-  open is aborted and reported `abandoned`. A second signal skips the drain.
+  kernel waits `preDrainDelayMs` (`PRE_DRAIN_DELAY_MS`, default `5_000`) before
+  telling the runtime to stop accepting — endpoint removal is eventually
+  consistent — then in-flight work gets `drainTimeoutMs` (`DRAIN_TIMEOUT_MS`,
+  default `20_000`); whatever is still open is aborted and reported
+  `abandoned`. A second signal skips the drain. Both timings have to agree with
+  the pod's `terminationGracePeriodSeconds`, which is why the deployment can
+  set them and the option only pins them.
 - **Probes from the state machine.** `GET /livez` and `GET /readyz` on
   `PROBE_PORT` (default `9000`), up before the graph is built.
 - **Configuration from the environment, typed.** The kernel provides

package/dist/index.cjs

@@ -38,18 +38,25 @@ var HealthChecks = class extends _btravstack_di.Port.many("HealthChecks") {};
 *
 * Each check's failure is recovered into a component line BEFORE `allAsync`
 * sees it, so a failing dependency cannot short-circuit the others: a report
-* naming one component is worth less than one naming all of them. What
-* survives to `allAsync`'s error channel is a `Defect` alone — a check that
-* threw rather than answered, which is a bug in the check.
+* naming one component is worth less than one naming all of them. A check
+* that throws rather than answers is a bug in the check, and it is folded in
+* too: each check is STARTED inside the pipeline, so a synchronous throw and
+* 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.
 */
-const runHealthChecks = (checks) => (0, unthrown.allAsync)(checks.map((health) => health.check().map(() => ({
+const runHealthChecks = (checks) => (0, unthrown.allAsync)(checks.map((health) => (0, unthrown.OkAsync)().flatMap(() => health.check()).map(() => ({
 	name: health.name,
 	status: "healthy"
 })).recoverErrCases((matcher) => matcher.with(unthrown.P.tag("HealthCheckFailed"), (error) => ({
 	name: health.name,
 	status: "unhealthy",
 	reason: error.reason
-}))))).map((components) => ({
+}))).recoverDefect((cause) => (0, unthrown.Ok)({
+	name: health.name,
+	status: "unhealthy",
+	reason: String(cause)
+})))).map((components) => ({
 	status: components.every((c) => c.status === "healthy") ? "healthy" : "unhealthy",
 	components
 }));
@@ -361,6 +368,37 @@ const createUnitRegistry = () => {
 //#endregion
 //#region src/start.ts
 const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === _btravstack_config.Env.portId) || module.imports.some(providesEnv);
+/**
+* What the kernel reads from the environment for itself. Each field is pinned
+* by the matching `StartOptions` field — explicit beats environment beats
+* default, per field, exactly as a starter's own configuration is.
+*/
+const KERNEL_DEFAULTS = {
+	probePort: 9e3,
+	preDrainDelayMs: 5e3,
+	drainTimeoutMs: 2e4
+};
+const readKernelConfig = (options, env) => {
+	const probePort = options.probes === void 0 ? void 0 : options.probes === false ? KERNEL_DEFAULTS.probePort : options.probes.port;
+	const result = _btravstack_config.Config.object({
+		probePort: _btravstack_config.Config.pinned(probePort, _btravstack_config.Config.port("PROBE_PORT", { default: KERNEL_DEFAULTS.probePort })),
+		preDrainDelayMs: _btravstack_config.Config.pinned(options.preDrainDelayMs, _btravstack_config.Config.integer("PRE_DRAIN_DELAY_MS", {
+			default: KERNEL_DEFAULTS.preDrainDelayMs,
+			min: 0
+		})),
+		drainTimeoutMs: _btravstack_config.Config.pinned(options.drainTimeoutMs, _btravstack_config.Config.integer("DRAIN_TIMEOUT_MS", {
+			default: KERNEL_DEFAULTS.drainTimeoutMs,
+			min: 0
+		}))
+	})["~standard"].validate(env);
+	return result.issues === void 0 ? (0, unthrown.Ok)(result.value) : (0, unthrown.Err)(new RuntimeStartFailed({
+		runtime: "kernel",
+		cause: new _btravstack_config.ConfigInvalid({
+			port: "kernel",
+			issues: result.issues
+		})
+	}));
+};
 const start = (module, options = {}) => {
 	const clock = options.clock ?? systemClock;
 	const env = options.env ?? process.env;
@@ -382,8 +420,8 @@ const start = (module, options = {}) => {
 	const shutdown = Promise.withResolvers();
 	const teardownErrors = [];
 	const startedAt = clock.now();
-	const preDrainDelayMs = options.preDrainDelayMs ?? 5e3;
-	const drainTimeoutMs = options.drainTimeoutMs ?? 2e4;
+	const kernelConfig = readKernelConfig(options, env);
+	const { preDrainDelayMs, drainTimeoutMs } = kernelConfig.getOrElse(() => KERNEL_DEFAULTS);
 	const skipDrain = new AbortController();
 	let shutdownRequestedAt = startedAt;
 	let shutdownRequested = false;
@@ -420,16 +458,7 @@ const start = (module, options = {}) => {
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	emit({ type: "building" });
-	const probesOptions = options.probes === void 0 ? _btravstack_config.Config.port("PROBE_PORT", { default: 9e3 }).parse(env["PROBE_PORT"]).map((port) => ({ port })).mapErrCases((matcher) => matcher.with(unthrown.P.tag("ConfigFieldInvalid"), ({ reason }) => new RuntimeStartFailed({
-		runtime: "probes",
-		cause: new _btravstack_config.ConfigInvalid({
-			port: "probes",
-			issues: [{
-				message: reason,
-				path: ["PROBE_PORT"]
-			}]
-		})
-	}))) : (0, unthrown.Ok)(options.probes);
+	const probesOptions = kernelConfig.map(({ probePort }) => options.probes === false ? false : { port: probePort });
 	if (options.probes === false) probeBound.resolve(void 0);
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? (0, unthrown.OkAsync)() : startProbeServer({
 		port: probes.port,

package/dist/index.d.cts

@@ -74,9 +74,12 @@ type HealthReport = {
  *
  * Each check's failure is recovered into a component line BEFORE `allAsync`
  * sees it, so a failing dependency cannot short-circuit the others: a report
- * naming one component is worth less than one naming all of them. What
- * survives to `allAsync`'s error channel is a `Defect` alone — a check that
- * threw rather than answered, which is a bug in the check.
+ * naming one component is worth less than one naming all of them. A check
+ * that throws rather than answers is a bug in the check, and it is folded in
+ * too: each check is STARTED inside the pipeline, so a synchronous throw and
+ * 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.
  */
 declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
 //#endregion
@@ -439,9 +442,11 @@ type StartOptions<UnitX = never, UnitNeeds = never> = {
    */
   readonly env?: Environment;
   /**
-   * A module forked around **every unit**: built as the unit opens, torn down
-   * as it closes — while the unit's ambient record is still open — reading
-   * anything the application context carries.
+   * A module forked around **every unit** — a unit being one bounded piece of
+   * work, whatever the transport calls it: an HTTP request, a Temporal
+   * activity, an AMQP delivery. Built as the unit opens, torn down as it
+   * closes — while the unit's ambient record is still open — reading anything
+   * the application context carries.
    *
    * A failing unit finaliser is reported as a `teardownError` event and never
    * in `ExitReport.teardownErrors`. With this option the unit's work runs only
@@ -458,7 +463,21 @@ type StartOptions<UnitX = never, UnitNeeds = never> = {
   readonly probes?: {
     readonly port: number;
   } | false;
+  /**
+   * How long readiness stays false before the runtime is told to stop
+   * accepting. Unset, it is bound from `PRE_DRAIN_DELAY_MS` in `env` (default
+   * `5_000`) — the window that covers Kubernetes' eventually-consistent
+   * endpoint removal, which is a property of the cluster rather than of the
+   * code, so a deployment must be able to set it.
+   */
   readonly preDrainDelayMs?: number;
+  /**
+   * How long in-flight work gets before it is aborted and reported
+   * `abandoned`. Unset, it is bound from `DRAIN_TIMEOUT_MS` in `env` (default
+   * `20_000`). Keep it under the pod's `terminationGracePeriodSeconds`, which
+   * is the reason this one belongs in the environment: the two are set
+   * together, in the same manifest.
+   */
   readonly drainTimeoutMs?: number;
   readonly onEvent?: EventSink;
 };

package/dist/index.d.mts

@@ -74,9 +74,12 @@ type HealthReport = {
  *
  * Each check's failure is recovered into a component line BEFORE `allAsync`
  * sees it, so a failing dependency cannot short-circuit the others: a report
- * naming one component is worth less than one naming all of them. What
- * survives to `allAsync`'s error channel is a `Defect` alone — a check that
- * threw rather than answered, which is a bug in the check.
+ * naming one component is worth less than one naming all of them. A check
+ * that throws rather than answers is a bug in the check, and it is folded in
+ * too: each check is STARTED inside the pipeline, so a synchronous throw and
+ * 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.
  */
 declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
 //#endregion
@@ -439,9 +442,11 @@ type StartOptions<UnitX = never, UnitNeeds = never> = {
    */
   readonly env?: Environment;
   /**
-   * A module forked around **every unit**: built as the unit opens, torn down
-   * as it closes — while the unit's ambient record is still open — reading
-   * anything the application context carries.
+   * A module forked around **every unit** — a unit being one bounded piece of
+   * work, whatever the transport calls it: an HTTP request, a Temporal
+   * activity, an AMQP delivery. Built as the unit opens, torn down as it
+   * closes — while the unit's ambient record is still open — reading anything
+   * the application context carries.
    *
    * A failing unit finaliser is reported as a `teardownError` event and never
    * in `ExitReport.teardownErrors`. With this option the unit's work runs only
@@ -458,7 +463,21 @@ type StartOptions<UnitX = never, UnitNeeds = never> = {
   readonly probes?: {
     readonly port: number;
   } | false;
+  /**
+   * How long readiness stays false before the runtime is told to stop
+   * accepting. Unset, it is bound from `PRE_DRAIN_DELAY_MS` in `env` (default
+   * `5_000`) — the window that covers Kubernetes' eventually-consistent
+   * endpoint removal, which is a property of the cluster rather than of the
+   * code, so a deployment must be able to set it.
+   */
   readonly preDrainDelayMs?: number;
+  /**
+   * How long in-flight work gets before it is aborted and reported
+   * `abandoned`. Unset, it is bound from `DRAIN_TIMEOUT_MS` in `env` (default
+   * `20_000`). Keep it under the pod's `terminationGracePeriodSeconds`, which
+   * is the reason this one belongs in the environment: the two are set
+   * together, in the same manifest.
+   */
   readonly drainTimeoutMs?: number;
   readonly onEvent?: EventSink;
 };

package/dist/index.mjs

@@ -37,18 +37,25 @@ var HealthChecks = class extends Port.many("HealthChecks") {};
 *
 * Each check's failure is recovered into a component line BEFORE `allAsync`
 * sees it, so a failing dependency cannot short-circuit the others: a report
-* naming one component is worth less than one naming all of them. What
-* survives to `allAsync`'s error channel is a `Defect` alone — a check that
-* threw rather than answered, which is a bug in the check.
+* naming one component is worth less than one naming all of them. A check
+* that throws rather than answers is a bug in the check, and it is folded in
+* too: each check is STARTED inside the pipeline, so a synchronous throw and
+* 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.
 */
-const runHealthChecks = (checks) => allAsync(checks.map((health) => health.check().map(() => ({
+const runHealthChecks = (checks) => allAsync(checks.map((health) => OkAsync().flatMap(() => health.check()).map(() => ({
 	name: health.name,
 	status: "healthy"
 })).recoverErrCases((matcher) => matcher.with(P.tag("HealthCheckFailed"), (error) => ({
 	name: health.name,
 	status: "unhealthy",
 	reason: error.reason
-}))))).map((components) => ({
+}))).recoverDefect((cause) => Ok({
+	name: health.name,
+	status: "unhealthy",
+	reason: String(cause)
+})))).map((components) => ({
 	status: components.every((c) => c.status === "healthy") ? "healthy" : "unhealthy",
 	components
 }));
@@ -360,6 +367,37 @@ const createUnitRegistry = () => {
 //#endregion
 //#region src/start.ts
 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
+* by the matching `StartOptions` field — explicit beats environment beats
+* default, per field, exactly as a starter's own configuration is.
+*/
+const KERNEL_DEFAULTS = {
+	probePort: 9e3,
+	preDrainDelayMs: 5e3,
+	drainTimeoutMs: 2e4
+};
+const readKernelConfig = (options, env) => {
+	const probePort = options.probes === void 0 ? void 0 : options.probes === false ? KERNEL_DEFAULTS.probePort : options.probes.port;
+	const result = Config.object({
+		probePort: Config.pinned(probePort, Config.port("PROBE_PORT", { default: KERNEL_DEFAULTS.probePort })),
+		preDrainDelayMs: Config.pinned(options.preDrainDelayMs, Config.integer("PRE_DRAIN_DELAY_MS", {
+			default: KERNEL_DEFAULTS.preDrainDelayMs,
+			min: 0
+		})),
+		drainTimeoutMs: Config.pinned(options.drainTimeoutMs, Config.integer("DRAIN_TIMEOUT_MS", {
+			default: KERNEL_DEFAULTS.drainTimeoutMs,
+			min: 0
+		}))
+	})["~standard"].validate(env);
+	return result.issues === void 0 ? Ok(result.value) : Err(new RuntimeStartFailed({
+		runtime: "kernel",
+		cause: new ConfigInvalid({
+			port: "kernel",
+			issues: result.issues
+		})
+	}));
+};
 const start = (module, options = {}) => {
 	const clock = options.clock ?? systemClock;
 	const env = options.env ?? process.env;
@@ -381,8 +419,8 @@ const start = (module, options = {}) => {
 	const shutdown = Promise.withResolvers();
 	const teardownErrors = [];
 	const startedAt = clock.now();
-	const preDrainDelayMs = options.preDrainDelayMs ?? 5e3;
-	const drainTimeoutMs = options.drainTimeoutMs ?? 2e4;
+	const kernelConfig = readKernelConfig(options, env);
+	const { preDrainDelayMs, drainTimeoutMs } = kernelConfig.getOrElse(() => KERNEL_DEFAULTS);
 	const skipDrain = new AbortController();
 	let shutdownRequestedAt = startedAt;
 	let shutdownRequested = false;
@@ -419,16 +457,7 @@ const start = (module, options = {}) => {
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	emit({ type: "building" });
-	const probesOptions = options.probes === void 0 ? Config.port("PROBE_PORT", { default: 9e3 }).parse(env["PROBE_PORT"]).map((port) => ({ port })).mapErrCases((matcher) => matcher.with(P.tag("ConfigFieldInvalid"), ({ reason }) => new RuntimeStartFailed({
-		runtime: "probes",
-		cause: new ConfigInvalid({
-			port: "probes",
-			issues: [{
-				message: reason,
-				path: ["PROBE_PORT"]
-			}]
-		})
-	}))) : Ok(options.probes);
+	const probesOptions = kernelConfig.map(({ probePort }) => options.probes === false ? false : { port: probePort });
 	if (options.probes === false) probeBound.resolve(void 0);
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? OkAsync() : startProbeServer({
 		port: probes.port,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -46,20 +46,20 @@
   },
   "devDependencies": {
     "@btravstack/tsconfig": "0.2.0",
-    "@types/node": "26.2.0",
+    "@types/node": "26.4.0",
     "@unthrown/vitest": "5.7.0",
     "@vitest/coverage-v8": "4.1.11",
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.6.0",
-    "@btravstack/di": "0.6.0"
+    "@btravstack/config": "0.8.0",
+    "@btravstack/di": "0.8.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.6.0",
-    "@btravstack/di": "^0.6.0"
+    "@btravstack/config": "^0.8.0",
+    "@btravstack/di": "^0.8.0"
   },
   "engines": {
     "node": ">=22"