te.js 1.3.0 → 2.0.0

package/rate-limit/base.js

@@ -0,0 +1,165 @@
+import TejError from '../server/error.js';
+import MemoryStorage from './storage/memory.js';
+import RedisStorage from './storage/redis.js';
+import dbManager from '../database/index.js';
+
+/**
+ * Base rate limiter class implementing common functionality for rate limiting algorithms
+ *
+ * @abstract
+ * @class
+ * @description
+ * This is the base class for all rate limiting algorithms. It provides common configuration
+ * options and storage handling, while allowing specific algorithms to implement their own logic.
+ * Only one algorithm can be active per instance - the algorithm is determined by which options
+ * object is provided (tokenBucketConfig, slidingWindowConfig, or fixedWindowConfig).
+ *
+ * @example
+ * // Using with Redis storage and token bucket algorithm
+ * const limiter = new TokenBucketRateLimiter({
+ *   maxRequests: 10,
+ *   timeWindowSeconds: 60,
+ *   store: 'redis',
+ *   tokenBucketConfig: {
+ *     refillRate: 0.5,
+ *     burstSize: 15
+ *   }
+ * });
+ */
+class RateLimiter {
+  /**
+   * Creates a new rate limiter instance
+   *
+   * @param {Object} options - Configuration options for the rate limiter
+   * @param {number} [options.maxRequests=60] - Maximum number of requests allowed within the time window.
+   *                                           This is the default rate limit cap that applies across all algorithms.
+   *                                           For token bucket, this affects the default refill rate.
+   * @param {number} [options.timeWindowSeconds=60] - Time window in seconds for rate limiting.
+   *                                                 For fixed window, this is the window duration.
+   *                                                 For sliding window, this is the total time span considered.
+   *                                                 For token bucket, this affects the default refill rate calculation.
+   * @param {string} [options.keyPrefix='rl:'] - Prefix for storage keys. Useful when implementing different rate limit
+   *                                           rules with different prefixes (e.g., 'rl:api:', 'rl:web:').
+   * @param {string} [options.store='memory'] - Storage backend to use ('memory' or 'redis')
+   * @param {Object} [options.tokenBucketConfig] - Token bucket algorithm specific options
+   * @param {Object} [options.slidingWindowConfig] - Sliding window algorithm specific options
+   * @param {Object} [options.fixedWindowConfig] - Fixed window algorithm specific options
+   */
+  constructor(options) {
+    // Common options for all algorithms
+    this.options = {
+      maxRequests: 60, // Maximum number of requests
+      timeWindowSeconds: 60, // Time window in seconds
+      keyPrefix: 'rl:', // Key prefix for storage
+      store: 'memory', // Default to memory storage
+      ...options,
+    };
+
+    // Only one algorithm can be active per instance
+    if (options?.tokenBucketConfig && options?.slidingWindowConfig) {
+      throw new TejError(
+        400,
+        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
+      );
+    }
+
+    if (options?.tokenBucketConfig && options?.fixedWindowConfig) {
+      throw new TejError(
+        500,
+        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
+      );
+    }
+
+    if (options?.slidingWindowConfig && options?.fixedWindowConfig) {
+      throw new TejError(
+        500,
+        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
+      );
+    }
+
+    // Set default values for algorithm options if any are provided
+    this.tokenBucketOptions = options?.tokenBucketConfig
+      ? {
+          refillRate: this.options.maxRequests / this.options.timeWindowSeconds, // Tokens per second
+          burstSize: this.options.maxRequests, // Maximum token capacity
+          ...options.tokenBucketConfig,
+        }
+      : null;
+
+    this.slidingWindowOptions = options?.slidingWindowConfig
+      ? {
+          granularity: 1, // Time precision in seconds
+          weights: { current: 1, previous: 0 }, // Weights for current and previous windows
+          ...options.slidingWindowConfig,
+        }
+      : null;
+
+    this.fixedWindowOptions = options?.fixedWindowConfig
+      ? {
+          strictWindow: false, // If true, windows align with clock
+          ...options.fixedWindowConfig,
+        }
+      : null;
+
+    // Initialize storage based on store type
+    if (this.options.store === 'redis') {
+      if (!dbManager.hasConnection('redis')) {
+        throw new TejError(
+          500,
+          'Redis store selected but no Redis connection available. Call withRedis() first.',
+        );
+      }
+      const redisClient = dbManager.getConnection('redis');
+      this.storage = new RedisStorage(redisClient);
+    } else {
+      this.storage = new MemoryStorage();
+    }
+  }
+
+  /**
+   * Generate storage key for the rate limit identifier
+   *
+   * @param {string} identifier - Unique identifier for the rate limit (e.g. IP address, user ID)
+   * @returns {string} The storage key with prefix
+   */
+  getKey(identifier) {
+    return `${this.options.keyPrefix}${identifier}`;
+  }
+
+  /**
+   * Abstract method for checking if request is allowed
+   * Must be implemented by concrete rate limiter classes
+   *
+   * @abstract
+   * @param {string} identifier - Unique identifier for the rate limit (e.g. IP address, user ID)
+   * @returns {Promise<Object>} Rate limit check result
+   * @returns {boolean} result.success - Whether the request is allowed
+   * @returns {number} result.remainingRequests - Number of requests remaining in the window
+   * @returns {number} result.resetTime - Unix timestamp when the rate limit resets
+   * @throws {Error} If not implemented by child class
+   */
+  async consume(identifier) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Get algorithm-specific options for the specified algorithm type
+   *
+   * @param {string} type - Algorithm type ('tokenBucketConfig', 'slidingWindowConfig', or 'fixedWindowConfig')
+   * @returns {Object|null} The algorithm-specific options, or null if type not found
+   */
+  getAlgorithmOptions(type) {
+    switch (type) {
+      case 'token-bucket':
+        return this.tokenBucketOptions;
+      case 'sliding-window':
+        return this.slidingWindowOptions;
+      case 'fixed-window':
+        return this.fixedWindowOptions;
+      default:
+        return null;
+    }
+  }
+}
+
+export default RateLimiter;

