autotel 2.1.0

package/src/event-queue.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Tests for events queue guardrails
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { EventQueue } from './event-queue';
+
+// Mock adapter for testing
+type MockEvent = {
+  name: string;
+  attributes?: Record<string, unknown>;
+};
+
+class MockAdapter {
+  public events: MockEvent[] = [];
+  public callCount = 0;
+  public shouldFail = false;
+
+  async trackEvent(
+    name: string,
+    attributes?: Record<string, unknown>,
+  ): Promise<void> {
+    this.callCount++;
+    if (this.shouldFail) {
+      throw new Error('Adapter failed');
+    }
+    this.events.push({ name, attributes });
+  }
+
+  async trackFunnelStep(): Promise<void> {}
+  async trackOutcome(): Promise<void> {}
+  async trackValue(): Promise<void> {}
+}
+
+describe('EventQueue', () => {
+  let mockAdapter: MockAdapter;
+  let queue: EventQueue;
+
+  beforeEach(() => {
+    mockAdapter = new MockAdapter();
+    queue = new EventQueue([mockAdapter], {
+      maxSize: 10,
+      batchSize: 3,
+      flushInterval: 100,
+      maxRetries: 2,
+    });
+  });
+
+  describe('Batching', () => {
+    it('should enqueue events without immediate sending', () => {
+      queue.enqueue({ name: 'test1', attributes: {}, timestamp: Date.now() });
+      queue.enqueue({ name: 'test2', attributes: {}, timestamp: Date.now() });
+
+      expect(queue.size()).toBe(2);
+      expect(mockAdapter.callCount).toBe(0); // Not sent yet
+    });
+
+    it('should flush after interval', async () => {
+      queue.enqueue({ name: 'test1', attributes: {}, timestamp: Date.now() });
+      queue.enqueue({ name: 'test2', attributes: {}, timestamp: Date.now() });
+
+      // Wait for flush interval
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      expect(queue.size()).toBe(0);
+      expect(mockAdapter.events.length).toBeGreaterThan(0);
+    });
+
+    it('should batch events efficiently', async () => {
+      // Enqueue 5 events (batch size is 3)
+      for (let i = 0; i < 5; i++) {
+        queue.enqueue({
+          name: `test${i}`,
+          attributes: {},
+          timestamp: Date.now(),
+        });
+      }
+
+      // Manual flush
+      await queue.flush();
+
+      expect(queue.size()).toBe(0);
+      expect(mockAdapter.events.length).toBe(5);
+    });
+  });
+
+  describe('Backpressure', () => {
+    it('should drop oldest when queue is full in production', () => {
+      const originalEnv = process.env.NODE_ENV;
+      process.env.NODE_ENV = 'production';
+
+      // Fill queue to max (10 events)
+      for (let i = 0; i < 12; i++) {
+        queue.enqueue({
+          name: `test${i}`,
+          attributes: { index: i },
+          timestamp: Date.now(),
+        });
+      }
+
+      // Queue should be at max size
+      expect(queue.size()).toBe(10);
+
+      process.env.NODE_ENV = originalEnv;
+    });
+
+    it('should drop oldest and log when queue is full (consistent behavior)', () => {
+      // Fill queue to max
+      for (let i = 0; i < 10; i++) {
+        queue.enqueue({
+          name: `test${i}`,
+          attributes: {},
+          timestamp: Date.now(),
+        });
+      }
+
+      // Next enqueue should drop oldest (not throw)
+      expect(() => {
+        queue.enqueue({
+          name: 'test11',
+          attributes: {},
+          timestamp: Date.now(),
+        });
+      }).not.toThrow();
+
+      // Verify queue is still at max size
+      expect(queue['queue']).toHaveLength(10);
+    });
+  });
+
+  describe('Retry logic', () => {
+    it('should retry on failure', async () => {
+      mockAdapter.shouldFail = true;
+
+      queue.enqueue({ name: 'test1', attributes: {}, timestamp: Date.now() });
+
+      await queue.flush();
+
+      // Should have tried maxRetries + 1 times (initial + 2 retries = 3)
+      expect(mockAdapter.callCount).toBeGreaterThanOrEqual(3);
+    });
+
+    it('should succeed after transient failure', async () => {
+      let failCount = 0;
+      mockAdapter.trackEvent = async () => {
+        if (failCount < 2) {
+          failCount++;
+          throw new Error('Transient failure');
+        }
+        mockAdapter.events.push({ name: 'test', attributes: {} });
+      };
+
+      queue.enqueue({ name: 'test1', attributes: {}, timestamp: Date.now() });
+
+      await queue.flush();
+
+      // Should eventually succeed
+      expect(mockAdapter.events.length).toBe(1);
+    });
+  });
+
+  describe('Graceful flush', () => {
+    it('should flush all remaining events', async () => {
+      for (let i = 0; i < 5; i++) {
+        queue.enqueue({
+          name: `test${i}`,
+          attributes: {},
+          timestamp: Date.now(),
+        });
+      }
+
+      expect(queue.size()).toBe(5);
+
+      await queue.flush();
+
+      expect(queue.size()).toBe(0);
+      expect(mockAdapter.events.length).toBe(5);
+    });
+
+    it('should handle empty queue flush', async () => {
+      await expect(queue.flush()).resolves.not.toThrow();
+    });
+  });
+
+  describe('Multiple adapters', () => {
+    it('should send to all adapters', async () => {
+      const adapter1 = new MockAdapter();
+      const adapter2 = new MockAdapter();
+      const multiQueue = new EventQueue([adapter1, adapter2]);
+
+      multiQueue.enqueue({
+        name: 'test1',
+        attributes: {},
+        timestamp: Date.now(),
+      });
+
+      await multiQueue.flush();
+
+      expect(adapter1.events.length).toBe(1);
+      expect(adapter2.events.length).toBe(1);
+    });
+
+    it('should handle partial adapter failures', async () => {
+      const adapter1 = new MockAdapter();
+      const adapter2 = new MockAdapter();
+      adapter1.shouldFail = true; // One adapter fails
+
+      const multiQueue = new EventQueue([adapter1, adapter2], {
+        maxRetries: 1,
+      });
+
+      multiQueue.enqueue({
+        name: 'test1',
+        attributes: {},
+        timestamp: Date.now(),
+      });
+
+      // Should not throw, just log error
+      await expect(multiQueue.flush()).resolves.not.toThrow();
+    });
+  });
+});

