@dotdo/postgres 0.1.0

package/src/observability/propagation.test.ts

@@ -0,0 +1,417 @@
+/**
+ * Tests for Span Context Propagation
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  parseTraceparent,
+  formatTraceparent,
+  parseTracestate,
+  formatTracestate,
+  extractSpanContext,
+  injectSpanContext,
+  createChildContext,
+  createRootContext,
+  isSampled,
+  TRACEPARENT_HEADER,
+  TRACESTATE_HEADER,
+  SAMPLED_FLAG,
+  W3CTraceContextPropagator,
+  createPropagator,
+} from './propagation'
+import type { SpanContext } from './types'
+
+describe('Propagation', () => {
+  describe('parseTraceparent()', () => {
+    it('should parse a valid traceparent header', () => {
+      const header = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
+      const context = parseTraceparent(header)
+
+      expect(context).not.toBeNull()
+      expect(context?.traceId).toBe('0af7651916cd43dd8448eb211c80319c')
+      expect(context?.spanId).toBe('b7ad6b7169203331')
+      expect(context?.parentSpanId).toBe('b7ad6b7169203331')
+      expect(context?.traceFlags).toBe(1)
+    })
+
+    it('should return null for null input', () => {
+      expect(parseTraceparent(null)).toBeNull()
+    })
+
+    it('should return null for empty string', () => {
+      expect(parseTraceparent('')).toBeNull()
+    })
+
+    it('should return null for invalid format (wrong number of parts)', () => {
+      expect(parseTraceparent('00-abc-def')).toBeNull()
+      expect(parseTraceparent('00-abc-def-01-extra')).toBeNull()
+    })
+
+    it('should return null for invalid trace ID (wrong length)', () => {
+      expect(parseTraceparent('00-abc-b7ad6b7169203331-01')).toBeNull()
+    })
+
+    it('should return null for all-zero trace ID', () => {
+      expect(
+        parseTraceparent('00-00000000000000000000000000000000-b7ad6b7169203331-01')
+      ).toBeNull()
+    })
+
+    it('should return null for invalid span ID (wrong length)', () => {
+      expect(
+        parseTraceparent('00-0af7651916cd43dd8448eb211c80319c-abc-01')
+      ).toBeNull()
+    })
+
+    it('should return null for all-zero span ID', () => {
+      expect(
+        parseTraceparent('00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01')
+      ).toBeNull()
+    })
+
+    it('should return null for invalid trace flags', () => {
+      expect(
+        parseTraceparent('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-xyz')
+      ).toBeNull()
+    })
+
+    it('should handle unsampled trace (flags = 00)', () => {
+      const header = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00'
+      const context = parseTraceparent(header)
+
+      expect(context?.traceFlags).toBe(0)
+    })
+  })
+
+  describe('formatTraceparent()', () => {
+    it('should format a span context as traceparent header', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      const header = formatTraceparent(context)
+      expect(header).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+    })
+
+    it('should format unsampled trace correctly', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 0,
+      }
+
+      const header = formatTraceparent(context)
+      expect(header).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00')
+    })
+
+    it('should be reversible with parseTraceparent', () => {
+      const original: SpanContext = {
+        traceId: 'abcdef1234567890abcdef1234567890',
+        spanId: 'abcdef1234567890',
+        traceFlags: 1,
+      }
+
+      const header = formatTraceparent(original)
+      const parsed = parseTraceparent(header)
+
+      expect(parsed?.traceId).toBe(original.traceId)
+      expect(parsed?.spanId).toBe(original.spanId)
+      expect(parsed?.traceFlags).toBe(original.traceFlags)
+    })
+  })
+
+  describe('parseTracestate()', () => {
+    it('should parse a valid tracestate header', () => {
+      const header = 'congo=t61rcWkgMzE,rojo=00f067aa0ba902b7'
+      const state = parseTracestate(header)
+
+      expect(state['congo']).toBe('t61rcWkgMzE')
+      expect(state['rojo']).toBe('00f067aa0ba902b7')
+    })
+
+    it('should return empty object for null input', () => {
+      expect(parseTracestate(null)).toEqual({})
+    })
+
+    it('should return empty object for empty string', () => {
+      expect(parseTracestate('')).toEqual({})
+    })
+
+    it('should handle single entry', () => {
+      const state = parseTracestate('vendor=value')
+      expect(state['vendor']).toBe('value')
+    })
+
+    it('should handle whitespace', () => {
+      const state = parseTracestate(' vendor1=value1 , vendor2=value2 ')
+      expect(state['vendor1']).toBe('value1')
+      expect(state['vendor2']).toBe('value2')
+    })
+
+    it('should filter invalid keys', () => {
+      const state = parseTracestate('valid_key=value,INVALID=uppercase')
+      expect(state['valid_key']).toBe('value')
+      // Uppercase keys should be filtered
+      expect(state['INVALID']).toBeUndefined()
+    })
+  })
+
+  describe('formatTracestate()', () => {
+    it('should format a tracestate map as header', () => {
+      const state = { vendor1: 'value1', vendor2: 'value2' }
+      const header = formatTracestate(state)
+      expect(header).toBe('vendor1=value1,vendor2=value2')
+    })
+
+    it('should handle empty state', () => {
+      expect(formatTracestate({})).toBe('')
+    })
+
+    it('should handle single entry', () => {
+      expect(formatTracestate({ vendor: 'value' })).toBe('vendor=value')
+    })
+  })
+
+  describe('extractSpanContext()', () => {
+    it('should extract from Headers object', () => {
+      const headers = new Headers()
+      headers.set(TRACEPARENT_HEADER, '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+      headers.set(TRACESTATE_HEADER, 'vendor=value')
+
+      const context = extractSpanContext(headers)
+
+      expect(context?.traceId).toBe('0af7651916cd43dd8448eb211c80319c')
+      expect(context?.traceState).toBe('vendor=value')
+    })
+
+    it('should extract from Record object', () => {
+      const headers: Record<string, string> = {
+        [TRACEPARENT_HEADER]: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+        [TRACESTATE_HEADER]: 'vendor=value',
+      }
+
+      const context = extractSpanContext(headers)
+
+      expect(context?.traceId).toBe('0af7651916cd43dd8448eb211c80319c')
+      expect(context?.traceState).toBe('vendor=value')
+    })
+
+    it('should extract from Map object', () => {
+      const headers = new Map<string, string>()
+      headers.set(TRACEPARENT_HEADER, '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+
+      const context = extractSpanContext(headers)
+
+      expect(context?.traceId).toBe('0af7651916cd43dd8448eb211c80319c')
+    })
+
+    it('should return null when traceparent is missing', () => {
+      const headers = new Headers()
+      expect(extractSpanContext(headers)).toBeNull()
+    })
+
+    it('should return context without traceState when tracestate is missing', () => {
+      const headers = new Headers()
+      headers.set(TRACEPARENT_HEADER, '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+
+      const context = extractSpanContext(headers)
+
+      expect(context?.traceId).toBeDefined()
+      expect(context?.traceState).toBeUndefined()
+    })
+  })
+
+  describe('injectSpanContext()', () => {
+    it('should inject into Headers object', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+        traceState: 'vendor=value',
+      }
+
+      const headers = new Headers()
+      injectSpanContext(context, headers)
+
+      expect(headers.get(TRACEPARENT_HEADER)).toBe(
+        '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
+      )
+      expect(headers.get(TRACESTATE_HEADER)).toBe('vendor=value')
+    })
+
+    it('should inject into Record object', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      const headers: Record<string, string> = {}
+      injectSpanContext(context, headers)
+
+      expect(headers[TRACEPARENT_HEADER]).toBe(
+        '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
+      )
+    })
+
+    it('should not inject tracestate when not present', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      const headers = new Headers()
+      injectSpanContext(context, headers)
+
+      expect(headers.has(TRACESTATE_HEADER)).toBe(false)
+    })
+
+    it('should return the headers object for chaining', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      const headers = new Headers()
+      const result = injectSpanContext(context, headers)
+
+      expect(result).toBe(headers)
+    })
+  })
+
+  describe('createChildContext()', () => {
+    it('should create a child with same trace ID', () => {
+      const parent: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+        traceState: 'vendor=value',
+      }
+
+      const child = createChildContext(parent)
+
+      expect(child.traceId).toBe(parent.traceId)
+      expect(child.parentSpanId).toBe(parent.spanId)
+      expect(child.traceFlags).toBe(parent.traceFlags)
+      expect(child.traceState).toBe(parent.traceState)
+    })
+
+    it('should generate a new span ID', () => {
+      const parent: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      const child = createChildContext(parent)
+
+      expect(child.spanId).not.toBe(parent.spanId)
+      expect(child.spanId).toHaveLength(16)
+    })
+  })
+
+  describe('createRootContext()', () => {
+    it('should create a new root context', () => {
+      const context = createRootContext()
+
+      expect(context.traceId).toHaveLength(32)
+      expect(context.spanId).toHaveLength(16)
+      expect(context.parentSpanId).toBeUndefined()
+      expect(context.traceFlags).toBe(SAMPLED_FLAG)
+    })
+
+    it('should create unsampled context when sampled=false', () => {
+      const context = createRootContext(false)
+
+      expect(context.traceFlags).toBe(0)
+    })
+
+    it('should generate unique IDs', () => {
+      const context1 = createRootContext()
+      const context2 = createRootContext()
+
+      expect(context1.traceId).not.toBe(context2.traceId)
+      expect(context1.spanId).not.toBe(context2.spanId)
+    })
+  })
+
+  describe('isSampled()', () => {
+    it('should return true for sampled trace', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      expect(isSampled(context)).toBe(true)
+    })
+
+    it('should return false for unsampled trace', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 0,
+      }
+
+      expect(isSampled(context)).toBe(false)
+    })
+
+    it('should handle trace flags with other bits set', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 0x03, // Sampled + another bit
+      }
+
+      expect(isSampled(context)).toBe(true)
+    })
+  })
+
+  describe('W3CTraceContextPropagator', () => {
+    it('should be created with createPropagator()', () => {
+      const propagator = createPropagator()
+      expect(propagator).toBeInstanceOf(W3CTraceContextPropagator)
+    })
+
+    it('should extract span context', () => {
+      const propagator = createPropagator()
+      const headers = new Headers()
+      headers.set(TRACEPARENT_HEADER, '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+
+      const context = propagator.extract(headers)
+
+      expect(context?.traceId).toBe('0af7651916cd43dd8448eb211c80319c')
+    })
+
+    it('should inject span context', () => {
+      const propagator = createPropagator()
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      }
+
+      const headers = new Headers()
+      propagator.inject(context, headers)
+
+      expect(headers.get(TRACEPARENT_HEADER)).toBe(
+        '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
+      )
+    })
+  })
+
+  describe('Header constants', () => {
+    it('should export correct header names', () => {
+      expect(TRACEPARENT_HEADER).toBe('traceparent')
+      expect(TRACESTATE_HEADER).toBe('tracestate')
+    })
+
+    it('should export sampled flag', () => {
+      expect(SAMPLED_FLAG).toBe(0x01)
+    })
+  })
+})

package/src/observability/propagation.ts

@@ -0,0 +1,294 @@
+/**
+ * Span Context Propagation
+ *
+ * Implements W3C Trace Context propagation for distributed tracing.
+ * Allows span context to be passed between services via HTTP headers.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+
+import type { SpanContext } from './types'
+import { generateTraceId, generateSpanId } from './tracer'
+
+/**
+ * W3C Trace Context header names
+ */
+export const TRACEPARENT_HEADER = 'traceparent'
+export const TRACESTATE_HEADER = 'tracestate'
+
+/**
+ * Trace flags
+ */
+export const SAMPLED_FLAG = 0x01
+
+/**
+ * Parse a traceparent header into a SpanContext
+ *
+ * @param header - The traceparent header value
+ * @returns SpanContext or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const context = parseTraceparent('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+ * // { traceId: '0af7651916cd43dd8448eb211c80319c', spanId: 'b7ad6b7169203331', traceFlags: 1 }
+ * ```
+ */
+export function parseTraceparent(header: string | null): SpanContext | null {
+  if (!header) {
+    return null
+  }
+
+  // Format: version-traceid-parentid-traceflags
+  // Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+  const parts = header.split('-')
+
+  if (parts.length !== 4) {
+    return null
+  }
+
+  const version = parts[0]!; const traceId = parts[1]!; const spanId = parts[2]!; const flags = parts[3]!
+
+  // Validate version (currently only version 00 is supported)
+  if (version !== '00') {
+    // Future versions might be supported, but we only handle 00
+    if (version.length !== 2 || !/^[0-9a-f]{2}$/.test(version)) {
+      return null
+    }
+  }
+
+  // Validate trace ID (32 hex chars, not all zeros)
+  if (
+    traceId.length !== 32 ||
+    !/^[0-9a-f]{32}$/.test(traceId) ||
+    traceId === '00000000000000000000000000000000'
+  ) {
+    return null
+  }
+
+  // Validate span ID (16 hex chars, not all zeros)
+  if (
+    spanId.length !== 16 ||
+    !/^[0-9a-f]{16}$/.test(spanId) ||
+    spanId === '0000000000000000'
+  ) {
+    return null
+  }
+
+  // Validate trace flags (2 hex chars)
+  if (flags.length !== 2 || !/^[0-9a-f]{2}$/.test(flags)) {
+    return null
+  }
+
+  const traceFlags = parseInt(flags, 16)
+
+  return {
+    traceId,
+    spanId,
+    parentSpanId: spanId, // The incoming span ID becomes our parent
+    traceFlags,
+  }
+}
+
+/**
+ * Format a SpanContext as a traceparent header value
+ *
+ * @param context - The span context to format
+ * @returns The traceparent header value
+ *
+ * @example
+ * ```typescript
+ * const header = formatTraceparent({
+ *   traceId: '0af7651916cd43dd8448eb211c80319c',
+ *   spanId: 'b7ad6b7169203331',
+ *   traceFlags: 1,
+ * })
+ * // '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
+ * ```
+ */
+export function formatTraceparent(context: SpanContext): string {
+  const version = '00'
+  const flags = context.traceFlags.toString(16).padStart(2, '0')
+  return `${version}-${context.traceId}-${context.spanId}-${flags}`
+}
+
+/**
+ * Parse a tracestate header into a key-value map
+ *
+ * @param header - The tracestate header value
+ * @returns Map of vendor-specific trace state
+ *
+ * @example
+ * ```typescript
+ * const state = parseTracestate('congo=t61rcWkgMzE,rojo=00f067aa0ba902b7')
+ * // { congo: 't61rcWkgMzE', rojo: '00f067aa0ba902b7' }
+ * ```
+ */
+export function parseTracestate(header: string | null): Record<string, string> {
+  if (!header) {
+    return {}
+  }
+
+  const state: Record<string, string> = {}
+  const pairs = header.split(',')
+
+  for (const pair of pairs) {
+    const [key, value] = pair.trim().split('=')
+    if (key && value !== undefined) {
+      // Validate key format (only lowercase letters, digits, underscore, hyphen, asterisk, slash)
+      if (/^[a-z0-9_\-*/]+$/.test(key)) {
+        state[key] = value
+      }
+    }
+  }
+
+  return state
+}
+
+/**
+ * Format a tracestate map as a header value
+ *
+ * @param state - The trace state map
+ * @returns The tracestate header value
+ */
+export function formatTracestate(state: Record<string, string>): string {
+  return Object.entries(state)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(',')
+}
+
+/**
+ * Extract span context from HTTP headers
+ *
+ * @param headers - The headers object (Headers, Record, or Map)
+ * @returns SpanContext or null if not present
+ */
+export function extractSpanContext(
+  headers: Headers | Record<string, string> | Map<string, string>
+): SpanContext | null {
+  let traceparent: string | null = null
+  let tracestate: string | null = null
+
+  if (headers instanceof Headers) {
+    traceparent = headers.get(TRACEPARENT_HEADER)
+    tracestate = headers.get(TRACESTATE_HEADER)
+  } else if (headers instanceof Map) {
+    traceparent = headers.get(TRACEPARENT_HEADER) ?? null
+    tracestate = headers.get(TRACESTATE_HEADER) ?? null
+  } else {
+    traceparent = headers[TRACEPARENT_HEADER] ?? null
+    tracestate = headers[TRACESTATE_HEADER] ?? null
+  }
+
+  const context = parseTraceparent(traceparent)
+  if (context && tracestate) {
+    context.traceState = tracestate
+  }
+
+  return context
+}
+
+/**
+ * Inject span context into HTTP headers
+ *
+ * @param context - The span context to inject
+ * @param headers - The headers object to inject into
+ * @returns The headers object (for chaining)
+ */
+export function injectSpanContext(
+  context: SpanContext,
+  headers: Headers
+): Headers
+export function injectSpanContext(
+  context: SpanContext,
+  headers: Record<string, string>
+): Record<string, string>
+export function injectSpanContext(
+  context: SpanContext,
+  headers: Headers | Record<string, string>
+): Headers | Record<string, string> {
+  const traceparent = formatTraceparent(context)
+
+  if (headers instanceof Headers) {
+    headers.set(TRACEPARENT_HEADER, traceparent)
+    if (context.traceState) {
+      headers.set(TRACESTATE_HEADER, context.traceState)
+    }
+  } else {
+    headers[TRACEPARENT_HEADER] = traceparent
+    if (context.traceState) {
+      headers[TRACESTATE_HEADER] = context.traceState
+    }
+  }
+
+  return headers
+}
+
+/**
+ * Create a child span context from a parent
+ *
+ * @param parent - The parent span context
+ * @returns A new span context with the same trace ID
+ */
+export function createChildContext(parent: SpanContext): SpanContext {
+  return {
+    traceId: parent.traceId,
+    spanId: generateSpanId(),
+    parentSpanId: parent.spanId,
+    traceFlags: parent.traceFlags,
+    traceState: parent.traceState,
+  }
+}
+
+/**
+ * Create a new root span context
+ *
+ * @param sampled - Whether the trace should be sampled (default: true)
+ * @returns A new span context
+ */
+export function createRootContext(sampled = true): SpanContext {
+  return {
+    traceId: generateTraceId(),
+    spanId: generateSpanId(),
+    traceFlags: sampled ? SAMPLED_FLAG : 0,
+  }
+}
+
+/**
+ * Check if a span context is sampled
+ *
+ * @param context - The span context
+ * @returns true if sampled
+ */
+export function isSampled(context: SpanContext): boolean {
+  return (context.traceFlags & SAMPLED_FLAG) !== 0
+}
+
+/**
+ * Propagator interface for context propagation
+ */
+export interface Propagator {
+  /** Extract span context from carrier */
+  extract(carrier: Headers | Record<string, string>): SpanContext | null
+  /** Inject span context into carrier */
+  inject(context: SpanContext, carrier: Headers | Record<string, string>): void
+}
+
+/**
+ * W3C Trace Context propagator
+ */
+export class W3CTraceContextPropagator implements Propagator {
+  extract(carrier: Headers | Record<string, string>): SpanContext | null {
+    return extractSpanContext(carrier)
+  }
+
+  inject(context: SpanContext, carrier: Headers | Record<string, string>): void {
+    injectSpanContext(context, carrier as Headers)
+  }
+}
+
+/**
+ * Create a W3C Trace Context propagator
+ */
+export function createPropagator(): Propagator {
+  return new W3CTraceContextPropagator()
+}