autotel 2.1.0

package/src/baggage-span-processor.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { BaggageSpanProcessor } from './baggage-span-processor';
+import { context, propagation, trace } from '@opentelemetry/api';
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import {
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+
+// Set up context manager globally
+const contextManager = new AsyncLocalStorageContextManager();
+contextManager.enable();
+context.setGlobalContextManager(contextManager);
+
+describe('BaggageSpanProcessor', () => {
+  beforeEach(() => {
+    // Set up context manager to ensure context propagation works
+    trace.setGlobalTracerProvider(undefined as any);
+  });
+
+  it('should copy baggage entries to span attributes with default prefix', async () => {
+    const exporter = new InMemorySpanExporter();
+    const baggageProcessor = new BaggageSpanProcessor();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [baggageProcessor, new SimpleSpanProcessor(exporter)],
+    });
+
+    // Set as global provider
+    trace.setGlobalTracerProvider(provider);
+
+    const tracer = provider.getTracer('test');
+
+    // Set baggage
+    const activeContext = context.active();
+    let baggage = propagation.createBaggage();
+    baggage = baggage.setEntry('tenant.id', { value: 'tenant-123' });
+    baggage = baggage.setEntry('user.id', { value: 'user-456' });
+    const contextWithBaggage = propagation.setBaggage(activeContext, baggage);
+
+    // Create span within baggage context
+    await new Promise<void>((resolve) => {
+      context.with(contextWithBaggage, () => {
+        tracer.startActiveSpan('test-span', (span) => {
+          span.end();
+          resolve();
+        });
+      });
+    });
+
+    // Flush to ensure spans are exported
+    await provider.forceFlush();
+
+    const spans = exporter.getFinishedSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0]!.attributes['baggage.tenant.id']).toBe('tenant-123');
+    expect(spans[0]!.attributes['baggage.user.id']).toBe('user-456');
+  });
+
+  it('should use custom prefix when provided', async () => {
+    const exporter = new InMemorySpanExporter();
+    const baggageProcessor = new BaggageSpanProcessor({ prefix: 'ctx.' });
+    const provider = new BasicTracerProvider({
+      spanProcessors: [baggageProcessor, new SimpleSpanProcessor(exporter)],
+    });
+
+    // Set as global provider
+    trace.setGlobalTracerProvider(provider);
+
+    const tracer = provider.getTracer('test');
+
+    // Set baggage
+    const activeContext = context.active();
+    let baggage = propagation.createBaggage();
+    baggage = baggage.setEntry('tenant.id', { value: 'tenant-123' });
+    const contextWithBaggage = propagation.setBaggage(activeContext, baggage);
+
+    // Create span within baggage context
+    await new Promise<void>((resolve) => {
+      context.with(contextWithBaggage, () => {
+        tracer.startActiveSpan('test-span', (span) => {
+          span.end();
+          resolve();
+        });
+      });
+    });
+
+    // Flush to ensure spans are exported
+    await provider.forceFlush();
+
+    const spans = exporter.getFinishedSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0]!.attributes['ctx.tenant.id']).toBe('tenant-123');
+  });
+
+  it('should use no prefix when empty string provided', async () => {
+    const exporter = new InMemorySpanExporter();
+    const baggageProcessor = new BaggageSpanProcessor({ prefix: '' });
+    const provider = new BasicTracerProvider({
+      spanProcessors: [baggageProcessor, new SimpleSpanProcessor(exporter)],
+    });
+
+    // Set as global provider
+    trace.setGlobalTracerProvider(provider);
+
+    const tracer = provider.getTracer('test');
+
+    // Set baggage
+    const activeContext = context.active();
+    let baggage = propagation.createBaggage();
+    baggage = baggage.setEntry('tenant.id', { value: 'tenant-123' });
+    const contextWithBaggage = propagation.setBaggage(activeContext, baggage);
+
+    // Create span within baggage context
+    await new Promise<void>((resolve) => {
+      context.with(contextWithBaggage, () => {
+        tracer.startActiveSpan('test-span', (span) => {
+          span.end();
+          resolve();
+        });
+      });
+    });
+
+    // Flush to ensure spans are exported
+    await provider.forceFlush();
+
+    const spans = exporter.getFinishedSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0]!.attributes['tenant.id']).toBe('tenant-123');
+  });
+
+  it('should handle spans with no baggage gracefully', async () => {
+    const exporter = new InMemorySpanExporter();
+    const baggageProcessor = new BaggageSpanProcessor();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [baggageProcessor, new SimpleSpanProcessor(exporter)],
+    });
+
+    // Set as global provider
+    trace.setGlobalTracerProvider(provider);
+
+    const tracer = provider.getTracer('test');
+
+    // Create span without baggage
+    await new Promise<void>((resolve) => {
+      tracer.startActiveSpan('test-span', (span) => {
+        span.end();
+        resolve();
+      });
+    });
+
+    // Flush to ensure spans are exported
+    await provider.forceFlush();
+
+    const spans = exporter.getFinishedSpans();
+    expect(spans).toHaveLength(1);
+    // Should have no baggage attributes
+    expect(
+      Object.keys(spans[0]!.attributes).filter((k) => k.startsWith('baggage.')),
+    ).toHaveLength(0);
+  });
+
+  it('should copy multiple baggage entries', async () => {
+    const exporter = new InMemorySpanExporter();
+    const baggageProcessor = new BaggageSpanProcessor();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [baggageProcessor, new SimpleSpanProcessor(exporter)],
+    });
+
+    // Set as global provider
+    trace.setGlobalTracerProvider(provider);
+
+    const tracer = provider.getTracer('test');
+
+    // Set multiple baggage entries
+    const activeContext = context.active();
+    let baggage = propagation.createBaggage();
+    baggage = baggage.setEntry('key1', { value: 'value1' });
+    baggage = baggage.setEntry('key2', { value: 'value2' });
+    baggage = baggage.setEntry('key3', { value: 'value3' });
+    const contextWithBaggage = propagation.setBaggage(activeContext, baggage);
+
+    // Create span within baggage context
+    await new Promise<void>((resolve) => {
+      context.with(contextWithBaggage, () => {
+        tracer.startActiveSpan('test-span', (span) => {
+          span.end();
+          resolve();
+        });
+      });
+    });
+
+    // Flush to ensure spans are exported
+    await provider.forceFlush();
+
+    const spans = exporter.getFinishedSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0]!.attributes['baggage.key1']).toBe('value1');
+    expect(spans[0]!.attributes['baggage.key2']).toBe('value2');
+    expect(spans[0]!.attributes['baggage.key3']).toBe('value3');
+  });
+});