package/src/event-queue.ts

@@ -0,0 +1,203 @@
+/**
+ * Events event queue with batching, backpressure, retry logic, and rate limiting
+ */
+
+import type { EventSubscriber, EventAttributes } from './event-subscriber';
+import { getLogger } from './init';
+import { TokenBucketRateLimiter, type RateLimiterConfig } from './rate-limiter';
+
+export interface EventData {
+  name: string;
+  attributes?: EventAttributes;
+  timestamp: number;
+}
+
+export interface QueueConfig {
+  maxSize: number; // Max events in queue (default: 50,000)
+  batchSize: number; // Events per batch (default: 100)
+  flushInterval: number; // Flush interval in ms (default: 10,000)
+  maxRetries: number; // Max retry attempts (default: 3)
+  rateLimit?: RateLimiterConfig; // Optional rate limiting (default: 100 events/sec)
+}
+
+const DEFAULT_CONFIG: QueueConfig = {
+  maxSize: 50_000,
+  batchSize: 100,
+  flushInterval: 10_000,
+  maxRetries: 3,
+  rateLimit: {
+    maxEventsPerSecond: 100,
+    burstCapacity: 200,
+  },
+};
+
+/**
+ * Events queue with batching and backpressure
+ *
+ * Features:
+ * - Batches events for efficient sending
+ * - Bounded queue with drop-oldest policy (prod) or blocking (dev)
+ * - Exponential backoff retry
+ * - Rate limiting to prevent overwhelming subscribers
+ * - Graceful flush on shutdown
+ */
+export class EventQueue {
+  private queue: EventData[] = [];
+  private flushTimer: NodeJS.Timeout | null = null;
+  private readonly config: QueueConfig;
+  private readonly subscribers: EventSubscriber[];
+  private readonly rateLimiter: TokenBucketRateLimiter | null;
+  private flushing = false;
+
+  constructor(subscribers: EventSubscriber[], config?: Partial<QueueConfig>) {
+    this.subscribers = subscribers;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+
+    // Initialize rate limiter if configured
+    this.rateLimiter = this.config.rateLimit
+      ? new TokenBucketRateLimiter(this.config.rateLimit)
+      : null;
+  }
+
+  /**
+   * Enqueue an event for sending
+   *
+   * Backpressure policy:
+   * - Drops oldest event and logs warning if queue is full (same behavior in all environments)
+   */
+  enqueue(event: EventData): void {
+    // Check queue size
+    if (this.queue.length >= this.config.maxSize) {
+      // Drop oldest event and log warning (same behavior in all environments)
+      const droppedEvent = this.queue.shift();
+      getLogger().warn(
+        `[autotel] Events queue full (${this.config.maxSize} events). ` +
+          'Dropping oldest event. Events are being produced faster than they can be sent. ' +
+          'Check your subscribers or reduce tracking frequency.',
+        { droppedEvent: droppedEvent?.name },
+      );
+    }
+
+    this.queue.push(event);
+    this.scheduleBatchFlush();
+  }
+
+  /**
+   * Schedule a batch flush if not already scheduled
+   */
+  private scheduleBatchFlush(): void {
+    if (this.flushTimer || this.flushing) return;
+
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flushBatch();
+    }, this.config.flushInterval);
+  }
+
+  /**
+   * Flush a batch of events
+   */
+  private async flushBatch(): Promise<void> {
+    if (this.queue.length === 0 || this.flushing) return;
+
+    this.flushing = true;
+
+    try {
+      const batch = this.queue.splice(0, this.config.batchSize);
+      await this.sendWithRetry(batch, this.config.maxRetries);
+    } finally {
+      this.flushing = false;
+
+      // Schedule next flush if more events
+      if (this.queue.length > 0) {
+        this.scheduleBatchFlush();
+      }
+    }
+  }
+
+  /**
+   * Send events with exponential backoff retry
+   */
+  private async sendWithRetry(
+    events: EventData[],
+    retriesLeft: number,
+  ): Promise<void> {
+    try {
+      await this.sendToSubscribers(events);
+    } catch (error) {
+      if (retriesLeft > 0) {
+        // Exponential backoff: 1s, 2s, 4s
+        const delay = Math.pow(2, this.config.maxRetries - retriesLeft) * 1000;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.sendWithRetry(events, retriesLeft - 1);
+      } else {
+        // Give up after max retries
+        // Always log failed retries to maintain visibility (same behavior in all environments)
+        getLogger().error(
+          '[autotel] Failed to send events after retries',
+          error instanceof Error ? error : undefined,
+          { retriesAttempted: this.config.maxRetries },
+        );
+      }
+    }
+  }
+
+  /**
+   * Send events to all configured subscribers with rate limiting
+   */
+  private async sendToSubscribers(events: EventData[]): Promise<void> {
+    // If rate limiting is disabled, send all at once
+    if (!this.rateLimiter) {
+      const promises = events.map((event) =>
+        Promise.all(
+          this.subscribers.map((subscriber) =>
+            subscriber.trackEvent(event.name, event.attributes),
+          ),
+        ),
+      );
+      await Promise.all(promises);
+      return;
+    }
+
+    // With rate limiting: wait for token before sending each event
+    for (const event of events) {
+      // Wait for rate limiter token (smooth traffic)
+      await this.rateLimiter.waitForToken();
+
+      // Send to all subscribers concurrently
+      await Promise.all(
+        this.subscribers.map((subscriber) =>
+          subscriber.trackEvent(event.name, event.attributes),
+        ),
+      );
+    }
+  }
+
+  /**
+   * Flush all remaining events (for shutdown)
+   */
+  async flush(): Promise<void> {
+    // Cancel any pending timer
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Wait for any in-progress flush to complete
+    while (this.flushing) {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+
+    // Flush all batches
+    while (this.queue.length > 0) {
+      await this.flushBatch();
+    }
+  }
+
+  /**
+   * Get queue size (for testing/debugging)
+   */
+  size(): number {
+    return this.queue.length;
+  }
+}