package/rate-limit/index.js

@@ -0,0 +1,147 @@
+import TejError from '../server/error.js';
+import FixedWindowRateLimiter from './algorithms/fixed-window.js';
+import SlidingWindowRateLimiter from './algorithms/sliding-window.js';
+import TokenBucketRateLimiter from './algorithms/token-bucket.js';
+import dbManager from '../database/index.js';
+
+/**
+ * Creates a rate limiting middleware function with the specified algorithm and storage
+ *
+ * @param {Object} options - Configuration options for the rate limiter
+ * @param {number} options.maxRequests - Maximum number of requests allowed within the time window
+ * @param {number} options.timeWindowSeconds - Time window in seconds
+ * @param {string} [options.algorithm='sliding-window'] - Rate limiting algorithm to use:
+ *                                                     - 'token-bucket': Best for handling traffic bursts
+ *                                                     - 'sliding-window': Best for smooth rate limiting
+ *                                                     - 'fixed-window': Simplest approach
+ * @param {string} [options.store='memory'] - Storage backend to use:
+ *                                         - 'memory': In-memory storage (default)
+ *                                         - 'redis': Redis-based storage (requires global Redis config)
+ * @param {Object} [options.algorithmOptions] - Algorithm-specific options
+ * @param {Function} [options.keyGenerator] - Optional function to generate unique identifiers
+ * @param {Object} [options.headerFormat] - Rate limit header format configuration
+ * @param {string} [options.headerFormat.type='standard'] - Type of headers to use:
+ *                                                       - 'legacy': Use X-RateLimit-* headers
+ *                                                       - 'standard': Use RateLimit-* headers (draft 6+)
+ *                                                       - 'both': Use both legacy and standard headers
+ * @param {boolean} [options.headerFormat.draft7=false] - Whether to include draft 7 policy header
+ * @param {boolean} [options.headerFormat.draft8=false] - Whether to include draft 8 reset format
+ * @param {Function} [options.onRateLimited] - Optional callback when rate limit is exceeded
+ * @returns {Function} Middleware function for use with te.js
+ */
+function rateLimiter(options) {
+  const {
+    algorithm = 'sliding-window',
+    store = 'memory',
+    keyGenerator = (ammo) => ammo.ip,
+    headerFormat = { type: 'standard' },
+    onRateLimited,
+    ...limiterOptions
+  } = options;
+
+  // Check Redis connectivity if Redis store is selected
+  if (store === 'redis' && !dbManager.hasConnection('redis', {})) {
+    throw new TejError(
+      400,
+      'Redis store selected but no Redis connection found. Please use withRedis() before using withRateLimit()',
+    );
+  }
+
+  // Map algorithm names to their config property names
+  const configMap = {
+    'token-bucket': 'tokenBucketConfig',
+    'sliding-window': 'slidingWindowConfig',
+    'fixed-window': 'fixedWindowConfig',
+  };
+
+  const configKey = configMap[algorithm];
+  if (!configKey) {
+    throw new TejError(
+      400,
+      `Invalid algorithm: ${algorithm}. Must be one of: ${Object.keys(configMap).join(', ')}`,
+    );
+  }
+
+  // Create algorithm-specific config
+  const limiterConfig = {
+    maxRequests: limiterOptions.maxRequests,
+    timeWindowSeconds: limiterOptions.timeWindowSeconds,
+    [configKey]: limiterOptions.algorithmOptions || {},
+    store, // Pass the store type to the limiter
+  };
+
+  // Create the appropriate limiter instance
+  let limiter;
+  switch (algorithm) {
+    case 'token-bucket':
+      limiter = new TokenBucketRateLimiter(limiterConfig);
+      break;
+    case 'sliding-window':
+      limiter = new SlidingWindowRateLimiter(limiterConfig);
+      break;
+    case 'fixed-window':
+      limiter = new FixedWindowRateLimiter(limiterConfig);
+      break;
+    default:
+      throw new TejError(400, 'Invalid algorithm specified');
+  }
+
+  // Helper to set headers based on format
+  const setRateLimitHeaders = (ammo, result) => {
+    const { type = 'standard', draft7 = false, draft8 = false } = headerFormat;
+    const useStandard = type === 'standard' || type === 'both';
+    const useLegacy = type === 'legacy' || type === 'both';
+
+    if (useStandard) {
+      // Standard headers (draft 6+)
+      ammo.res.setHeader('RateLimit-Limit', limiter.options.maxRequests);
+      ammo.res.setHeader('RateLimit-Remaining', result.remainingRequests);
+
+      // Draft 8 uses delta-seconds format
+      if (draft8) {
+        const resetDelta = result.resetTime - Math.floor(Date.now() / 1000);
+        ammo.res.setHeader('RateLimit-Reset', resetDelta);
+      } else {
+        ammo.res.setHeader('RateLimit-Reset', result.resetTime);
+      }
+
+      // Draft 7 added optional policy information
+      if (draft7) {
+        const policy = `${limiter.options.maxRequests};w=${limiter.options.timeWindowSeconds}`;
+        ammo.res.setHeader('RateLimit-Policy', policy);
+      }
+    }
+
+    if (useLegacy) {
+      // Legacy X- headers
+      ammo.res.setHeader('X-RateLimit-Limit', limiter.options.maxRequests);
+      ammo.res.setHeader('X-RateLimit-Remaining', result.remainingRequests);
+      ammo.res.setHeader('X-RateLimit-Reset', result.resetTime);
+    }
+
+    // Always set Retry-After on 429 responses
+    if (!result.success) {
+      const retryAfter = result.resetTime - Math.floor(Date.now() / 1000);
+      ammo.res.setHeader('Retry-After', retryAfter);
+    }
+  };
+
+  // Return middleware function
+  return async (ammo, next) => {
+    const key = keyGenerator(ammo);
+    const result = await limiter.consume(key);
+
+    setRateLimitHeaders(ammo, result);
+
+    if (!result.success) {
+      if (onRateLimited) {
+        return onRateLimited(ammo);
+      }
+      return ammo.throw(429, 'Too Many Requests');
+    }
+
+    await next();
+  };
+}
+
+export default rateLimiter;