package/src/baggage-span-processor.ts

@@ -0,0 +1,98 @@
+/**
+ * Span processor that copies baggage entries to span attributes
+ *
+ * This makes baggage visible in trace UIs without manual attribute setting.
+ * Enabled via init({ baggage: true }) or init({ baggage: 'custom-prefix' })
+ */
+
+import type { Span, Context } from '@opentelemetry/api';
+import { propagation, context as otelContext } from '@opentelemetry/api';
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+export interface BaggageSpanProcessorOptions {
+  /**
+   * Prefix for baggage attributes
+   * @default 'baggage.'
+   */
+  prefix?: string;
+}
+
+/**
+ * Span processor that automatically copies baggage entries to span attributes
+ *
+ * This makes baggage visible in trace UIs (Jaeger, Grafana, DataDog, etc.)
+ * without manually calling ctx.setAttribute() for each baggage entry.
+ *
+ * @example Enable in init()
+ * ```typescript
+ * init({
+ *   service: 'my-app',
+ *   baggage: true // Uses default 'baggage.' prefix
+ * });
+ *
+ * // Now baggage automatically appears as span attributes
+ * await withBaggage({
+ *   baggage: { 'tenant.id': 't1', 'user.id': 'u1' },
+ *   fn: async () => {
+ *     // Span has baggage.tenant.id and baggage.user.id attributes!
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom prefix
+ * ```typescript
+ * init({
+ *   service: 'my-app',
+ *   baggage: 'ctx' // Uses 'ctx.' prefix
+ * });
+ * // Creates attributes: ctx.tenant.id, ctx.user.id
+ * ```
+ */
+export class BaggageSpanProcessor implements SpanProcessor {
+  private readonly prefix: string;
+
+  constructor(options: BaggageSpanProcessorOptions = {}) {
+    this.prefix = options.prefix ?? 'baggage.';
+  }
+
+  onStart(span: Span, parentContext: Context): void {
+    // Read baggage from parentContext first (spans created with explicit context)
+    // Then fall back to active context (spans created without explicit context)
+    // Also check getActiveContextWithBaggage() to see baggage set via ctx.setBaggage()
+    let baggage = propagation.getBaggage(parentContext);
+    if (!baggage) {
+      baggage = propagation.getBaggage(otelContext.active());
+    }
+    // Check stored context from ctx.setBaggage() if still no baggage
+    if (!baggage) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { getActiveContextWithBaggage } = require('../trace-context');
+        const storedContext = getActiveContextWithBaggage();
+        baggage = propagation.getBaggage(storedContext);
+      } catch {
+        // Fallback if trace-context isn't available
+      }
+    }
+    if (!baggage) return;
+
+    // Copy all baggage entries to span attributes
+    for (const [key, entry] of baggage.getAllEntries()) {
+      span.setAttribute(`${this.prefix}${key}`, entry.value);
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onEnd(_span: ReadableSpan): void {
+    // No-op - required by SpanProcessor interface
+  }
+
+  async shutdown(): Promise<void> {
+    // No-op
+  }
+
+  async forceFlush(): Promise<void> {
+    // No-op
+  }
+}

