autotel 2.1.0

package/src/operation-context.ts

@@ -0,0 +1,93 @@
+/**
+ * Operation context tracking using AsyncLocalStorage
+ *
+ * This module provides a way to track operation names across async boundaries
+ * so they can be automatically captured in events events.
+ *
+ * We cannot read span attributes from OpenTelemetry's API (it's write-only),
+ * so we maintain our own async context storage.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Operation context that flows through async operations
+ */
+export interface OperationContext {
+  /**
+   * The name of the current operation
+   * This is set by trace() or span() and can be read by events
+   */
+  name: string;
+}
+
+/**
+ * AsyncLocalStorage instance for tracking operation context
+ */
+const operationStorage = new AsyncLocalStorage<OperationContext>();
+
+/**
+ * Get the current operation context (if any)
+ *
+ * @returns The current operation context, or undefined if not in an operation
+ *
+ * @example
+ * ```typescript
+ * const ctx = getOperationContext();
+ * if (ctx) {
+ *   console.log('Current operation:', ctx.name);
+ * }
+ * ```
+ */
+export function getOperationContext(): OperationContext | undefined {
+  return operationStorage.getStore();
+}
+
+/**
+ * Run a function within an operation context
+ *
+ * This sets the operation name for the duration of the function execution,
+ * including all async operations spawned from it.
+ *
+ * @param name - The operation name to set
+ * @param fn - The function to execute within the context
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await runInOperationContext('user.create', async () => {
+ *   // Any events.trackEvent() calls here will automatically capture
+ *   // 'operation.name': 'user.create'
+ *   await createUser();
+ *   return 'success';
+ * });
+ * ```
+ */
+export function runInOperationContext<T>(name: string, fn: () => T): T {
+  return operationStorage.run({ name }, fn);
+}
+
+/**
+ * Update the operation name in the current context
+ *
+ * This is useful when you want to change the operation name within
+ * an already-established context (e.g., when entering a nested span).
+ *
+ * @param name - The new operation name
+ *
+ * @example
+ * ```typescript
+ * runInOperationContext('parent.operation', () => {
+ *   // operation.name is 'parent.operation'
+ *
+ *   updateOperationName('nested.operation');
+ *   // operation.name is now 'nested.operation'
+ * });
+ * ```
+ */
+export function updateOperationName(name: string): void {
+  const store = operationStorage.getStore();
+  if (store) {
+    store.name = name;
+  }
+}

package/src/processors.ts