package/rate-limit/storage/base.js

@@ -0,0 +1,104 @@
+import TejError from '../../server/error.js';
+
+/**
+ * Abstract base class for rate limiter storage backends
+ *
+ * @abstract
+ * @description
+ * Defines the interface that all storage implementations must follow.
+ * Storage backends are responsible for persisting rate limit data and handling
+ * data expiration. Two implementations are provided out of the box:
+ * - MemoryStorage: For single-instance applications and testing
+ * - RedisStorage: For distributed applications
+ *
+ * Custom storage implementations can be created by extending this class
+ * and implementing all required methods.
+ *
+ * @example
+ * // Custom storage implementation
+ * class MyCustomStorage extends RateLimitStorage {
+ *   async get(key) {
+ *     // Implementation
+ *   }
+ *   async set(key, value, ttl) {
+ *     // Implementation
+ *   }
+ *   async increment(key) {
+ *     // Implementation
+ *   }
+ *   async delete(key) {
+ *     // Implementation
+ *   }
+ * }
+ */
+class RateLimitStorage {
+  /**
+   * Retrieve rate limit data for a given key
+   *
+   * @abstract
+   * @param {string} key - The storage key to retrieve data for
+   * @returns {Promise<Object|null>} The stored data, or null if not found
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * const data = await storage.get('rl:127.0.0.1');
+   * if (data) {
+   *   console.log('Found rate limit data:', data);
+   * }
+   */
+  async get(key) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Store rate limit data with optional expiration
+   *
+   * @abstract
+   * @param {string} key - The storage key to store data under
+   * @param {Object} value - The data to store
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * await storage.set('rl:127.0.0.1', { counter: 5 }, 60);
+   */
+  async set(key, value, ttl) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Increment a numeric value in storage
+   *
+   * @abstract
+   * @param {string} key - The storage key to increment
+   * @returns {Promise<number|null>} The new value after increment, or null if key not found
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * const newValue = await storage.increment('rl:127.0.0.1');
+   * if (newValue !== null) {
+   *   console.log('New counter value:', newValue);
+   * }
+   */
+  async increment(key) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Delete data for a given key
+   *
+   * @abstract
+   * @param {string} key - The storage key to delete
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * await storage.delete('rl:127.0.0.1');
+   */
+  async delete(key) {
+    throw new TejError(500, 'Not implemented');
+  }
+}
+
+export default RateLimitStorage;