package/src/circuit-breaker.test.ts

@@ -0,0 +1,341 @@
+/**
+ * Tests for circuit breaker
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  CircuitBreaker,
+  CircuitState,
+  CircuitOpenError,
+} from './circuit-breaker';
+
+describe('CircuitBreaker', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  describe('CLOSED state (normal operation)', () => {
+    it('should execute function successfully when closed', async () => {
+      const cb = new CircuitBreaker('test');
+
+      const result = await cb.execute(async () => 'success');
+
+      expect(result).toBe('success');
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+    });
+
+    it('should record failures but stay closed under threshold', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 5,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // 4 failures (under threshold of 5)
+      for (let i = 0; i < 4; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('test error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+      expect(cb.getFailureCount()).toBe(4);
+    });
+  });
+
+  describe('OPEN state (fast-fail)', () => {
+    it('should open circuit after threshold failures', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 3,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Trigger 3 failures to open circuit
+      for (let i = 0; i < 3; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('adapter error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+      expect(cb.getFailureCount()).toBe(3);
+    });
+
+    it('should fast-fail when circuit is open', async () => {
+      const cb = new CircuitBreaker('test-adapter', {
+        failureThreshold: 2,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Open the circuit
+      for (let i = 0; i < 2; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      // Should fast-fail without calling function
+      await expect(
+        cb.execute(async () => 'should not be called'),
+      ).rejects.toThrow(CircuitOpenError);
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+    });
+
+    it('should transition to half-open after reset timeout', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 2,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Open circuit
+      for (let i = 0; i < 2; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+
+      // Advance time past reset timeout
+      vi.advanceTimersByTime(31_000);
+
+      // Next call should transition to half-open
+      const result = await cb.execute(async () => 'recovered');
+
+      expect(result).toBe('recovered');
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+    });
+  });
+
+  describe('HALF_OPEN state (testing recovery)', () => {
+    it('should close circuit on successful test request', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 2,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Open circuit
+      cb.forceOpen();
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+
+      // Wait for reset timeout
+      vi.advanceTimersByTime(31_000);
+
+      // Successful test request should close circuit
+      await cb.execute(async () => 'success');
+
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+      expect(cb.getFailureCount()).toBe(0);
+    });
+
+    it('should reopen circuit if test request fails', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 1,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Open circuit
+      try {
+        await cb.execute(async () => {
+          throw new Error('error');
+        });
+      } catch {
+        // Expected
+      }
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+
+      // Wait for reset timeout
+      vi.advanceTimersByTime(31_000);
+
+      // Failed test request should reopen circuit
+      try {
+        await cb.execute(async () => {
+          throw new Error('still failing');
+        });
+      } catch {
+        // Expected
+      }
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+    });
+  });
+
+  describe('Time window management', () => {
+    it('should only count failures within time window', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 3,
+        resetTimeout: 30_000,
+        windowSize: 10_000, // 10 second window
+      });
+
+      // Record 2 failures
+      for (let i = 0; i < 2; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      expect(cb.getFailureCount()).toBe(2);
+
+      // Advance time past window
+      vi.advanceTimersByTime(11_000);
+
+      // Old failures should be cleared
+      expect(cb.getFailureCount()).toBe(0);
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+    });
+
+    it('should track failure timestamps correctly', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 5,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Record failures over time
+      for (let i = 0; i < 3; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('error');
+          });
+        } catch {
+          // Expected
+        }
+        vi.advanceTimersByTime(5000); // 5 seconds between failures
+      }
+
+      const failures = cb.getRecentFailures();
+      expect(failures).toHaveLength(3);
+      expect(failures[0]?.error).toBe('error');
+    });
+  });
+
+  describe('Manual control', () => {
+    it('should allow manual reset', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 2,
+        resetTimeout: 30_000,
+        windowSize: 60_000,
+      });
+
+      // Open circuit
+      for (let i = 0; i < 2; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+
+      // Manual reset
+      cb.forceReset();
+
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+      expect(cb.getFailureCount()).toBe(0);
+    });
+
+    it('should allow manual open', () => {
+      const cb = new CircuitBreaker('test');
+
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+
+      cb.forceOpen();
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+    });
+  });
+
+  describe('Configuration', () => {
+    it('should use default config values', () => {
+      const cb = new CircuitBreaker('test');
+
+      // Should use default threshold of 5
+      expect(cb.getFailureCount()).toBe(0);
+      expect(cb.getState()).toBe(CircuitState.CLOSED);
+    });
+
+    it('should allow custom config', async () => {
+      const cb = new CircuitBreaker('test', {
+        failureThreshold: 2,
+        resetTimeout: 5000,
+        windowSize: 10_000,
+      });
+
+      // Should open after 2 failures (custom threshold)
+      for (let i = 0; i < 2; i++) {
+        try {
+          await cb.execute(async () => {
+            throw new Error('error');
+          });
+        } catch {
+          // Expected
+        }
+      }
+
+      expect(cb.getState()).toBe(CircuitState.OPEN);
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should record error messages', async () => {
+      const cb = new CircuitBreaker('test');
+
+      try {
+        await cb.execute(async () => {
+          throw new Error('specific error message');
+        });
+      } catch {
+        // Expected
+      }
+
+      const failures = cb.getRecentFailures();
+      expect(failures[0]?.error).toBe('specific error message');
+    });
+
+    it('should handle non-Error throws', async () => {
+      const cb = new CircuitBreaker('test');
+
+      try {
+        await cb.execute(async () => {
+          throw 'string error';
+        });
+      } catch {
+        // Expected
+      }
+
+      const failures = cb.getRecentFailures();
+      expect(failures[0]?.error).toBe('string error');
+    });
+  });
+});