@od-oneapp/ai-platform 0.1.0

package/src/governance/entitlements/rate-limiter.ts

@@ -0,0 +1,711 @@
+/**
+ * Rate Limiting Implementation
+ * Multiple strategies for request rate limiting: sliding window, token bucket, fixed window
+ *
+ * FEATURES:
+ * - Token bucket algorithm
+ * - Sliding window counter
+ * - Fixed window counter
+ * - Distributed rate limiting support (Redis ready)
+ * - Per-key rate limiting (user, IP, organization)
+ * - Graceful degradation
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+/**
+ * Request object interface
+ */
+export interface Request {
+  /** Request identifier (user ID, IP address, etc.) */
+  key: string;
+
+  /** Request metadata */
+  [key: string]: unknown;
+}
+
+const RATE_LIMIT_KEY_ERROR = 'Rate limit key must be a non-empty string';
+
+function resolveRateLimitKey(req: Request, keyGenerator: (req: Request) => string): string {
+  const key = keyGenerator(req);
+
+  if (typeof key !== 'string' || key.trim().length === 0) {
+    throw new Error(RATE_LIMIT_KEY_ERROR);
+  }
+
+  return key;
+}
+
+/**
+ * Rate limiter configuration
+ */
+export interface RateLimitConfig {
+  /** Time window in milliseconds */
+  windowMs: number;
+
+  /** Maximum requests in window */
+  maxRequests: number;
+
+  /** Function to extract rate limit key from request */
+  keyGenerator: (req: Request) => string;
+
+  /** Skip rate limiting for certain requests */
+  skip?: (req: Request) => boolean;
+
+  /** Custom handler for rate limit exceeded */
+  onRateLimitExceeded?: (req: Request, key: string) => void;
+
+  /** Enable debug logging */
+  enableLogging?: boolean;
+}
+
+/**
+ * Token bucket configuration
+ */
+export interface TokenBucketConfig {
+  /** Maximum tokens in bucket */
+  capacity: number;
+
+  /** Tokens added per second */
+  refillRate: number;
+
+  /** Optional: check if refill should be skipped */
+  skipRefill?: () => boolean;
+}
+
+/**
+ * Sliding window limiter configuration
+ */
+export interface SlidingWindowLimiterConfig {
+  /** Time window in milliseconds */
+  windowMs: number;
+
+  /** Maximum requests in window */
+  maxRequests: number;
+
+  /** Enable logging */
+  enableLogging?: boolean;
+}
+
+/**
+ * Rate limit response
+ */
+export interface RateLimitResponse {
+  /** Whether the request is allowed */
+  allowed: boolean;
+
+  /** Remaining requests in current window */
+  remaining: number;
+
+  /** Total limit for the window */
+  limit: number;
+
+  /** Retry-After header value in seconds */
+  retryAfter?: number;
+
+  /** When the limit resets (Unix timestamp in ms) */
+  resetAt: number;
+}
+
+/**
+ * Token bucket limiter
+ */
+export interface TokenBucket {
+  /** Check if request can proceed */
+  canConsume(tokens?: number): boolean;
+
+  /** Consume tokens */
+  consume(tokens?: number): RateLimitResponse;
+
+  /** Get current tokens */
+  getTokens(): number;
+
+  /** Reset bucket */
+  reset(): void;
+
+  /** Get bucket stats */
+  getStats(): TokenBucketStats;
+}
+
+/**
+ * Token bucket statistics
+ */
+export interface TokenBucketStats {
+  /** Current tokens in bucket */
+  currentTokens: number;
+
+  /** Bucket capacity */
+  capacity: number;
+
+  /** Tokens per second refill rate */
+  refillRate: number;
+
+  /** Time until bucket is full (ms) */
+  timeToFullMs: number;
+
+  /** Requests processed */
+  requestsProcessed: number;
+
+  /** Requests rejected */
+  requestsRejected: number;
+}
+
+/**
+ * Sliding window limiter
+ */
+export interface SlidingWindowLimiter {
+  /** Check if request can proceed */
+  canConsume(key: string, tokens?: number): boolean;
+
+  /** Consume tokens/requests */
+  consume(key: string, tokens?: number): Promise<RateLimitResponse>;
+
+  /** Get usage stats for key */
+  getStats(key: string): Promise<SlidingWindowStats>;
+
+  /** Reset usage for key */
+  reset(key: string): void | Promise<void>;
+
+  /** Clear all entries */
+  clear(): void | Promise<void>;
+}
+
+/**
+ * Sliding window statistics
+ */
+export interface SlidingWindowStats {
+  /** Requests in current window */
+  count: number;
+
+  /** Limit for window */
+  limit: number;
+
+  /** Time until window resets (ms) */
+  resetInMs: number;
+
+  /** Percentage of quota used */
+  usagePercent: number;
+
+  /** Window start time (Unix timestamp ms) */
+  windowStartAt: number;
+}
+
+/**
+ * Generic rate limiter interface
+ */
+export interface RateLimiter {
+  /** Check if request can proceed */
+  isAllowed(req: Request): Promise<boolean>;
+
+  /** Process request and get limit status */
+  process(req: Request): Promise<RateLimitResponse>;
+
+  /** Reset limits for a key */
+  reset(key: string): Promise<void>;
+
+  /** Get current stats for a key */
+  getStats(key: string): Promise<RateLimitResponse>;
+
+  /** Clear all entries */
+  clear(): Promise<void>;
+}
+
+/**
+ * Storage backend for distributed rate limiting
+ */
+export interface RateLimitStorage {
+  /** Get current count for key in window */
+  getCount(key: string): Promise<number>;
+
+  /** Increment count for key */
+  increment(key: string, amount?: number): Promise<number>;
+
+  /** Get window start time for key */
+  getWindowStart(key: string): Promise<number | null>;
+
+  /** Set window start time for key */
+  setWindowStart(key: string, time: number): Promise<void>;
+
+  /** Reset entry for key */
+  reset(key: string): Promise<void>;
+
+  /** Set expiration for key (Unix timestamp ms) */
+  setExpiration(key: string, expiresAt: number): Promise<void>;
+
+  /** Clear all entries */
+  clear(): Promise<void>;
+}
+
+/**
+ * Create a sliding window rate limiter
+ *
+ * @param config - Sliding window configuration
+ * @param storage - Optional storage backend (defaults to in-memory)
+ * @returns Sliding window limiter
+ *
+ * @example
+ * ```typescript
+ * const limiter = createSlidingWindowLimiter({
+ *   windowMs: 60000,
+ *   maxRequests: 100,
+ *   enableLogging: true
+ * });
+ *
+ * // Check if request can proceed
+ * const canProceed = limiter.canConsume('user-123');
+ * if (canProceed) {
+ *   limiter.consume('user-123');
+ * }
+ * ```
+ */
+export function createSlidingWindowLimiter(
+  config: SlidingWindowLimiterConfig,
+  storage?: RateLimitStorage,
+): SlidingWindowLimiter {
+  const logger = config.enableLogging ? logInfo : () => {};
+  const store = storage || createInMemoryStorage();
+
+  return {
+    canConsume(key: string, tokens: number = 1): boolean {
+      // Note: This is synchronous, in-memory check only
+      // For distributed scenarios, use async version
+      return tokens > 0;
+    },
+
+    async consume(key: string, tokens: number = 1): Promise<RateLimitResponse> {
+      const now = Date.now();
+      let windowStart = await store.getWindowStart(key);
+      let count = await store.getCount(key);
+
+      // Check if window has expired
+      if (windowStart && now - windowStart > config.windowMs) {
+        // Reset window
+        windowStart = now;
+        count = 0;
+        await store.setWindowStart(key, now);
+      } else if (!windowStart) {
+        windowStart = now;
+        await store.setWindowStart(key, now);
+      }
+
+      // Check if we can consume
+      const allowed = count + tokens <= config.maxRequests;
+
+      if (allowed) {
+        const newCount = await store.increment(key, tokens);
+        const remaining = Math.max(0, config.maxRequests - newCount);
+        const resetAt = windowStart + config.windowMs;
+
+        logger(
+          `[RateLimit] Request allowed for ${key}: ${newCount}/${config.maxRequests}, resets in ${resetAt - now}ms`,
+        );
+
+        return {
+          allowed: true,
+          remaining,
+          limit: config.maxRequests,
+          resetAt,
+        };
+      }
+
+      // Limit exceeded
+      const resetAt = windowStart + config.windowMs;
+      const retryAfter = Math.ceil((resetAt - now) / 1000);
+
+      logger(
+        `[RateLimit] Rate limit exceeded for ${key}: ${count}/${config.maxRequests}, retry after ${retryAfter}s`,
+      );
+
+      // Set expiration on the key
+      await store.setExpiration(key, resetAt);
+
+      return {
+        allowed: false,
+        remaining: 0,
+        limit: config.maxRequests,
+        retryAfter,
+        resetAt,
+      };
+    },
+
+    async getStats(key: string): Promise<SlidingWindowStats> {
+      const count = await store.getCount(key);
+      const windowStart = await store.getWindowStart(key);
+      const now = Date.now();
+
+      const actualWindowStart = windowStart || now;
+      const resetInMs = actualWindowStart + config.windowMs - now;
+      const usagePercent = (count / config.maxRequests) * 100;
+
+      return {
+        count,
+        limit: config.maxRequests,
+        resetInMs: Math.max(0, resetInMs),
+        usagePercent,
+        windowStartAt: actualWindowStart,
+      };
+    },
+
+    async reset(key: string): Promise<void> {
+      await store.reset(key);
+      logger(`[RateLimit] Reset limits for key: ${key}`);
+    },
+
+    async clear(): Promise<void> {
+      await store.clear();
+      logger('[RateLimit] Cleared all rate limit entries');
+    },
+  };
+}
+
+/**
+ * Create a token bucket rate limiter
+ *
+ * @param capacity - Maximum tokens in bucket
+ * @param refillRate - Tokens to add per second
+ * @returns Token bucket instance
+ *
+ * @example
+ * ```typescript
+ * const bucket = createTokenBucket(100, 10);
+ *
+ * // Try to consume 5 tokens
+ * if (bucket.canConsume(5)) {
+ *   bucket.consume(5);
+ * }
+ * ```
+ */
+export function createTokenBucket(capacity: number, refillRate: number): TokenBucket {
+  let tokens = capacity;
+  let lastRefill = Date.now();
+  let requestsProcessed = 0;
+  let requestsRejected = 0;
+
+  const refill = () => {
+    const now = Date.now();
+    const timePassed = (now - lastRefill) / 1000; // seconds
+    const tokensToAdd = timePassed * refillRate;
+
+    tokens = Math.min(capacity, tokens + tokensToAdd);
+    lastRefill = now;
+  };
+
+  return {
+    canConsume(tokensNeeded: number = 1): boolean {
+      refill();
+      return tokens >= tokensNeeded;
+    },
+
+    consume(tokensNeeded: number = 1): RateLimitResponse {
+      refill();
+
+      if (tokens >= tokensNeeded) {
+        tokens -= tokensNeeded;
+        requestsProcessed++;
+
+        const timeToFullMs =
+          refillRate > 0 && tokens < capacity ? ((capacity - tokens) / refillRate) * 1000 : 0;
+
+        return {
+          allowed: true,
+          remaining: Math.floor(tokens),
+          limit: capacity,
+          resetAt: Date.now() + timeToFullMs,
+        };
+      }
+
+      requestsRejected++;
+
+      // Calculate when tokens will be available
+      const tokensNeeded_ = tokensNeeded - tokens;
+      const secondsToWait = tokensNeeded_ / refillRate;
+      const retryAfter = Math.ceil(secondsToWait);
+
+      return {
+        allowed: false,
+        remaining: Math.floor(tokens),
+        limit: capacity,
+        retryAfter,
+        resetAt: Date.now() + secondsToWait * 1000,
+      };
+    },
+
+    getTokens(): number {
+      refill();
+      return Math.floor(tokens);
+    },
+
+    reset(): void {
+      tokens = capacity;
+      lastRefill = Date.now();
+    },
+
+    getStats(): TokenBucketStats {
+      refill();
+
+      const timeToFullMs =
+        refillRate > 0 && tokens < capacity ? ((capacity - tokens) / refillRate) * 1000 : 0;
+
+      return {
+        currentTokens: Math.floor(tokens),
+        capacity,
+        refillRate,
+        timeToFullMs,
+        requestsProcessed,
+        requestsRejected,
+      };
+    },
+  };
+}
+
+/**
+ * Create a rate limiter with sliding window algorithm
+ * This is the main factory function for most use cases
+ *
+ * @param config - Rate limit configuration
+ * @param storage - Optional storage backend
+ * @returns RateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,        // 1 minute
+ *   maxRequests: 100,
+ *   keyGenerator: (req) => req.userId || req.ip,
+ *   enableLogging: true
+ * });
+ *
+ * const allowed = await limiter.isAllowed({
+ *   key: 'user-123'
+ * });
+ * ```
+ */
+export function createRateLimiter(
+  config: RateLimitConfig,
+  storage?: RateLimitStorage,
+): RateLimiter {
+  const logger = config.enableLogging ? logInfo : () => {};
+  const slidingWindow = createSlidingWindowLimiter(
+    {
+      windowMs: config.windowMs,
+      maxRequests: config.maxRequests,
+      enableLogging: config.enableLogging,
+    },
+    storage,
+  );
+
+  return {
+    async isAllowed(req: Request): Promise<boolean> {
+      // Skip if configured
+      if (config.skip?.(req)) {
+        return true;
+      }
+
+      const key = resolveRateLimitKey(req, config.keyGenerator);
+      const result = await slidingWindow.consume(key);
+
+      if (!result.allowed) {
+        config.onRateLimitExceeded?.(req, key);
+        logger(`[RateLimiter] Rate limit exceeded for key: ${key}`);
+      }
+
+      return result.allowed;
+    },
+
+    async process(req: Request): Promise<RateLimitResponse> {
+      if (config.skip?.(req)) {
+        return {
+          allowed: true,
+          remaining: config.maxRequests,
+          limit: config.maxRequests,
+          resetAt: Date.now() + config.windowMs,
+        };
+      }
+
+      const key = resolveRateLimitKey(req, config.keyGenerator);
+      const result = await slidingWindow.consume(key);
+
+      if (!result.allowed) {
+        config.onRateLimitExceeded?.(req, key);
+      }
+
+      return result;
+    },
+
+    async reset(key: string): Promise<void> {
+      await slidingWindow.reset(key);
+      logger(`[RateLimiter] Reset rate limits for key: ${key}`);
+    },
+
+    async getStats(key: string): Promise<RateLimitResponse> {
+      const stats = await slidingWindow.getStats(key);
+      return {
+        allowed: stats.count < stats.limit,
+        remaining: Math.max(0, stats.limit - stats.count),
+        limit: stats.limit,
+        resetAt: stats.windowStartAt + config.windowMs,
+      };
+    },
+
+    async clear(): Promise<void> {
+      await slidingWindow.clear();
+      logger('[RateLimiter] Cleared all rate limit entries');
+    },
+  };
+}
+
+/**
+ * Create fixed window rate limiter (simpler, less precise)
+ * Good for simple per-minute rate limits
+ *
+ * @param windowMs - Window duration in milliseconds
+ * @param maxRequests - Max requests per window
+ * @returns RateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createFixedWindowLimiter(60000, 100);
+ * ```
+ */
+export function createFixedWindowLimiter(
+  windowMs: number,
+  maxRequests: number,
+): SlidingWindowLimiter {
+  return createSlidingWindowLimiter({
+    windowMs,
+    maxRequests,
+  });
+}
+
+/**
+ * Create in-memory storage backend for rate limiting
+ * Suitable for single-instance deployments
+ *
+ * @returns RateLimitStorage instance
+ */
+function createInMemoryStorage(): RateLimitStorage {
+  const store = new Map<string, { count: number; windowStart: number; expiresAt?: number }>();
+
+  // Cleanup expired entries periodically
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, data] of store.entries()) {
+      if (data.expiresAt && data.expiresAt < now) {
+        store.delete(key);
+      }
+    }
+  }, 60000); // Every minute
+  void cleanupInterval;
+
+  return {
+    async getCount(key: string): Promise<number> {
+      const data = store.get(key);
+      return data?.count || 0;
+    },
+
+    async increment(key: string, amount: number = 1): Promise<number> {
+      const data = store.get(key) || { count: 0, windowStart: Date.now() };
+      data.count += amount;
+      store.set(key, data);
+      return data.count;
+    },
+
+    async getWindowStart(key: string): Promise<number | null> {
+      const data = store.get(key);
+      return data?.windowStart || null;
+    },
+
+    async setWindowStart(key: string, time: number): Promise<void> {
+      const data = store.get(key) || { count: 0, windowStart: time };
+      data.windowStart = time;
+      store.set(key, data);
+    },
+
+    async reset(key: string): Promise<void> {
+      store.delete(key);
+    },
+
+    async setExpiration(key: string, expiresAt: number): Promise<void> {
+      const data = store.get(key);
+      if (data) {
+        data.expiresAt = expiresAt;
+      }
+    },
+
+    async clear(): Promise<void> {
+      store.clear();
+    },
+  };
+}
+
+/**
+ * Create distributed rate limiting storage with Redis
+ * For multi-instance deployments
+ *
+ * @param redisClient - Redis client instance (ioredis or similar)
+ * @param keyPrefix - Optional key prefix for namespacing
+ * @returns RateLimitStorage instance
+ *
+ * @example
+ * ```typescript
+ * const redis = new Redis();
+ * const storage = createRedisStorage(redis, 'ratelimit:');
+ * const limiter = createRateLimiter(config, storage);
+ * ```
+ */
+import type { RedisClientExtended as RedisClient } from '../../integrations/redis';
+
+export function createRedisStorage(
+  redisClient: RedisClient,
+  keyPrefix: string = 'ratelimit:',
+): RateLimitStorage {
+  const TTL = 86400; // 24 hours
+
+  return {
+    async getCount(key: string): Promise<number> {
+      const value = await redisClient.get(`${keyPrefix}count:${key}`);
+      return value ? parseInt(value, 10) : 0;
+    },
+
+    async increment(key: string, amount: number = 1): Promise<number> {
+      const countKey = `${keyPrefix}count:${key}`;
+      const newCount = await redisClient.incrby(countKey, amount);
+      await redisClient.expire(countKey, TTL);
+      return newCount;
+    },
+
+    async getWindowStart(key: string): Promise<number | null> {
+      const value = await redisClient.get(`${keyPrefix}window:${key}`);
+      return value ? parseInt(value, 10) : null;
+    },
+
+    async setWindowStart(key: string, time: number): Promise<void> {
+      const windowKey = `${keyPrefix}window:${key}`;
+      await redisClient.set(windowKey, String(time));
+      await redisClient.expire(windowKey, TTL);
+    },
+
+    async reset(key: string): Promise<void> {
+      await redisClient.del(`${keyPrefix}count:${key}`);
+      await redisClient.del(`${keyPrefix}window:${key}`);
+    },
+
+    async setExpiration(key: string, expiresAt: number): Promise<void> {
+      const countKey = `${keyPrefix}count:${key}`;
+      const ttl = Math.ceil((expiresAt - Date.now()) / 1000);
+      if (ttl > 0) {
+        await redisClient.expire(countKey, ttl);
+      }
+    },
+
+    async clear(): Promise<void> {
+      const pattern = `${keyPrefix}*`;
+      const keys = await redisClient.keys(pattern);
+      if (keys.length > 0) {
+        await redisClient.del(...keys);
+      }
+    },
+  };
+}
+
+// Re-export types