@btravstack/core 0.11.0 → 0.12.0

package/README.md

@@ -112,6 +112,22 @@ and turns the outcome into a process exit code — one call, and the whole of a
 `TickerApp` that does not export `Greeter` is a type error at the call, and so
 is a module that exports no runtime port at all.
 
+## For a runtime author
+
+Two helpers sit beside the `Runtime` contract, because every transport needs
+them and none should own a private copy:
+
+- **`releasedBy(signal, running)`** — `running`, but no later than the kernel's
+  drain deadline, for a `Serving.drain` whose work settles on somebody else's
+  clock.
+- **`traceIdOfTraceparent(header)`** — the trace-id field of a W3C
+  `traceparent`, and nothing else of it: the parent's span id is dropped, since
+  `UnitMeta.traceId` is a correlation id rather than a span context. Answers
+  `undefined` for anything the specification calls invalid — a malformed
+  header, an all-zero trace id, an all-zero parent id, the reserved version
+  `ff` — so your runtime falls back to its own id instead of adopting one that
+  means nothing. A higher version's extra fields are read rather than refused.
+
 ## What you get
 
 - **A drain that survives Kubernetes.** On SIGTERM: readiness flips false, the

package/dist/index.cjs

@@ -206,6 +206,39 @@ var RuntimeStartFailed = class extends (0, unthrown.TaggedError)("RuntimeStartFa
 */
 const RuntimePort = (0, _btravstack_di.Port)("Runtime");
 /**
+* The trace id inside a W3C `traceparent` header, and nothing else of it.
+*
+* @remarks
+* The parent's **span id is dropped**, deliberately: `UnitMeta.traceId` is a
+* correlation id rather than a span context, and half-carrying one would
+* suggest a parent-child link nothing here maintains.
+*
+* Three things the specification calls invalid are refused like a malformed
+* header, because adopting one would replace a runtime's own usable id with a
+* value that means nothing: an **all-zero trace id**, an **all-zero parent
+* id** (the header is well-formed and names no span), and **version `ff`**,
+* which is reserved and never a version a caller may send.
+*
+* It is here rather than in a runtime because **every** transport carrying an
+* inbound trace needs the same answer, and two copies of a parser is two
+* places for the all-zero rule to be forgotten. A runtime pairs it with the
+* adopt-only-a-non-blank-inbound-id rule its own headers need:
+* `UnitMeta.traceId` defaults to `meta.id` when it is nullish and `""` is not,
+* so an empty header would hand a caller's every unit the same blank id.
+*
+* @example
+* ```ts
+* const parent = request.headers["traceparent"];
+* const traceId = typeof parent === "string" ? traceIdOfTraceparent(parent) : undefined;
+* ```
+*/
+const traceIdOfTraceparent = (header) => {
+	const [, version, traceId, parentId, extra] = /^(?!ff)([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-[\da-f]{2}(-.*)?$/.exec(header.trim()) ?? [];
+	if (traceId === void 0 || parentId === void 0) return void 0;
+	if (version === "00" && extra !== void 0) return void 0;
+	return /^0+$/.test(traceId) || /^0+$/.test(parentId) ? void 0 : traceId;
+};
+/**
 * `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
@@ -709,3 +742,4 @@ exports.runMain = runMain;
 exports.start = start;
 exports.stderrSink = stderrSink;
 exports.systemClock = systemClock;
+exports.traceIdOfTraceparent = traceIdOfTraceparent;

package/dist/index.d.cts

@@ -432,6 +432,34 @@ type RuntimeInstance = InstanceType<PortClass<"Runtime">>;
 type RuntimeOf<X> = ServiceOf<Extract<X, RuntimeInstance>>;
 type RuntimeResolvesOf<X> = RuntimeOf<X> extends Runtime<infer Resolves, unknown> ? Resolves : never;
 type RuntimeInfoOf<X> = RuntimeOf<X> extends Runtime<AnyPort, infer Info> ? Info : never;
+/**
+ * The trace id inside a W3C `traceparent` header, and nothing else of it.
+ *
+ * @remarks
+ * The parent's **span id is dropped**, deliberately: `UnitMeta.traceId` is a
+ * correlation id rather than a span context, and half-carrying one would
+ * suggest a parent-child link nothing here maintains.
+ *
+ * Three things the specification calls invalid are refused like a malformed
+ * header, because adopting one would replace a runtime's own usable id with a
+ * value that means nothing: an **all-zero trace id**, an **all-zero parent
+ * id** (the header is well-formed and names no span), and **version `ff`**,
+ * which is reserved and never a version a caller may send.
+ *
+ * It is here rather than in a runtime because **every** transport carrying an
+ * inbound trace needs the same answer, and two copies of a parser is two
+ * places for the all-zero rule to be forgotten. A runtime pairs it with the
+ * adopt-only-a-non-blank-inbound-id rule its own headers need:
+ * `UnitMeta.traceId` defaults to `meta.id` when it is nullish and `""` is not,
+ * so an empty header would hand a caller's every unit the same blank id.
+ *
+ * @example
+ * ```ts
+ * const parent = request.headers["traceparent"];
+ * const traceId = typeof parent === "string" ? traceIdOfTraceparent(parent) : undefined;
+ * ```
+ */
+declare const traceIdOfTraceparent: (header: string) => string | undefined;
 /**
  * `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
@@ -666,4 +694,4 @@ declare const start: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<
  */
 declare const runMain: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-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, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, 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, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };

package/dist/index.d.mts

@@ -432,6 +432,34 @@ type RuntimeInstance = InstanceType<PortClass<"Runtime">>;
 type RuntimeOf<X> = ServiceOf<Extract<X, RuntimeInstance>>;
 type RuntimeResolvesOf<X> = RuntimeOf<X> extends Runtime<infer Resolves, unknown> ? Resolves : never;
 type RuntimeInfoOf<X> = RuntimeOf<X> extends Runtime<AnyPort, infer Info> ? Info : never;
+/**
+ * The trace id inside a W3C `traceparent` header, and nothing else of it.
+ *
+ * @remarks
+ * The parent's **span id is dropped**, deliberately: `UnitMeta.traceId` is a
+ * correlation id rather than a span context, and half-carrying one would
+ * suggest a parent-child link nothing here maintains.
+ *
+ * Three things the specification calls invalid are refused like a malformed
+ * header, because adopting one would replace a runtime's own usable id with a
+ * value that means nothing: an **all-zero trace id**, an **all-zero parent
+ * id** (the header is well-formed and names no span), and **version `ff`**,
+ * which is reserved and never a version a caller may send.
+ *
+ * It is here rather than in a runtime because **every** transport carrying an
+ * inbound trace needs the same answer, and two copies of a parser is two
+ * places for the all-zero rule to be forgotten. A runtime pairs it with the
+ * adopt-only-a-non-blank-inbound-id rule its own headers need:
+ * `UnitMeta.traceId` defaults to `meta.id` when it is nullish and `""` is not,
+ * so an empty header would hand a caller's every unit the same blank id.
+ *
+ * @example
+ * ```ts
+ * const parent = request.headers["traceparent"];
+ * const traceId = typeof parent === "string" ? traceIdOfTraceparent(parent) : undefined;
+ * ```
+ */
+declare const traceIdOfTraceparent: (header: string) => string | undefined;
 /**
  * `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
@@ -666,4 +694,4 @@ declare const start: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<
  */
 declare const runMain: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-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, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, 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, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };

package/dist/index.mjs

@@ -205,6 +205,39 @@ var RuntimeStartFailed = class extends TaggedError("RuntimeStartFailed") {
 */
 const RuntimePort = Port("Runtime");
 /**
+* The trace id inside a W3C `traceparent` header, and nothing else of it.
+*
+* @remarks
+* The parent's **span id is dropped**, deliberately: `UnitMeta.traceId` is a
+* correlation id rather than a span context, and half-carrying one would
+* suggest a parent-child link nothing here maintains.
+*
+* Three things the specification calls invalid are refused like a malformed
+* header, because adopting one would replace a runtime's own usable id with a
+* value that means nothing: an **all-zero trace id**, an **all-zero parent
+* id** (the header is well-formed and names no span), and **version `ff`**,
+* which is reserved and never a version a caller may send.
+*
+* It is here rather than in a runtime because **every** transport carrying an
+* inbound trace needs the same answer, and two copies of a parser is two
+* places for the all-zero rule to be forgotten. A runtime pairs it with the
+* adopt-only-a-non-blank-inbound-id rule its own headers need:
+* `UnitMeta.traceId` defaults to `meta.id` when it is nullish and `""` is not,
+* so an empty header would hand a caller's every unit the same blank id.
+*
+* @example
+* ```ts
+* const parent = request.headers["traceparent"];
+* const traceId = typeof parent === "string" ? traceIdOfTraceparent(parent) : undefined;
+* ```
+*/
+const traceIdOfTraceparent = (header) => {
+	const [, version, traceId, parentId, extra] = /^(?!ff)([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-[\da-f]{2}(-.*)?$/.exec(header.trim()) ?? [];
+	if (traceId === void 0 || parentId === void 0) return void 0;
+	if (version === "00" && extra !== void 0) return void 0;
+	return /^0+$/.test(traceId) || /^0+$/.test(parentId) ? void 0 : traceId;
+};
+/**
 * `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
@@ -688,4 +721,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 };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };

package/package.json

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