package/rate-limit/storage/memory.js

@@ -0,0 +1,102 @@
+import RateLimitStorage from './base.js';
+
+/**
+ * In-memory storage implementation for rate limiting
+ * 
+ * @extends RateLimitStorage
+ * @description
+ * This storage backend uses a JavaScript Map to store rate limit data in memory.
+ * It's suitable for single-instance applications or testing environments, but not 
+ * recommended for production use in distributed systems as data is not shared
+ * between instances.
+ * 
+ * Key features:
+ * - Fast access (all data in memory)
+ * - Automatic cleanup of expired entries
+ * - No external dependencies
+ * - Data is lost on process restart
+ * - Not suitable for distributed systems
+ * 
+ * @example
+ * import { TokenBucketRateLimiter, MemoryStorage } from 'te.js/rate-limit';
+ * 
+ * // Memory storage is used by default if no redis config is provided
+ * const limiter = new TokenBucketRateLimiter({
+ *   maxRequests: 60,
+ *   timeWindowSeconds: 60,
+ *   tokenBucketConfig: {
+ *     refillRate: 1,
+ *     burstSize: 60
+ *   }
+ * });
+ * 
+ * // Or create storage instance explicitly
+ * const storage = new MemoryStorage();
+ * await storage.set('key', { counter: 5 }, 60); // Store for 60 seconds
+ */
+class MemoryStorage extends RateLimitStorage {
+  /**
+   * Initialize a new memory storage instance
+   */
+  constructor() {
+    super();
+    this.store = new Map();
+  }
+
+  /**
+   * Get stored data for a key, handling expiration
+   * 
+   * @param {string} key - The storage key to retrieve data for
+   * @returns {Promise<Object|null>} The stored data, or null if not found or expired
+   */
+  async get(key) {
+    const item = this.store.get(key);
+    if (!item) return null;
+    if (item.expireAt < Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return item.value;
+  }
+
+  /**
+   * Store data with expiration time
+   * 
+   * @param {string} key - The storage key
+   * @param {Object} value - The data to store
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<void>}
+   */
+  async set(key, value, ttl) {
+    this.store.set(key, {
+      value,
+      expireAt: Date.now() + ttl * 1000
+    });
+  }
+
+  /**
+   * Increment a numeric value in storage
+   * 
+   * @param {string} key - The storage key to increment
+   * @returns {Promise<number|null>} New value after increment, or null if key not found/expired
+   */
+  async increment(key) {
+    const item = await this.get(key);
+    if (!item) return null;
+    item.counter = (item.counter || 0) + 1;
+    await this.set(key, item, (item.expireAt - Date.now()) / 1000);
+    return item.counter;
+  }
+
+  /**
+   * Delete data for a key
+   * 
+   * @param {string} key - The storage key to delete
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    this.store.delete(key);
+  }
+}
+
+export default MemoryStorage;

package/rate-limit/storage/redis.js

@@ -0,0 +1,88 @@
+import RateLimitStorage from './base.js';
+
+/**
+ * Redis storage implementation for rate limiting
+ *
+ * @extends RateLimitStorage
+ * @description
+ * This storage backend uses Redis for distributed rate limiting across multiple application instances.
+ * It's the recommended storage backend for production use in distributed systems as it provides
+ * reliable rate limiting across all application instances.
+ *
+ * Key features:
+ * - Distributed rate limiting (works across multiple app instances)
+ * - Atomic operations for race condition prevention
+ * - Automatic key expiration using Redis TTL
+ * - Persistence options available through Redis configuration
+ * - Clustering support for high availability
+ *
+ * @example
+ * import { TokenBucketRateLimiter } from 'te.js/rate-limit';
+ *
+ * // Use Redis storage for distributed rate limiting
+ * const limiter = new TokenBucketRateLimiter({
+ *   maxRequests: 100,
+ *   timeWindowSeconds: 60,
+ *   store: 'redis', // Use Redis storage
+ *   tokenBucketConfig: {
+ *     refillRate: 2,
+ *     burstSize: 100
+ *   }
+ * });
+ */
+class RedisStorage extends RateLimitStorage {
+  /**
+   * Initialize Redis storage with client
+   *
+   * @param {RedisClient} client - Connected Redis client instance
+   */
+  constructor(client) {
+    super();
+    this.client = client;
+  }
+
+  /**
+   * Get stored data for a key
+   *
+   * @param {string} key - The storage key to retrieve
+   * @returns {Promise<Object|null>} Stored value if found, null otherwise
+   */
+  async get(key) {
+    const value = await this.client.get(key);
+    return value ? JSON.parse(value) : null;
+  }
+
+  /**
+   * Store data with expiration time
+   *
+   * @param {string} key - The storage key
+   * @param {Object} value - The data to store
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<void>}
+   */
+  async set(key, value, ttl) {
+    await this.client.set(key, JSON.stringify(value), { EX: ttl });
+  }
+
+  /**
+   * Increment a counter value atomically
+   *
+   * @param {string} key - The storage key to increment
+   * @returns {Promise<number>} New value after increment
+   */
+  async increment(key) {
+    return await this.client.incr(key);
+  }
+
+  /**
+   * Delete data for a key
+   *
+   * @param {string} key - The storage key to delete
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    await this.client.del(key);
+  }
+}
+
+export default RedisStorage;