@@ -0,0 +1,106 @@
+/**
+ * OpenTelemetry Span Processors
+ *
+ * Re-exports commonly-needed OpenTelemetry span processors for custom configurations.
+ *
+ * These processors are already included in autotel's dependencies, so re-exporting
+ * them provides a "one install is all you need" developer experience without any
+ * bundle size impact.
+ *
+ * Use these when you need custom span processing logic beyond what `init()` provides.
+ *
+ * @example Simple processor (synchronous, for testing)
+ * ```typescript
+ * import { init } from 'autotel'
+ * import { InMemorySpanExporter } from 'autotel/exporters'
+ * import { SimpleSpanProcessor } from 'autotel/processors'
+ *
+ * const exporter = new InMemorySpanExporter()
+ * init({
+ *   service: 'test',
+ *   spanProcessor: new SimpleSpanProcessor(exporter),
+ * })
+ * ```
+ *
+ * @example Batch processor (async batching, for production)
+ * ```typescript
+ * import { init } from 'autotel'
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+ * import { BatchSpanProcessor } from 'autotel/processors'
+ *
+ * const exporter = new OTLPTraceExporter({ url: 'http://collector:4318/v1/traces' })
+ * init({
+ *   service: 'my-app',
+ *   spanProcessor: new BatchSpanProcessor(exporter, {
+ *     maxQueueSize: 2048,
+ *     scheduledDelayMillis: 5000,
+ *     exportTimeoutMillis: 30000,
+ *     maxExportBatchSize: 512,
+ *   }),
+ * })
+ * ```
+ *
+ * Note: Most users don't need to use processors directly - `init()` configures
+ * BatchSpanProcessor by default. Use these when you need custom processing logic.
+ *
+ * @module autotel/processors
+ * @see {@link https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-processor | OTel Span Processor Spec}
+ */
+
+export {
+  /**
+   * Simple span processor - processes spans synchronously.
+   *
+   * Perfect for:
+   * - Unit testing (synchronous span export)
+   * - Development (immediate span visibility)
+   * - Debugging (no batching delays)
+   *
+   * How it works:
+   * - Spans are exported immediately when they end
+   * - No batching or queuing
+   * - Blocking (export happens on the same thread)
+   *
+   * Warning: Not recommended for production - use BatchSpanProcessor instead.
+   * SimpleSpanProcessor can impact performance in high-throughput scenarios.
+   *
+   * @example
+   * ```typescript
+   * import { SimpleSpanProcessor } from 'autotel/processors'
+   * import { ConsoleSpanExporter } from 'autotel/exporters'
+   *
+   * const processor = new SimpleSpanProcessor(new ConsoleSpanExporter())
+   * ```
+   */
+  SimpleSpanProcessor,
+
+  /**
+   * Batch span processor - batches spans before exporting.
+   *
+   * Perfect for:
+   * - Production use (efficient, non-blocking)
+   * - High-throughput applications
+   * - Custom export configurations
+   *
+   * How it works:
+   * - Spans are queued in memory
+   * - Exported in batches at regular intervals
+   * - Non-blocking (export happens on background thread)
+   * - Configurable batch size, delay, queue size
+   *
+   * This is the default processor used by `init()`.
+   *
+   * @example Custom configuration
+   * ```typescript
+   * import { BatchSpanProcessor } from 'autotel/processors'
+   *
+   * const processor = new BatchSpanProcessor(exporter, {
+   *   maxQueueSize: 4096,           // Max spans in queue
+   *   scheduledDelayMillis: 10000,  // Export every 10s
+   *   exportTimeoutMillis: 30000,   // 30s export timeout
+   *   maxExportBatchSize: 1024,     // Max 1024 spans per batch
+   * })
+   * ```
+   */
+  BatchSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';

package/src/rate-limiter.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Tests for token bucket rate limiter
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { TokenBucketRateLimiter } from './rate-limiter';
+
+describe('TokenBucketRateLimiter', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  describe('tryConsume()', () => {
+    it('should allow events within rate limit', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 10,
+        burstCapacity: 20,
+      });
+
+      // Should allow first 20 events (burst capacity)
+      for (let i = 0; i < 20; i++) {
+        expect(limiter.tryConsume()).toBe(true);
+      }
+
+      // 21st event should be rejected
+      expect(limiter.tryConsume()).toBe(false);
+    });
+
+    it('should refill tokens over time', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 10, // 10 events/sec = 1 event/100ms
+        burstCapacity: 10,
+      });
+
+      // Consume all tokens
+      for (let i = 0; i < 10; i++) {
+        expect(limiter.tryConsume()).toBe(true);
+      }
+
+      // Should be rate limited
+      expect(limiter.tryConsume()).toBe(false);
+
+      // Advance time by 100ms (1 token should be added)
+      vi.advanceTimersByTime(100);
+
+      // Should allow 1 more event
+      expect(limiter.tryConsume()).toBe(true);
+      expect(limiter.tryConsume()).toBe(false);
+
+      // Advance time by 500ms (5 tokens should be added)
+      vi.advanceTimersByTime(500);
+
+      // Should allow 5 more events
+      for (let i = 0; i < 5; i++) {
+        expect(limiter.tryConsume()).toBe(true);
+      }
+      expect(limiter.tryConsume()).toBe(false);
+    });
+
+    it('should not exceed max tokens', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 10,
+        burstCapacity: 20,
+      });
+
+      // Wait a long time
+      vi.advanceTimersByTime(10_000);
+
+      // Should only have 20 tokens (burstCapacity), not more
+      expect(limiter.getAvailableTokens()).toBe(20);
+    });
+
+    it('should consume multiple tokens at once', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 100,
+        burstCapacity: 200,
+      });
+
+      // Consume 50 tokens at once
+      expect(limiter.tryConsume(50)).toBe(true);
+      expect(limiter.getAvailableTokens()).toBe(150);
+
+      // Consume another 150 tokens
+      expect(limiter.tryConsume(150)).toBe(true);
+      expect(limiter.getAvailableTokens()).toBe(0);
+
+      // Should reject request for 1 token
+      expect(limiter.tryConsume(1)).toBe(false);
+    });
+  });
+
+  describe('waitForToken()', () => {
+    it('should wait until token is available', async () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 10, // 1 token every 100ms
+        burstCapacity: 1,
+      });
+
+      // Consume the only token
+      expect(limiter.tryConsume()).toBe(true);
+      expect(limiter.tryConsume()).toBe(false);
+
+      // Wait for next token
+      const promise = limiter.waitForToken();
+
+      // Advance time by 100ms
+      vi.advanceTimersByTime(100);
+
+      // Should resolve after 100ms
+      await promise;
+
+      // Token should be consumed
+      expect(limiter.tryConsume()).toBe(false);
+    });
+
+    it('should calculate correct wait time for multiple tokens', async () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 10, // 1 token every 100ms
+        burstCapacity: 10,
+      });
+
+      // Consume all tokens
+      expect(limiter.tryConsume(10)).toBe(true);
+
+      // Request 5 tokens (should wait 500ms)
+      const promise = limiter.waitForToken(5);
+
+      // Advance by 400ms (not enough)
+      vi.advanceTimersByTime(400);
+
+      // Promise should not resolve yet
+      let resolved = false;
+      promise.then(() => {
+        resolved = true;
+      });
+
+      await vi.runAllTimersAsync();
+
+      // Should be resolved now
+      expect(resolved).toBe(true);
+    });
+  });
+
+  describe('getAvailableTokens()', () => {
+    it('should return current token count', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 100,
+        burstCapacity: 200,
+      });
+
+      expect(limiter.getAvailableTokens()).toBe(200);
+
+      limiter.tryConsume(50);
+      expect(limiter.getAvailableTokens()).toBe(150);
+
+      // Advance time by 100ms (10 tokens added)
+      vi.advanceTimersByTime(100);
+      expect(limiter.getAvailableTokens()).toBe(160);
+    });
+  });
+
+  describe('reset()', () => {
+    it('should reset to full capacity', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 10,
+        burstCapacity: 20,
+      });
+
+      // Consume all tokens
+      limiter.tryConsume(20);
+      expect(limiter.getAvailableTokens()).toBe(0);
+
+      // Reset
+      limiter.reset();
+      expect(limiter.getAvailableTokens()).toBe(20);
+    });
+  });
+
+  describe('Burst capacity', () => {
+    it('should default to 2x rate if not specified', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 50,
+        // burstCapacity not specified
+      });
+
+      // Should have 100 tokens (2x rate)
+      expect(limiter.getAvailableTokens()).toBe(100);
+    });
+
+    it('should allow custom burst capacity', () => {
+      const limiter = new TokenBucketRateLimiter({
+        maxEventsPerSecond: 50,
+        burstCapacity: 500, // 10x rate
+      });
+
+      expect(limiter.getAvailableTokens()).toBe(500);
+    });
+  });
+});

