@btravstack/core 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -1,9 +1,59 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let unthrown = require("unthrown");
 let _btravstack_di = require("@btravstack/di");
+let unthrown = require("unthrown");
 let _btravstack_config = require("@btravstack/config");
 let node_http = require("node:http");
 let node_async_hooks = require("node:async_hooks");
+//#region src/instrumentation.ts
+/**
+* The set port a package contributes its instrumentation to.
+*
+* Nothing collects it unless an OTel SDK is composed, which is the point: a
+* starter DECLARES what it can instrument, and composing
+* `@btravstack/observability/otel` is what turns the declarations on. A graph
+* without it registers nothing and pays nothing — the Spring Boot starter
+* shape, in one port.
+*/
+var Instrumentations = class extends _btravstack_di.Port.many("Instrumentations") {};
+//#endregion
+//#region src/health.ts
+/**
+* A component could not answer for itself. Modeled rather than thrown, because
+* a health check that throws is a bug in the check; one that fails is the news
+* `/healthz` exists to carry.
+*/
+var HealthCheckFailed = class extends (0, unthrown.TaggedError)("HealthCheckFailed") {};
+/**
+* The set port every starter contributes to and the kernel reads whole.
+*
+* A set port rather than a registry the kernel hands out: a starter DECLARES
+* its check the same way it declares anything else, and a starter an
+* application never composed contributes nothing — no registration call to
+* forget, and no order to get wrong.
+*/
+var HealthChecks = class extends _btravstack_di.Port.many("HealthChecks") {};
+/**
+* Runs every check and folds the results into one report — the whole app is
+* unhealthy if any single component is.
+*
+* 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.
+*/
+const runHealthChecks = (checks) => (0, unthrown.allAsync)(checks.map((health) => 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) => ({
+	status: components.every((c) => c.status === "healthy") ? "healthy" : "unhealthy",
+	components
+}));
+//#endregion
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
@@ -185,6 +235,12 @@ const startProbeServer = (args) => (0, unthrown.fromSafePromise)(new Promise((re
 			respond(response, args.ready(), "ready");
 			return;
 		}
+		if (request.url === "/healthz") {
+			args.health().map((report) => {
+				response.writeHead(report.status === "healthy" ? 200 : 503, { "content-type": "application/json" }).end(JSON.stringify(report));
+			});
+			return;
+		}
 		response.writeHead(404).end();
 	});
 	const onBindError = (cause) => {
@@ -359,6 +415,8 @@ const start = (module, options = {}) => {
 		requestShutdown("uncaught");
 	});
 	let disposeProbes = () => {};
