@od-oneapp/analytics 2026.1.1301

package/src/shared/utils/rate-limit.ts

@@ -0,0 +1,289 @@
+/**
+ * @fileoverview Rate limiting utilities for analytics calls
+ * Rate limiting utilities for analytics calls
+ *
+ * Prevents overwhelming provider APIs, hitting rate limits, and excessive costs.
+ * Uses token bucket algorithm for smooth rate limiting with bursts.
+ *
+ * @module rate-limit
+ */
+
+import { logWarn } from '@repo/shared/logger';
+
+/**
+ * Rate limiter configuration
+ */
+export interface RateLimiterConfig {
+  /** Maximum number of calls per window */
+  maxCalls: number;
+  /** Window size in milliseconds */
+  windowMs: number;
+  /** Maximum number of concurrent calls */
+  maxConcurrent?: number;
+  /** Whether to queue excess calls or drop them */
+  queueExcess?: boolean;
+  /** Maximum queue size */
+  maxQueueSize?: number;
+}
+
+/**
+ * Rate limiter for analytics calls
+ *
+ * Implements token bucket algorithm with optional call queuing.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({
+ *   maxCalls: 100,
+ *   windowMs: 1000, // 100 calls per second
+ *   maxConcurrent: 10,
+ * });
+ *
+ * // Check if call is allowed
+ * if (await limiter.tryAcquire()) {
+ *   await analytics.track('Event');
+ *   limiter.release();
+ * }
+ *
+ * // Or use wrapper
+ * await limiter.execute(() => analytics.track('Event'));
+ * ```
+ */
+export class RateLimiter {
+  private callCount = 0;
+  private concurrentCount = 0;
+  private windowStart = Date.now();
+  private queue: Array<() => void> = [];
+  private readonly config: Required<RateLimiterConfig>;
+
+  constructor(config: RateLimiterConfig) {
+    this.config = {
+      maxCalls: config.maxCalls,
+      windowMs: config.windowMs,
+      maxConcurrent: config.maxConcurrent ?? Infinity,
+      queueExcess: config.queueExcess ?? false,
+      maxQueueSize: config.maxQueueSize ?? 1000,
+    };
+  }
+
+  /**
+   * Try to acquire a rate limit token
+   *
+   * @returns Promise resolving to whether the call is allowed
+   */
+  async tryAcquire(): Promise<boolean> {
+    // Reset window if needed
+    const now = Date.now();
+    if (now - this.windowStart >= this.config.windowMs) {
+      this.callCount = 0;
+      this.windowStart = now;
+    }
+
+    // Check rate limit
+    if (this.callCount >= this.config.maxCalls) {
+      if (this.config.queueExcess && this.queue.length < this.config.maxQueueSize) {
+        // Queue the call - will re-check rate limit when dequeued
+        return new Promise<boolean>(resolve => {
+          this.queue.push(() => {
+            // Re-check rate limit when dequeued to prevent bypassing
+            const now = Date.now();
+            if (now - this.windowStart >= this.config.windowMs) {
+              this.callCount = 0;
+              this.windowStart = now;
+            }
+            if (this.callCount < this.config.maxCalls) {
+              this.callCount++;
+              resolve(true);
+            } else {
+              resolve(false);
+            }
+          });
+        });
+      }
+
+      if (process.env.NODE_ENV === 'development') {
+        logWarn('Rate limit exceeded', {
+          maxCalls: this.config.maxCalls,
+          windowMs: this.config.windowMs,
+          currentCount: this.callCount,
+        });
+      }
+
+      return false;
+    }
+
+    // Check concurrency limit
+    if (this.concurrentCount >= this.config.maxConcurrent) {
+      if (this.config.queueExcess && this.queue.length < this.config.maxQueueSize) {
+        // Queue the call
+        return new Promise<boolean>(resolve => {
+          this.queue.push(() => resolve(true));
+        });
+      }
+
+      return false;
+    }
+
+    this.callCount++;
+    this.concurrentCount++;
+    return true;
+  }
+
+  /**
+   * Release a rate limit token
+   */
+  release(): void {
+    this.concurrentCount = Math.max(0, this.concurrentCount - 1);
+
+    // Process queue - only process if concurrency allows and rate limit allows
+    if (this.queue.length > 0 && this.concurrentCount < this.config.maxConcurrent) {
+      // Reset rate limit window if needed before processing queue
+      const now = Date.now();
+      if (now - this.windowStart >= this.config.windowMs) {
+        this.callCount = 0;
+        this.windowStart = now;
+      }
+
+      // Only process if rate limit allows
+      if (this.callCount < this.config.maxCalls) {
+        const next = this.queue.shift();
+        if (next) {
+          this.concurrentCount++;
+          next();
+        }
+      }
+    }
+  }
+
+  /**
+   * Execute a function with rate limiting
+   *
+   * @param fn - Function to execute
+   * @returns Promise resolving to function result
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T | null> {
+    const allowed = await this.tryAcquire();
+
+    if (!allowed) {
+      return null;
+    }
+
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+
+  /**
+   * Get current rate limiter stats
+   */
+  getStats(): {
+    callCount: number;
+    concurrentCount: number;
+    queueSize: number;
+    remainingCalls: number;
+    windowStart: number;
+  } {
+    return {
+      callCount: this.callCount,
+      concurrentCount: this.concurrentCount,
+      queueSize: this.queue.length,
+      remainingCalls: Math.max(0, this.config.maxCalls - this.callCount),
+      windowStart: this.windowStart,
+    };
+  }
+
+  /**
+   * Reset the rate limiter
+   */
+  reset(): void {
+    this.callCount = 0;
+    this.concurrentCount = 0;
+    this.windowStart = Date.now();
+    this.queue = [];
+  }
+}
+
+/**
+ * Simple in-memory rate limiter using Map
+ *
+ * Useful for per-provider or per-user rate limiting.
+ */
+export class MapRateLimiter {
+  private limiters = new Map<string, RateLimiter>();
+  private readonly config: RateLimiterConfig;
+
+  constructor(config: RateLimiterConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Get or create a rate limiter for a key
+   */
+  private getLimiter(key: string): RateLimiter {
+    let limiter = this.limiters.get(key);
+
+    if (!limiter) {
+      limiter = new RateLimiter(this.config);
+      this.limiters.set(key, limiter);
+    }
+
+    return limiter;
+  }
+
+  /**
+   * Try to acquire a rate limit token for a key
+   */
+  async tryAcquire(key: string): Promise<boolean> {
+    return this.getLimiter(key).tryAcquire();
+  }
+
+  /**
+   * Release a rate limit token for a key
+   */
+  release(key: string): void {
+    this.getLimiter(key).release();
+  }
+
+  /**
+   * Execute a function with rate limiting for a key
+   */
+  async execute<T>(key: string, fn: () => Promise<T>): Promise<T | null> {
+    return this.getLimiter(key).execute(fn);
+  }
+
+  /**
+   * Get stats for a key
+   */
+  getStats(key: string): ReturnType<RateLimiter['getStats']> | null {
+    const limiter = this.limiters.get(key);
+    return limiter ? limiter.getStats() : null;
+  }
+
+  /**
+   * Reset rate limiter for a key
+   */
+  reset(key: string): void {
+    const limiter = this.limiters.get(key);
+    if (limiter) {
+      limiter.reset();
+    }
+  }
+
+  /**
+   * Clean up old limiters (call periodically)
+   */
+  cleanup(maxAge: number = 60000): void {
+    const now = Date.now();
+
+    for (const [key, limiter] of this.limiters.entries()) {
+      const stats = limiter.getStats();
+
+      // Remove if inactive for maxAge
+      if (now - stats.windowStart > maxAge && stats.callCount === 0 && stats.queueSize === 0) {
+        this.limiters.delete(key);
+      }
+    }
+  }
+}