@btravstack/core 0.6.0 → 0.7.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

@@ -361,6 +361,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 +413,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 +451,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

@@ -458,7 +458,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

@@ -458,7 +458,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

@@ -360,6 +360,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 +412,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 +450,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.7.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -53,13 +53,13 @@
     "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.7.0",
+    "@btravstack/di": "0.7.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.6.0",
-    "@btravstack/di": "^0.6.0"
+    "@btravstack/config": "^0.7.0",
+    "@btravstack/di": "^0.7.0"
   },
   "engines": {
     "node": ">=22"