+	let healthChecks = [];
+	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	emit({ type: "building" });
@@ -376,7 +434,8 @@ const start = (module, options = {}) => {
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? (0, unthrown.OkAsync)() : startProbeServer({
 		port: probes.port,
 		live,
-		ready
+		ready,
+		health
 	}).tap((server) => {
 		probeBoundPort = server.port;
 		probeBound.resolve(server.port);
@@ -444,6 +503,7 @@ const start = (module, options = {}) => {
 			tracker.advanceTo("starting");
 			const runtime = ctx.get(RuntimePort);
 			runtimeName = runtime.name;
+			healthChecks = ctx.get(HealthChecks);
 			const runtimeCtx = ctx;
 			const unit = options.unit;
 			const run = (meta, work) => registry.run(meta, (signal) => {
@@ -554,6 +614,9 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
+exports.HealthCheckFailed = HealthCheckFailed;
+exports.HealthChecks = HealthChecks;
+exports.Instrumentations = Instrumentations;
 exports.LEVELS = LEVELS;
 exports.Logger = Logger;
 exports.Meter = Meter;
@@ -563,6 +626,7 @@ exports.SPAN_STATUS = SPAN_STATUS;
 exports.Tracer = Tracer;
 exports.currentUnit = currentUnit;
 exports.releasedBy = releasedBy;
+exports.runHealthChecks = runHealthChecks;
 exports.runMain = runMain;
 exports.start = start;
 exports.stderrSink = stderrSink;

package/dist/index.d.cts

@@ -1,6 +1,85 @@
 import { AsyncResult, Result } from "unthrown";
 import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
+//#region src/instrumentation.d.ts
+/**
+ * One package's offer of an OpenTelemetry instrumentation.
+ *
+ * **Async, and answers `undefined` rather than failing, because the package
+ * supplying the instrumentation is an OPTIONAL peer.** A starter cannot know at
+ * composition time whether the consumer installed it, so it contributes the
+ * ATTEMPT and the collector drops what did not load — which is what lets
+ * `@btravstack/prisma` declare engine tracing without making every consumer
+ * install `@prisma/instrumentation`. A contributor that wants to say why its
+ * load answered nothing logs that itself; it is the one that knows.
+ *
+ * The instrumentation is `unknown` on purpose. Naming OpenTelemetry's
+ * `Instrumentation` would put the vendor in the package every other one peers
+ * on — the same reason `Tracer` and `Meter` are declared as narrowings rather
+ * than as OTel's own types. The collector
+ * (`@btravstack/observability/otel`) is where the vendor is already a
+ * dependency, so that is where the cast belongs.
+ */
+type InstrumentationLoader = () => Promise<unknown>;
+declare const Instrumentations_base: import("@btravstack/di").ManyPortClass<"Instrumentations">;
+/**
+ * The set port a package contributes its instrumentation to.
+ *
+ * Nothing collects it unless an OTel SDK is composed, which is the point: a
+ * starter DECLARES what it can instrument, and composing
+ * `@btravstack/observability/otel` is what turns the declarations on. A graph
+ * without it registers nothing and pays nothing — the Spring Boot starter
+ * shape, in one port.
+ */
+declare class Instrumentations extends Instrumentations_base<InstrumentationLoader> {}
+//#endregion
+//#region src/health.d.ts
+declare const HealthCheckFailed_base: import("unthrown").TaggedErrorConstructor<"HealthCheckFailed">;
+/**
+ * A component could not answer for itself. Modeled rather than thrown, because
+ * a health check that throws is a bug in the check; one that fails is the news
+ * `/healthz` exists to carry.
+ */
+declare class HealthCheckFailed extends HealthCheckFailed_base<{
+  readonly reason: string;
+}> {}
+/** One contribution: what to call the component, and how to ask it. */
+type HealthCheck = {
+  readonly name: string;
+  readonly check: () => AsyncResult<void, HealthCheckFailed>;
+};
+declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
+/**
+ * The set port every starter contributes to and the kernel reads whole.
+ *
+ * A set port rather than a registry the kernel hands out: a starter DECLARES
+ * its check the same way it declares anything else, and a starter an
+ * application never composed contributes nothing — no registration call to
+ * forget, and no order to get wrong.
+ */
+declare class HealthChecks extends HealthChecks_base<HealthCheck> {}
+type ComponentHealth = {
+  readonly name: string;
+  readonly status: "healthy" | "unhealthy";
+  /** Present only when the component is unhealthy. */
+  readonly reason?: string;
+};
+type HealthReport = {
+  readonly status: "healthy" | "unhealthy";
+  readonly components: readonly ComponentHealth[];
+};
+/**
+ * Runs every check and folds the results into one report — the whole app is
+ * unhealthy if any single component is.
+ *
+ * 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.
+ */
+declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
+//#endregion
 //#region src/clock.d.ts
 type Clock = {
   readonly now: () => number;
@@ -455,4 +534,4 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  */
 declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-export { type Attributes, type Clock, type Counter, type DrainReport, type EventSink, type ExitReport, type Histogram, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/dist/index.d.mts

@@ -1,6 +1,85 @@
-import { AsyncResult, Result } from "unthrown";
 import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
+import { AsyncResult, Result } from "unthrown";
 import { Env, Environment } from "@btravstack/config";
+//#region src/instrumentation.d.ts
+/**
+ * One package's offer of an OpenTelemetry instrumentation.
+ *
+ * **Async, and answers `undefined` rather than failing, because the package
+ * supplying the instrumentation is an OPTIONAL peer.** A starter cannot know at
+ * composition time whether the consumer installed it, so it contributes the
+ * ATTEMPT and the collector drops what did not load — which is what lets
+ * `@btravstack/prisma` declare engine tracing without making every consumer
+ * install `@prisma/instrumentation`. A contributor that wants to say why its
+ * load answered nothing logs that itself; it is the one that knows.
+ *
+ * The instrumentation is `unknown` on purpose. Naming OpenTelemetry's
+ * `Instrumentation` would put the vendor in the package every other one peers
+ * on — the same reason `Tracer` and `Meter` are declared as narrowings rather
+ * than as OTel's own types. The collector
+ * (`@btravstack/observability/otel`) is where the vendor is already a
+ * dependency, so that is where the cast belongs.
+ */
+type InstrumentationLoader = () => Promise<unknown>;
+declare const Instrumentations_base: import("@btravstack/di").ManyPortClass<"Instrumentations">;
+/**
+ * The set port a package contributes its instrumentation to.
+ *
+ * Nothing collects it unless an OTel SDK is composed, which is the point: a
+ * starter DECLARES what it can instrument, and composing
+ * `@btravstack/observability/otel` is what turns the declarations on. A graph
+ * without it registers nothing and pays nothing — the Spring Boot starter
+ * shape, in one port.
+ */
+declare class Instrumentations extends Instrumentations_base<InstrumentationLoader> {}
+//#endregion
+//#region src/health.d.ts
+declare const HealthCheckFailed_base: import("unthrown").TaggedErrorConstructor<"HealthCheckFailed">;
+/**
+ * A component could not answer for itself. Modeled rather than thrown, because
+ * a health check that throws is a bug in the check; one that fails is the news
+ * `/healthz` exists to carry.
+ */
+declare class HealthCheckFailed extends HealthCheckFailed_base<{
+  readonly reason: string;
+}> {}
+/** One contribution: what to call the component, and how to ask it. */
+type HealthCheck = {
+  readonly name: string;
+  readonly check: () => AsyncResult<void, HealthCheckFailed>;
+};
+declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
+/**
+ * The set port every starter contributes to and the kernel reads whole.
+ *
+ * A set port rather than a registry the kernel hands out: a starter DECLARES
+ * its check the same way it declares anything else, and a starter an
+ * application never composed contributes nothing — no registration call to
+ * forget, and no order to get wrong.
+ */
+declare class HealthChecks extends HealthChecks_base<HealthCheck> {}
+type ComponentHealth = {
+  readonly name: string;
+  readonly status: "healthy" | "unhealthy";
+  /** Present only when the component is unhealthy. */
+  readonly reason?: string;
+};
+type HealthReport = {
+  readonly status: "healthy" | "unhealthy";
+  readonly components: readonly ComponentHealth[];
+};
+/**
+ * Runs every check and folds the results into one report — the whole app is
+ * unhealthy if any single component is.
+ *
+ * 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.
+ */
+declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
+//#endregion
 //#region src/clock.d.ts
 type Clock = {
   readonly now: () => number;
@@ -455,4 +534,4 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  */
 declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-export { type Attributes, type Clock, type Counter, type DrainReport, type EventSink, type ExitReport, type Histogram, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/dist/index.mjs

@@ -1,8 +1,58 @@
-import { Err, Ok, OkAsync, P, TaggedError, fromSafePromise } from "unthrown";
 import { Module, Port, Provider } from "@btravstack/di";
+import { Err, Ok, OkAsync, P, TaggedError, allAsync, fromSafePromise } from "unthrown";
 import { Config, ConfigInvalid, Env } from "@btravstack/config";
 import { createServer } from "node:http";
 import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/instrumentation.ts
+/**
+* The set port a package contributes its instrumentation to.
+*
+* Nothing collects it unless an OTel SDK is composed, which is the point: a
+* starter DECLARES what it can instrument, and composing
+* `@btravstack/observability/otel` is what turns the declarations on. A graph
+* without it registers nothing and pays nothing — the Spring Boot starter
+* shape, in one port.
+*/
+var Instrumentations = class extends Port.many("Instrumentations") {};
+//#endregion
+//#region src/health.ts
+/**
+* A component could not answer for itself. Modeled rather than thrown, because
+* a health check that throws is a bug in the check; one that fails is the news
+* `/healthz` exists to carry.
+*/
+var HealthCheckFailed = class extends TaggedError("HealthCheckFailed") {};
+/**
+* The set port every starter contributes to and the kernel reads whole.
+*
+* A set port rather than a registry the kernel hands out: a starter DECLARES
+* its check the same way it declares anything else, and a starter an
+* application never composed contributes nothing — no registration call to
+* forget, and no order to get wrong.
+*/
+var HealthChecks = class extends Port.many("HealthChecks") {};
+/**
+* Runs every check and folds the results into one report — the whole app is
+* unhealthy if any single component is.
+*
+* 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.
+*/
+const runHealthChecks = (checks) => allAsync(checks.map((health) => 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) => ({
+	status: components.every((c) => c.status === "healthy") ? "healthy" : "unhealthy",
+	components
+}));
+//#endregion
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
@@ -184,6 +234,12 @@ const startProbeServer = (args) => fromSafePromise(new Promise((resolve) => {
 			respond(response, args.ready(), "ready");
 			return;
 		}
+		if (request.url === "/healthz") {
+			args.health().map((report) => {
+				response.writeHead(report.status === "healthy" ? 200 : 503, { "content-type": "application/json" }).end(JSON.stringify(report));
+			});
+			return;
+		}
 		response.writeHead(404).end();
 	});
 	const onBindError = (cause) => {
@@ -358,6 +414,8 @@ const start = (module, options = {}) => {
 		requestShutdown("uncaught");
 	});
 	let disposeProbes = () => {};
+	let healthChecks = [];
+	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	emit({ type: "building" });
@@ -375,7 +433,8 @@ const start = (module, options = {}) => {
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? OkAsync() : startProbeServer({
 		port: probes.port,
 		live,
-		ready
+		ready,
+		health
 	}).tap((server) => {
 		probeBoundPort = server.port;
 		probeBound.resolve(server.port);
@@ -443,6 +502,7 @@ const start = (module, options = {}) => {
 			tracker.advanceTo("starting");
 			const runtime = ctx.get(RuntimePort);
 			runtimeName = runtime.name;
+			healthChecks = ctx.get(HealthChecks);
 			const runtimeCtx = ctx;
 			const unit = options.unit;
 			const run = (meta, work) => registry.run(meta, (signal) => {
@@ -553,4 +613,4 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
-export { LEVELS, Logger, Meter, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.5.0",
+  "version": "0.6.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.5.0",
-    "@btravstack/di": "0.5.0"
+    "@btravstack/config": "0.6.0",
+    "@btravstack/di": "0.6.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.5.0",
-    "@btravstack/di": "^0.5.0"
+    "@btravstack/config": "^0.6.0",
+    "@btravstack/di": "^0.6.0"
   },
   "engines": {
     "node": ">=22"