package/src/event-subscriber.ts

@@ -0,0 +1,136 @@
+/**
+ * Event Subscriber Interface (Type-only)
+ *
+ * Import this interface to create custom subscribers without importing implementations.
+ * Keeps core package focused on OpenTelemetry with zero extra dependencies.
+ *
+ * For ready-made subscribers (PostHog, Mixpanel, Amplitude, Segment),
+ * see the separate `autotel-subscribers` package.
+ *
+ * @example Custom subscriber
+ * ```typescript
+ * import { EventSubscriber } from 'autotel/event-subscriber';
+ *
+ * class MyCustomSubscriber implements EventSubscriber {
+ *   trackEvent(name: string, attributes?: Record<string, any>): void {
+ *     // Send to your events platform
+ *   }
+ *   // ... implement other methods
+ * }
+ * ```
+ *
+ * @example Use pre-built subscribers
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
+ * import { MixpanelSubscriber } from 'autotel-subscribers/mixpanel';
+ *
+ * const event =new Event('checkout', {
+ *   subscribers: [
+ *     new PostHogSubscriber({ apiKey: 'phc_...' }),
+ *     new MixpanelSubscriber({ token: '...' })
+ *   ]
+ * });
+ * ```
+ */
+
+/**
+ * Event attributes (supports any JSON-serializable values)
+ */
+export type EventAttributes = Record<string, string | number | boolean>;
+
+/**
+ * Funnel step status
+ */
+export type FunnelStatus = 'started' | 'completed' | 'abandoned' | 'failed';
+
+/**
+ * Outcome status
+ */
+export type OutcomeStatus = 'success' | 'failure' | 'partial';
+
+/**
+ * Event subscriber interface
+ *
+ * Implement this to send events to any platform.
+ * Zero runtime dependencies - just types.
+ *
+ * All tracking methods are async to support:
+ * - Backpressure signaling (buffer full)
+ * - Streaming platforms (Kafka, Kinesis, Pub/Sub)
+ * - Await delivery confirmation
+ * - Proper error propagation
+ */
+export interface EventSubscriber {
+  /**
+   * Track an event (e.g., "user.registered", "order.created")
+   *
+   * @returns Promise that resolves when event is sent (or buffered)
+   */
+  trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+
+  /**
+   * Track a funnel step (e.g., checkout: started → completed)
+   *
+   * @returns Promise that resolves when event is sent (or buffered)
+   */
+  trackFunnelStep(
+    funnelName: string,
+    step: FunnelStatus,
+    attributes?: EventAttributes,
+  ): Promise<void>;
+
+  /**
+   * Track an outcome (e.g., "payment.processing" → success/failure)
+   *
+   * @returns Promise that resolves when event is sent (or buffered)
+   */
+  trackOutcome(
+    operationName: string,
+    outcome: OutcomeStatus,
+    attributes?: EventAttributes,
+  ): Promise<void>;
+
+  /**
+   * Track a value/metric (e.g., revenue, cart value)
+   *
+   * @returns Promise that resolves when event is sent (or buffered)
+   */
+  trackValue(
+    name: string,
+    value: number,
+    attributes?: EventAttributes,
+  ): Promise<void>;
+
+  /**
+   * Optional: Flush pending events and clean up resources
+   *
+   * Implement this if your subscriber buffers events, maintains connections,
+   * or needs cleanup before shutdown. Called during graceful shutdown.
+   *
+   * @example
+   * ```typescript
+   * class MySubscriber implements EventSubscriber {
+   *   async shutdown(): Promise<void> {
+   *     await this.flushBuffer();
+   *     await this.closeConnections();
+   *   }
+   * }
+   * ```
+   */
+  shutdown?(): Promise<void>;
+
+  /**
+   * Optional: Subscriber name for debugging and error reporting
+   *
+   * @example "PostHogSubscriber", "SnowflakeSubscriber", "CustomWebhookSubscriber"
+   */
+  readonly name?: string;
+
+  /**
+   * Optional: Subscriber version for debugging
+   *
+   * @example "1.0.0"
+   */
+  readonly version?: string;
+}