@beignet/core 0.0.2 → 0.0.4

package/src/tracing/index.ts

@@ -0,0 +1,176 @@
+/**
+ * @beignet/core/tracing
+ *
+ * W3C trace context primitives used to correlate Beignet activity across
+ * requests, use cases, providers, and instrumentation sinks.
+ *
+ * This module is dependency-free so client bundles that import app context
+ * types stay clean.
+ */
+
+const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+/**
+ * Trace context used to correlate related activity.
+ */
+export interface TraceContext {
+  /**
+   * W3C trace ID.
+   */
+  traceId: string;
+  /**
+   * Current span ID.
+   */
+  spanId: string;
+  /**
+   * Parent span ID when available.
+   */
+  parentSpanId?: string;
+  /**
+   * W3C traceparent header value.
+   */
+  traceparent: string;
+}
+
+/**
+ * Parsed W3C traceparent header.
+ */
+export interface ParsedTraceparent {
+  /**
+   * W3C trace ID.
+   */
+  traceId: string;
+  /**
+   * Span ID from the traceparent header.
+   */
+  spanId: string;
+  /**
+   * Trace flags from the traceparent header.
+   */
+  traceFlags: string;
+  /**
+   * Normalized traceparent header value.
+   */
+  traceparent: string;
+}
+
+/**
+ * Input accepted when creating trace context.
+ */
+export interface TraceContextInput {
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+}
+
+function createHexId(length: number): string {
+  const bytes = new Uint8Array(length / 2);
+  if (typeof crypto !== "undefined" && "getRandomValues" in crypto) {
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+      "",
+    );
+  }
+
+  let value = "";
+  while (value.length < length) {
+    value += Math.floor(Math.random() * 16).toString(16);
+  }
+  return value.slice(0, length);
+}
+
+function isNonZeroHex(value: string): boolean {
+  return !/^0+$/.test(value);
+}
+
+/**
+ * Create a non-zero W3C trace ID.
+ */
+export function createTraceId(): string {
+  let traceId = createHexId(32);
+  while (!isNonZeroHex(traceId)) {
+    traceId = createHexId(32);
+  }
+  return traceId;
+}
+
+/**
+ * Create a non-zero W3C span ID.
+ */
+export function createSpanId(): string {
+  let spanId = createHexId(16);
+  while (!isNonZeroHex(spanId)) {
+    spanId = createHexId(16);
+  }
+  return spanId;
+}
+
+/**
+ * Create a W3C traceparent header value.
+ */
+export function createTraceparent(args: {
+  traceId: string;
+  spanId: string;
+  traceFlags?: string;
+}): string {
+  return `00-${args.traceId}-${args.spanId}-${args.traceFlags ?? "01"}`;
+}
+
+/**
+ * Parse and validate a W3C traceparent header value.
+ */
+export function parseTraceparent(
+  value: string | null | undefined,
+): ParsedTraceparent | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  const match = TRACEPARENT_PATTERN.exec(normalized);
+  if (!match) return undefined;
+
+  const [, traceId, spanId, traceFlags] = match;
+  if (!isNonZeroHex(traceId) || !isNonZeroHex(spanId)) return undefined;
+
+  return {
+    traceId,
+    spanId,
+    traceFlags,
+    traceparent: normalized,
+  };
+}
+
+/**
+ * Create trace context from explicit IDs or an existing traceparent.
+ */
+export function createTraceContext(
+  input: TraceContextInput = {},
+): TraceContext {
+  const parsed = parseTraceparent(input.traceparent);
+  const traceId = input.traceId ?? parsed?.traceId ?? createTraceId();
+  const parentSpanId = input.parentSpanId ?? parsed?.spanId;
+  const spanId = input.spanId ?? createSpanId();
+
+  return {
+    traceId,
+    spanId,
+    ...(parentSpanId ? { parentSpanId } : {}),
+    traceparent: createTraceparent({
+      traceId,
+      spanId,
+      traceFlags: parsed?.traceFlags,
+    }),
+  };
+}
+
+/**
+ * Create child trace context from a parent context.
+ */
+export function createChildTraceContext(
+  parent: TraceContextInput,
+): TraceContext {
+  return createTraceContext({
+    traceId: parent.traceId,
+    parentSpanId: parent.spanId,
+    traceparent: parent.traceparent,
+  });
+}