@spinajs/log 2.0.481 → 2.0.484

package/lib/mjs/traceparent.d.ts

@@ -0,0 +1,63 @@
+/**
+ * W3C Trace Context ( traceparent ) utilities.
+ *
+ * Pure, dependency-free and cross-platform ( Node 20+ and browsers ) — randomness
+ * is sourced from the WHATWG `crypto.getRandomValues`, available on `globalThis`
+ * in both environments, so this module deliberately does NOT import
+ * `node:crypto` and stays safe to bundle for the browser.
+ *
+ * A W3C `traceparent` header has the shape:
+ *
+ *   version "-" trace-id "-" parent-id "-" trace-flags
+ *   00      -   32 hex    -   16 hex     -   2 hex
+ *
+ * See https://www.w3.org/TR/trace-context/#traceparent-header.
+ */
+/**
+ * Minimal trace context this service carries on the ambient store and emits on
+ * the outbound `traceparent` header.
+ */
+export interface ITraceContext {
+    /** 32-hex-char trace id, shared by every span across services in one trace. */
+    traceId: string;
+    /** 16-hex-char span id identifying this service's span within the trace. */
+    spanId: string;
+    /** Whether the trace is sampled ( low bit of the trace-flags ). */
+    sampled: boolean;
+}
+/**
+ * Parse & validate an inbound `traceparent` header value.
+ *
+ * @returns the decomposed parts ( plus the derived `sampled` flag ), or `null`
+ *          when the value is missing / malformed / forbidden by the spec
+ *          ( all-zero trace-id, all-zero parent-id, or version `ff` ).
+ */
+export declare function parseTraceparent(value: string | undefined | null): {
+    version: string;
+    traceId: string;
+    parentId: string;
+    flags: string;
+    sampled: boolean;
+} | null;
+/**
+ * A fresh random trace id ( 16 bytes -> 32 lowercase hex chars ).
+ */
+export declare function randomTraceId(): string;
+/**
+ * A fresh random span id ( 8 bytes -> 16 lowercase hex chars ).
+ */
+export declare function randomSpanId(): string;
+/**
+ * Render a {@link ITraceContext} as a W3C `traceparent` header value.
+ */
+export declare function formatTraceparent(ctx: ITraceContext): string;
+/**
+ * Derive this service's trace context for a request.
+ *
+ * When `inboundTraceparent` is a valid header we CONTINUE the trace: the trace
+ * id and sampled decision are inherited, and a fresh span id is minted for this
+ * service's own span ( its parent being the inbound `parent-id` ). Otherwise a
+ * brand-new, sampled trace is STARTED.
+ */
+export declare function newTraceContext(inboundTraceparent?: string | null): ITraceContext;
+//# sourceMappingURL=traceparent.d.ts.map

package/lib/mjs/traceparent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.d.ts","sourceRoot":"","sources":["../../src/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAwBjK;AAgBD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAejF"}

package/lib/mjs/traceparent.js

@@ -0,0 +1,100 @@
+/**
+ * W3C Trace Context ( traceparent ) utilities.
+ *
+ * Pure, dependency-free and cross-platform ( Node 20+ and browsers ) — randomness
+ * is sourced from the WHATWG `crypto.getRandomValues`, available on `globalThis`
+ * in both environments, so this module deliberately does NOT import
+ * `node:crypto` and stays safe to bundle for the browser.
+ *
+ * A W3C `traceparent` header has the shape:
+ *
+ *   version "-" trace-id "-" parent-id "-" trace-flags
+ *   00      -   32 hex    -   16 hex     -   2 hex
+ *
+ * See https://www.w3.org/TR/trace-context/#traceparent-header.
+ */
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const ZERO_TRACE_ID = "00000000000000000000000000000000";
+const ZERO_SPAN_ID = "0000000000000000";
+/**
+ * Parse & validate an inbound `traceparent` header value.
+ *
+ * @returns the decomposed parts ( plus the derived `sampled` flag ), or `null`
+ *          when the value is missing / malformed / forbidden by the spec
+ *          ( all-zero trace-id, all-zero parent-id, or version `ff` ).
+ */
+export function parseTraceparent(value) {
+    if (!value) {
+        return null;
+    }
+    const match = TRACEPARENT_RE.exec(value.toLowerCase());
+    if (!match) {
+        return null;
+    }
+    const [, version, traceId, parentId, flags] = match;
+    // Spec-forbidden values: version ff is reserved, and all-zero ids are invalid.
+    if (version === "ff" || traceId === ZERO_TRACE_ID || parentId === ZERO_SPAN_ID) {
+        return null;
+    }
+    return {
+        version,
+        traceId,
+        parentId,
+        flags,
+        sampled: (parseInt(flags, 16) & 0x01) === 1,
+    };
+}
+/**
+ * Cross-platform `n` random bytes rendered as lowercase hex.
+ */
+function randomHex(bytes) {
+    const buffer = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buffer);
+    let out = "";
+    for (const b of buffer) {
+        out += b.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+/**
+ * A fresh random trace id ( 16 bytes -> 32 lowercase hex chars ).
+ */
+export function randomTraceId() {
+    return randomHex(16);
+}
+/**
+ * A fresh random span id ( 8 bytes -> 16 lowercase hex chars ).
+ */
+export function randomSpanId() {
+    return randomHex(8);
+}
+/**
+ * Render a {@link ITraceContext} as a W3C `traceparent` header value.
+ */
+export function formatTraceparent(ctx) {
+    return `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
+}
+/**
+ * Derive this service's trace context for a request.
+ *
+ * When `inboundTraceparent` is a valid header we CONTINUE the trace: the trace
+ * id and sampled decision are inherited, and a fresh span id is minted for this
+ * service's own span ( its parent being the inbound `parent-id` ). Otherwise a
+ * brand-new, sampled trace is STARTED.
+ */
+export function newTraceContext(inboundTraceparent) {
+    const parsed = parseTraceparent(inboundTraceparent);
+    if (parsed) {
+        return {
+            traceId: parsed.traceId,
+            spanId: randomSpanId(),
+            sampled: parsed.sampled,
+        };
+    }
+    return {
+        traceId: randomTraceId(),
+        spanId: randomSpanId(),
+        sampled: true,
+    };
+}
+//# sourceMappingURL=traceparent.js.map

package/lib/mjs/traceparent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.js","sourceRoot":"","sources":["../../src/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,MAAM,cAAc,GAAG,6DAA6D,CAAC;AACrF,MAAM,aAAa,GAAG,kCAAkC,CAAC;AACzD,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAEpD,+EAA+E;IAC/E,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,aAAa,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO;QACP,OAAO;QACP,QAAQ;QACR,KAAK;QACL,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAE1C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,SAAS,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAkB;IAClD,OAAO,MAAM,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,kBAAkC;IAChE,MAAM,MAAM,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;IACpD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,YAAY,EAAE;YACtB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,aAAa,EAAE;QACxB,MAAM,EAAE,YAAY,EAAE;QACtB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}