package/src/rate-limiter.ts

@@ -0,0 +1,98 @@
+/**
+ * Token bucket rate limiter for event subscribers
+ *
+ * Prevents overwhelming downstream events platforms with too many events.
+ * Uses token bucket algorithm for smooth rate limiting with burst capacity.
+ */
+
+export interface RateLimiterConfig {
+  /** Maximum events per second (default: 100) */
+  maxEventsPerSecond: number;
+  /** Burst capacity - max events in a single burst (default: 2x rate) */
+  burstCapacity?: number;
+}
+
+/**
+ * Token bucket rate limiter
+ *
+ * Allows bursts up to burstCapacity, then smooths to maxEventsPerSecond.
+ * Thread-safe for async operations.
+ */
+export class TokenBucketRateLimiter {
+  private tokens: number;
+  private readonly maxTokens: number;
+  private readonly refillRate: number; // tokens per millisecond
+  private lastRefill: number;
+
+  constructor(config: RateLimiterConfig) {
+    this.maxTokens = config.burstCapacity || config.maxEventsPerSecond * 2;
+    this.tokens = this.maxTokens; // Start with full bucket
+    this.refillRate = config.maxEventsPerSecond / 1000; // Convert to per-ms
+    this.lastRefill = Date.now();
+  }
+
+  /**
+   * Try to consume a token (allow an event)
+   * Returns true if allowed, false if rate limit exceeded
+   */
+  tryConsume(count = 1): boolean {
+    this.refill();
+
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Wait until a token is available (async rate limiting)
+   * Returns a promise that resolves when the event can be processed
+   */
+  async waitForToken(count = 1): Promise<void> {
+    this.refill();
+
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      return;
+    }
+
+    // Calculate wait time until we have enough tokens
+    const tokensNeeded = count - this.tokens;
+    const waitMs = Math.ceil(tokensNeeded / this.refillRate);
+
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+
+    // After waiting, try again (recursive)
+    return this.waitForToken(count);
+  }
+
+  /**
+   * Refill tokens based on elapsed time
+   */
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    const tokensToAdd = elapsed * this.refillRate;
+
+    this.tokens = Math.min(this.maxTokens, this.tokens + tokensToAdd);
+    this.lastRefill = now;
+  }
+
+  /**
+   * Get current available tokens (for testing/debugging)
+   */
+  getAvailableTokens(): number {
+    this.refill();
+    return Math.floor(this.tokens);
+  }
+
+  /**
+   * Reset the rate limiter (for testing)
+   */
+  reset(): void {
+    this.tokens = this.maxTokens;
+    this.lastRefill = Date.now();
+  }
+}