@btravstack/core 0.3.0

package/dist/index.mjs

@@ -0,0 +1,567 @@
+import { Err, Ok, OkAsync, P, TaggedError, fromSafePromise } from "unthrown";
+import { Module, Port, Provider } from "@btravstack/di";
+import { Config, ConfigInvalid, Env } from "@btravstack/config";
+import { createServer } from "node:http";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/clock.ts
+const systemClock = {
+	now: () => Date.now(),
+	sleep: (ms, signal) => fromSafePromise(new Promise((resolve) => {
+		if (signal?.aborted === true) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		timer.unref?.();
+		function onAbort() {
+			clearTimeout(timer);
+			resolve();
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	}))
+};
+//#endregion
+//#region src/events.ts
+const withErrors = (_key, value) => value instanceof Error ? {
+	name: value.name,
+	message: value.message,
+	stack: value.stack,
+	cause: value.cause
+} : value;
+const render = (event) => {
+	try {
+		return JSON.stringify(event, withErrors);
+	} catch {
+		return JSON.stringify({
+			type: event.type,
+			cause: "[unserialisable]"
+		});
+	}
+};
+const stderrSink = (event) => {
+	process.stderr.write(`${render(event)}\n`);
+};
+const safeSink = (sink) => (event) => {
+	try {
+		sink(event);
+	} catch {}
+};
+//#endregion
+//#region src/observability.ts
+/** The levels in order, least severe first — what `isEnabled` compares through. */
+const LEVELS = [
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+];
+/**
+* The application's logger, as a port — declared here and implemented in
+* `@btravstack/observability`, because a contract every package may depend on
+* has to be reachable without installing an implementation, and because the
+* correlation an implementation stamps per line is the kernel's own ambient
+* record.
+*
+* An implementation must not throw: a logger that throws turns an observability
+* problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
+* one deliberate exemption, since a lost line is not a modeled error.
+*/
+var Logger = class extends Port("Logger") {};
+/** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
+const SPAN_STATUS = {
+	unset: 0,
+	ok: 1,
+	error: 2
+};
+/**
+* The application's tracer, as a port — declared without naming OpenTelemetry,
+* because a port typed as a vendor's type points the dependency arrow outwards
+* and makes the whole family install that vendor.
+*/
+var Tracer = class extends Port("Tracer") {};
+/** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
+var Meter = class extends Port("Meter") {};
+//#endregion
+//#region src/runtime.ts
+var RuntimeStartFailed = class extends TaggedError("RuntimeStartFailed") {
+	message = `the ${this.runtime} runtime failed to start`;
+};
+/**
+* The port the kernel resolves its runtime from. A runtime is a **service the
+* module provides**, not an option handed to `start`: a runtime package
+* declares its own port over this one — `class HttpRuntime extends
+* RuntimePort<Runtime<never, HttpInfo>> {}` — so it is built by di like
+* everything else, and the kernel owns nothing but the lifecycle.
+*
+* Left generic on purpose: every runtime port is one id at runtime, since a
+* process boots exactly one, while each carries its own `Resolves`/`Info` in
+* the type.
+*/
+const RuntimePort = Port("Runtime");
+/**
+* `running`, but no later than the kernel's drain deadline — the primitive a
+* `Serving.drain` needs when the work it awaits settles on somebody else's
+* clock (Temporal's `shutdownForceTime`, a broker library's close) and so
+* cannot honour `signal` itself.
+*
+* **The losing branch's `Result` is dropped**, which is the point rather than
+* an oversight: once the deadline wins, the kernel has already moved on and
+* the eventual outcome has no consumer left. What that costs is the runtime's
+* own business — an un-acked AMQP delivery is redelivered, so abandoning one
+* repeats work rather than losing it, while a Temporal activity is retried on
+* another worker.
+*
+* Deliberately **`Clock`-agnostic**: there is no duration here, only a signal,
+* so it behaves identically under `@btravstack/testing`'s fake clock. Racing
+* work against a *timeout* is a different primitive and belongs on `Clock`
+* (`drain.ts` uses `clock.sleep` for exactly that, so a fake clock can control
+* it) — do not fold the two together.
+*/
+const releasedBy = (signal, running) => fromSafePromise(Promise.race([running, whenAborted(signal)])).flatMap((settled) => settled);
+const whenAborted = (signal) => signal.aborted ? OkAsync() : fromSafePromise(new Promise((resolve) => {
+	signal.addEventListener("abort", () => resolve(), { once: true });
+}));
+//#endregion
+//#region src/deferred.ts
+const createDeferred = () => {
+	let resolve;
+	return {
+		promise: new Promise((r) => {
+			resolve = r;
+		}),
+		resolve
+	};
+};
+//#endregion
+//#region src/drain.ts
+const drainApp = (args) => {
+	args.onUnready();
+	const inFlightAtStart = args.registry.inFlight();
+	const closedAtStart = args.registry.closed();
+	const deadline = new AbortController();
+	return args.clock.sleep(args.preDrainDelayMs, args.skip).flatMap(() => {
+		const drainStopped = args.serving.drain(deadline.signal);
+		return fromSafePromise(Promise.race([drainStopped.flatMap(() => args.registry.awaitIdle()), args.clock.sleep(args.drainTimeoutMs, args.skip)])).flatMap((raced) => {
+			deadline.abort();
+			return raced.map(() => {
+				const abandoned = args.registry.inFlight();
+				if (abandoned > 0) args.registry.abortAll();
+				return {
+					inFlightAtStart,
+					completed: args.registry.closed() - closedAtStart,
+					abandoned
+				};
+			});
+		});
+	});
+};
+//#endregion
+//#region src/phase.ts
+const ORDER = [
+	"building",
+	"starting",
+	"serving",
+	"draining",
+	"stopping",
+	"exited"
+];
+const rank = (phase) => ORDER.indexOf(phase);
+const createPhaseTracker = (onChange) => {
+	let phase = "building";
+	return {
+		current: () => phase,
+		advanceTo: (next) => {
+			if (rank(next) <= rank(phase)) return false;
+			phase = next;
+			onChange(next);
+			return true;
+		}
+	};
+};
+//#endregion
+//#region src/probes.ts
+const startProbeServer = (args) => fromSafePromise(new Promise((resolve) => {
+	const server = createServer((request, response) => {
+		if (request.url === "/livez") {
+			respond(response, args.live(), "ok");
+			return;
+		}
+		if (request.url === "/readyz") {
+			respond(response, args.ready(), "ready");
+			return;
+		}
+		response.writeHead(404).end();
+	});
+	const onBindError = (cause) => {
+		resolve(Err(new RuntimeStartFailed({
+			runtime: "probes",
+			cause
+		})));
+	};
+	const ignoreServingError = () => {};
+	server.once("error", onBindError);
+	try {
+		server.listen(args.port, "127.0.0.1", () => {
+			server.removeListener("error", onBindError);
+			server.on("error", ignoreServingError);
+			const address = server.address();
+			const port = typeof address === "object" && address !== null ? address.port : args.port;
+			resolve(Ok({
+				port,
+				close: () => fromSafePromise(new Promise((done) => server.close(() => done())))
+			}));
+		});
+	} catch (cause) {
+		onBindError(cause);
+	}
+	server.unref();
+})).flatMap((result) => result);
+const respond = (response, healthy, body) => {
+	if (healthy) {
+		response.writeHead(200).end(body);
+		return;
+	}
+	response.writeHead(503).end("unavailable");
+};
+//#endregion
+//#region src/process-handlers.ts
+const SIGNALS = ["SIGTERM", "SIGINT"];
+const installSignalHandlers = (handlers) => {
+	let seen = 0;
+	const onSignal = () => {
+		seen += 1;
+		if (seen === 1) {
+			handlers.onFirst();
+			return;
+		}
+		handlers.onSecond();
+	};
+	for (const signal of SIGNALS) process.on(signal, onSignal);
+	return () => {
+		for (const signal of SIGNALS) process.off(signal, onSignal);
+	};
+};
+const installUncaughtHandlers = (onUncaught) => {
+	let reported = false;
+	const report = (cause) => {
+		if (reported) return;
+		reported = true;
+		onUncaught(cause);
+	};
+	const onException = (error) => report(error);
+	const onRejection = (reason) => report(reason);
+	process.on("uncaughtException", onException);
+	process.on("unhandledRejection", onRejection);
+	return () => {
+		process.off("uncaughtException", onException);
+		process.off("unhandledRejection", onRejection);
+	};
+};
+//#endregion
+//#region src/units.ts
+const storage = new AsyncLocalStorage();
+const runWithUnit = (record, fn) => storage.run(record, fn);
+const currentUnit = () => storage.getStore();
+let counter = 0;
+const nextId = () => {
+	counter += 1;
+	return `u${counter}`;
+};
+const createUnitRegistry = () => {
+	const open = /* @__PURE__ */ new Set();
+	const idleWaiters = /* @__PURE__ */ new Set();
+	let closedCount = 0;
+	const settleIfIdle = () => {
+		if (open.size > 0) return;
+		for (const waiter of idleWaiters) waiter();
+		idleWaiters.clear();
+	};
+	return {
+		run: (meta, work) => {
+			const controller = new AbortController();
+			open.add(controller);
+			const record = {
+				unitId: nextId(),
+				traceId: meta.traceId ?? meta.id,
+				tenantId: meta.tenantId,
+				deadline: meta.deadline,
+				signal: controller.signal
+			};
+			return fromSafePromise(runWithUnit(record, async () => {
+				try {
+					return await work(controller.signal);
+				} finally {
+					open.delete(controller);
+					closedCount += 1;
+					settleIfIdle();
+				}
+			})).flatMap((result) => result);
+		},
+		inFlight: () => open.size,
+		closed: () => closedCount,
+		abortAll: () => {
+			for (const controller of open) controller.abort();
+		},
+		awaitIdle: () => open.size === 0 ? OkAsync() : fromSafePromise(new Promise((resolve) => {
+			idleWaiters.add(resolve);
+		}))
+	};
+};
+//#endregion
+//#region src/start.ts
+const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === Env.portId) || module.imports.some(providesEnv);
+const start = (module, options = {}) => {
+	const clock = options.clock ?? systemClock;
+	const env = options.env ?? process.env;
+	const emit = safeSink(options.onEvent ?? stderrSink);
+	let runtimeName = "";
+	let servingInfo = void 0;
+	let probeBoundPort = void 0;
+	const tracker = createPhaseTracker((phase) => {
+		if (phase === "serving") emit({
+			type: "serving",
+			runtime: runtimeName,
+			info: servingInfo,
+			probePort: probeBoundPort
+		});
+		if (phase === "stopping") emit({ type: "stopping" });
+		if (phase === "exited") emit({ type: "exited" });
+	});
+	const registry = createUnitRegistry();
+	const shutdown = createDeferred();
+	const teardownErrors = [];
+	const startedAt = clock.now();
+	const preDrainDelayMs = options.preDrainDelayMs ?? 5e3;
+	const drainTimeoutMs = options.drainTimeoutMs ?? 2e4;
+	const skipDrain = new AbortController();
+	let shutdownRequestedAt = startedAt;
+	let shutdownRequested = false;
+	const sinceShutdownRequested = () => clock.now() - shutdownRequestedAt;
+	const requestShutdown = (reason) => {
+		if (!shutdownRequested) {
+			shutdownRequested = true;
+			shutdownRequestedAt = clock.now();
+		}
+		shutdown.resolve(reason);
+	};
+	let forcedUnready = false;
+	const onUnready = () => {
+		forcedUnready = true;
+	};
+	const live = () => tracker.current() !== "exited";
+	const ready = () => tracker.current() === "serving" && !forcedUnready;
+	const disposeSignals = options.signals === false ? () => {} : installSignalHandlers({
+		onFirst: () => requestShutdown("signal"),
+		onSecond: () => skipDrain.abort()
+	});
+	const disposeUncaught = options.signals === false ? () => {} : installUncaughtHandlers((cause) => {
+		emit({
+			type: "uncaught",
+			cause
+		});
+		onUnready();
+		skipDrain.abort();
+		requestShutdown("uncaught");
+	});
+	let disposeProbes = () => {};
+	const probeBound = createDeferred();
+	const runtimePublished = createDeferred();
+	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);
+	if (options.probes === false) probeBound.resolve(void 0);
+	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? OkAsync() : startProbeServer({
+		port: probes.port,
+		live,
+		ready
+	}).tap((server) => {
+		probeBoundPort = server.port;
+		probeBound.resolve(server.port);
+		disposeProbes = () => {
+			server.close();
+		};
+	}).discard()).tapFailure((failure) => {
+		emit({
+			type: "startFailed",
+			cause: failure.tag === "Err" ? failure.error : failure.cause
+		});
+		probeBound.resolve(void 0);
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+		disposeSignals();
+		disposeUncaught();
+		tracker.advanceTo("exited");
+	});
+	const root = Module("Kernel")({
+		imports: providesEnv(module) ? [module] : [module, Module("Environment")({
+			provides: [Provider(Env)({ value: env })],
+			exports: [Env]
+		})],
+		exports: [module]
+	});
+	const runDrain = (serving) => {
+		tracker.advanceTo("draining");
+		emit({
+			type: "draining",
+			inFlight: registry.inFlight()
+		});
+		return drainApp({
+			serving,
+			registry,
+			clock,
+			preDrainDelayMs: Math.max(0, preDrainDelayMs - sinceShutdownRequested()),
+			drainTimeoutMs,
+			skip: skipDrain.signal,
+			onUnready
+		}).tap((report) => emit({
+			type: "drained",
+			report
+		}));
+	};
+	const finish = (serving, reason) => {
+		if (reason !== "signal") registry.abortAll();
+		return (reason === "signal" ? runDrain(serving) : OkAsync(void 0)).flatMap((report) => {
+			tracker.advanceTo("stopping");
+			return serving.stop().map(() => {
+				disposeSignals();
+				disposeUncaught();
+				tracker.advanceTo("exited");
+				disposeProbes();
+				return {
+					reason,
+					drain: report,
+					teardownErrors,
+					uptimeMs: clock.now() - startedAt
+				};
+			});
+		});
+	};
+	return {
+		exited: probesStarted.flatMap(() => Module.scoped(root, (ctx) => {
+			tracker.advanceTo("starting");
+			const runtime = ctx.get(RuntimePort);
+			runtimeName = runtime.name;
+			const runtimeCtx = ctx;
+			const unit = options.unit;
+			const run = (meta, work) => registry.run(meta, (signal) => {
+				if (unit === void 0) return work(runtimeCtx, signal);
+				const fork = Module.forkScope;
+				return fork(ctx, unit, (forked) => fromSafePromise((async () => await work(forked, signal))()).flatMap((result) => result), { onTeardownError: (port, cause) => emit({
+					type: "teardownError",
+					port,
+					cause
+				}) });
+			});
+			const host = {
+				ctx: runtimeCtx,
+				run
+			};
+			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
+			});
+			runtimePublished.resolve(void 0);
+			tracker.advanceTo("stopping");
+			disposeSignals();
+			disposeUncaught();
+			tracker.advanceTo("exited");
+			disposeProbes();
+		})),
+		stop: () => requestShutdown("runtimeStopped"),
+		requestDrain: () => requestShutdown("signal"),
+		phase: tracker.current,
+		ready,
+		probePort: () => fromSafePromise(probeBound.promise),
+		runtimeInfo: () => fromSafePromise(runtimePublished.promise)
+	};
+};
+//#endregion
+//#region src/run-main.ts
+const EX_SOFTWARE = 70;
+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;
+};
+/**
+* The exit-code half of `runMain`, on its own so the code table can be asserted
+* against hand-built reports without booting a kernel. Exported for
+* `run-main.spec.ts` only, not from `index.ts`.
+*/
+const awaitExit = async (app, exit) => {
+	exit((await app.exited).match({
+		ok: codeFor,
+		errCases: (matcher) => matcher.with(P._, (error) => isConfig(error) ? EX_CONFIG : 1),
+		defect: () => EX_SOFTWARE
+	}));
+};
+/**
+* Boot a module and turn its outcome into a process exit code — the front
+* door, and the one sanctioned place this package decides a process's fate.
+* `start` composed with the wait for `exited`: use `start` instead when the
+* `RunningApp` itself is wanted (a test, an embedder, a dev runner booting
+* two applications — none of which may claim `process.exitCode`).
+*
+* `exit` is injectable and defaults to setting `process.exitCode`: `runMain`
+* never calls `process.exit()`, so pending output is flushed, an embedding
+* host keeps control of its own lifetime, and a test can observe the code
+* without ending the run.
+*
+* | outcome | code |
+* | --- | --- |
+* | exited cleanly | `0` |
+* | startup failure (a modeled `Err`) | `1` |
+* | a configuration port that could not be bound (`ConfigInvalid`, `PROBE_PORT` included) | `78` |
+* | drained with work abandoned | `2` |
+* | exited with teardown errors | `2` |
+* | stopped by an uncaught exception or unhandled rejection | `70` |
+* | a defect | `70` |
+*
+* The two `70`s are the same statement reached through the two channels a bug
+* can take. A crash takes precedence over abandoned work.
+*
+* @example
+* ```ts
+* // `OrderApi` imports the application next to `http()` and exports
+* // `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
+* await runMain(OrderApi);
+* ```
+*/
+const runMain = async (module, options = {}, exit = (code) => {
+	process.exitCode = code;
+}) => {
+	await awaitExit(start(module, options), exit);
+};
+//#endregion
+export { LEVELS, Logger, Meter, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@btravstack/core",
+  "version": "0.3.0",
+  "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
+  "keywords": [
+    "application",
+    "bootstrap",
+    "dependency-injection",
+    "graceful-shutdown",
+    "kernel",
+    "lifecycle",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/tsconfig": "0.2.0",
+    "@types/node": "26.2.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.3.0",
+    "@btravstack/di": "0.3.0"
+  },
+  "peerDependencies": {
+    "unthrown": "^5.0.0",
+    "@btravstack/config": "^0.3.0",
+    "@btravstack/di": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.build.json",
+    "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"
+  }
+}