@qwickapps/server 1.3.1 → 1.5.0

package/src/plugins/rate-limit/rate-limit-service.ts

@@ -0,0 +1,228 @@
+/**
+ * Rate Limit Service
+ *
+ * Core service that coordinates between cache and store,
+ * selects strategies, and provides the programmatic API.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  RateLimitStore,
+  RateLimitCache,
+  RateLimitStrategy,
+  LimitStatus,
+  CheckLimitOptions,
+  StrategyContext,
+} from './types.js';
+import { getStrategy } from './strategies/index.js';
+
+/**
+ * Default configuration values
+ */
+const DEFAULTS = {
+  windowMs: 60000, // 1 minute
+  maxRequests: 100,
+  strategy: 'sliding-window' as RateLimitStrategy,
+};
+
+/**
+ * Service configuration
+ */
+export interface RateLimitServiceConfig {
+  store: RateLimitStore;
+  cache: RateLimitCache;
+  defaults?: {
+    windowMs?: number;
+    maxRequests?: number;
+    strategy?: RateLimitStrategy;
+  };
+}
+
+/**
+ * Rate Limit Service
+ *
+ * Provides the core rate limiting functionality with caching.
+ */
+export class RateLimitService {
+  private store: RateLimitStore;
+  private cache: RateLimitCache;
+  private defaults: Required<NonNullable<RateLimitServiceConfig['defaults']>>;
+
+  constructor(config: RateLimitServiceConfig) {
+    this.store = config.store;
+    this.cache = config.cache;
+    this.defaults = {
+      windowMs: config.defaults?.windowMs ?? DEFAULTS.windowMs,
+      maxRequests: config.defaults?.maxRequests ?? DEFAULTS.maxRequests,
+      strategy: config.defaults?.strategy ?? DEFAULTS.strategy,
+    };
+  }
+
+  /**
+   * Check if a key is rate limited
+   */
+  async isLimited(key: string, options?: CheckLimitOptions): Promise<boolean> {
+    const status = await this.checkLimit(key, { ...options, increment: false });
+    return status.limited;
+  }
+
+  /**
+   * Check rate limit status without incrementing
+   */
+  async checkLimit(key: string, options?: CheckLimitOptions): Promise<LimitStatus> {
+    const {
+      maxRequests = this.defaults.maxRequests,
+      windowMs = this.defaults.windowMs,
+      strategy: strategyName = this.defaults.strategy,
+      userId,
+      tenantId,
+      ipAddress,
+      increment = false,
+    } = options || {};
+
+    const strategy = getStrategy(strategyName);
+    const context: StrategyContext = {
+      store: this.store,
+      cache: this.cache,
+      userId,
+      tenantId,
+      ipAddress,
+    };
+
+    return strategy.check(key, { maxRequests, windowMs, increment }, context);
+  }
+
+  /**
+   * Increment the rate limit counter and return status
+   */
+  async incrementLimit(key: string, options?: CheckLimitOptions): Promise<LimitStatus> {
+    return this.checkLimit(key, { ...options, increment: true });
+  }
+
+  /**
+   * Get remaining requests for a key
+   */
+  async getRemainingRequests(key: string, options?: CheckLimitOptions): Promise<number> {
+    const status = await this.checkLimit(key, { ...options, increment: false });
+    return status.remaining;
+  }
+
+  /**
+   * Get full limit status for a key
+   */
+  async getLimitStatus(key: string, options?: CheckLimitOptions): Promise<LimitStatus> {
+    return this.checkLimit(key, { ...options, increment: false });
+  }
+
+  /**
+   * Clear a rate limit (e.g., after successful CAPTCHA)
+   */
+  async clearLimit(key: string, userId?: string): Promise<void> {
+    // Clear from both cache and store
+    await Promise.all([
+      this.cache.delete(key),
+      this.store.clear(key, userId),
+    ]);
+  }
+
+  /**
+   * Get the current defaults
+   */
+  getDefaults(): { windowMs: number; maxRequests: number; strategy: RateLimitStrategy } {
+    return { ...this.defaults };
+  }
+
+  /**
+   * Update the default settings at runtime
+   */
+  setDefaults(updates: Partial<{ windowMs: number; maxRequests: number; strategy: RateLimitStrategy }>): void {
+    if (updates.windowMs !== undefined && updates.windowMs > 0) {
+      this.defaults.windowMs = updates.windowMs;
+    }
+    if (updates.maxRequests !== undefined && updates.maxRequests > 0) {
+      this.defaults.maxRequests = updates.maxRequests;
+    }
+    if (updates.strategy !== undefined) {
+      // Validate strategy
+      const validStrategies: RateLimitStrategy[] = ['sliding-window', 'fixed-window', 'token-bucket'];
+      if (validStrategies.includes(updates.strategy)) {
+        this.defaults.strategy = updates.strategy;
+      }
+    }
+  }
+
+  /**
+   * Run cleanup of expired limits
+   */
+  async cleanup(): Promise<number> {
+    return this.store.cleanup();
+  }
+}
+
+// Global service instance for helper functions
+let currentService: RateLimitService | null = null;
+
+/**
+ * Set the current rate limit service instance
+ * (Called by the plugin on startup)
+ */
+export function setRateLimitService(service: RateLimitService | null): void {
+  currentService = service;
+}
+
+/**
+ * Get the current rate limit service instance
+ */
+export function getRateLimitService(): RateLimitService {
+  if (!currentService) {
+    throw new Error('Rate limit plugin not initialized. Did you register the rate limit plugin?');
+  }
+  return currentService;
+}
+
+// ============================================
+// Programmatic API (convenience functions)
+// ============================================
+
+/**
+ * Check if a key is currently rate limited
+ */
+export async function isLimited(key: string, options?: CheckLimitOptions): Promise<boolean> {
+  return getRateLimitService().isLimited(key, options);
+}
+
+/**
+ * Check rate limit status without incrementing counter
+ */
+export async function checkLimit(key: string, options?: CheckLimitOptions): Promise<LimitStatus> {
+  return getRateLimitService().checkLimit(key, options);
+}
+
+/**
+ * Increment the rate limit counter and return status
+ */
+export async function incrementLimit(key: string, options?: CheckLimitOptions): Promise<LimitStatus> {
+  return getRateLimitService().incrementLimit(key, options);
+}
+
+/**
+ * Get remaining requests for a key
+ */
+export async function getRemainingRequests(key: string, options?: CheckLimitOptions): Promise<number> {
+  return getRateLimitService().getRemainingRequests(key, options);
+}
+
+/**
+ * Get full limit status for a key
+ */
+export async function getLimitStatus(key: string, options?: CheckLimitOptions): Promise<LimitStatus> {
+  return getRateLimitService().getLimitStatus(key, options);
+}
+
+/**
+ * Clear a rate limit (e.g., after successful CAPTCHA)
+ */
+export async function clearLimit(key: string, userId?: string): Promise<void> {
+  return getRateLimitService().clearLimit(key, userId);
+}

package/src/plugins/rate-limit/stores/cache-store.ts

@@ -0,0 +1,261 @@
+/**
+ * Rate Limit Cache Store
+ *
+ * Provides a caching layer for rate limits using either Redis (via cache plugin)
+ * or an in-memory fallback with LRU eviction.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  RateLimitCache,
+  RateLimitCacheConfig,
+  CachedLimit,
+} from '../types.js';
+import { hasCache, getCache } from '../../cache-plugin.js';
+
+/**
+ * Simple LRU Cache implementation for in-memory fallback
+ */
+class LRUCache<T> {
+  private cache = new Map<string, { value: T; expiresAt: number }>();
+  private maxSize: number;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    // Check expiration
+    if (entry.expiresAt <= Date.now()) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry.value;
+  }
+
+  set(key: string, value: T, ttlMs: number): void {
+    // Remove oldest entries if at capacity
+    while (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      } else {
+        break;
+      }
+    }
+
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs,
+    });
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (entry.expiresAt <= Date.now()) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+}
+
+/**
+ * Create a Redis-based cache (uses existing cache plugin)
+ */
+function createRedisCache(config: RateLimitCacheConfig): RateLimitCache {
+  const instanceName = config.redisInstance || 'default';
+  const keyPrefix = config.keyPrefix || 'ratelimit:';
+  const defaultTtlMs = config.defaultTtlMs || 60000;
+
+  const prefixKey = (key: string): string => `${keyPrefix}${key}`;
+
+  return {
+    name: 'redis',
+
+    async get(key: string): Promise<CachedLimit | null> {
+      if (!hasCache(instanceName)) return null;
+
+      try {
+        const cache = getCache(instanceName);
+        const value = await cache.get<CachedLimit>(prefixKey(key));
+        return value;
+      } catch {
+        return null;
+      }
+    },
+
+    async set(key: string, value: CachedLimit, ttlMs: number): Promise<void> {
+      if (!hasCache(instanceName)) return;
+
+      try {
+        const cache = getCache(instanceName);
+        const ttlSeconds = Math.ceil((ttlMs || defaultTtlMs) / 1000);
+        await cache.set(prefixKey(key), value, ttlSeconds);
+      } catch {
+        // Ignore cache errors - we'll fall back to store
+      }
+    },
+
+    async increment(key: string, amount = 1): Promise<number | null> {
+      if (!hasCache(instanceName)) return null;
+
+      try {
+        const cache = getCache(instanceName);
+        // Get current value and increment
+        const current = await cache.get<CachedLimit>(prefixKey(key));
+        if (current) {
+          current.count += amount;
+          const ttlSeconds = Math.ceil((current.windowEnd - Date.now()) / 1000);
+          if (ttlSeconds > 0) {
+            await cache.set(prefixKey(key), current, ttlSeconds);
+          }
+          return current.count;
+        }
+        return null;
+      } catch {
+        return null;
+      }
+    },
+
+    async delete(key: string): Promise<boolean> {
+      if (!hasCache(instanceName)) return false;
+
+      try {
+        const cache = getCache(instanceName);
+        return cache.delete(prefixKey(key));
+      } catch {
+        return false;
+      }
+    },
+
+    isAvailable(): boolean {
+      return hasCache(instanceName);
+    },
+
+    async shutdown(): Promise<void> {
+      // Redis cache is managed by cache plugin
+    },
+  };
+}
+
+/**
+ * Create an in-memory cache with LRU eviction
+ */
+function createMemoryCache(config: RateLimitCacheConfig): RateLimitCache {
+  const maxEntries = config.maxMemoryEntries || 10000;
+  const keyPrefix = config.keyPrefix || 'ratelimit:';
+  const defaultTtlMs = config.defaultTtlMs || 60000;
+
+  const lru = new LRUCache<CachedLimit>(maxEntries);
+
+  const prefixKey = (key: string): string => `${keyPrefix}${key}`;
+
+  return {
+    name: 'memory',
+
+    async get(key: string): Promise<CachedLimit | null> {
+      return lru.get(prefixKey(key));
+    },
+
+    async set(key: string, value: CachedLimit, ttlMs: number): Promise<void> {
+      lru.set(prefixKey(key), value, ttlMs || defaultTtlMs);
+    },
+
+    async increment(key: string, amount = 1): Promise<number | null> {
+      const current = lru.get(prefixKey(key));
+      if (current) {
+        current.count += amount;
+        const ttlMs = current.windowEnd - Date.now();
+        if (ttlMs > 0) {
+          lru.set(prefixKey(key), current, ttlMs);
+        }
+        return current.count;
+      }
+      return null;
+    },
+
+    async delete(key: string): Promise<boolean> {
+      return lru.delete(prefixKey(key));
+    },
+
+    isAvailable(): boolean {
+      return true; // Memory cache is always available
+    },
+
+    async shutdown(): Promise<void> {
+      // Nothing to do for memory cache
+    },
+  };
+}
+
+/**
+ * Create a rate limit cache based on configuration
+ *
+ * @param config Cache configuration
+ * @returns RateLimitCache implementation
+ *
+ * @example
+ * ```ts
+ * // Auto-detect (Redis if available, memory fallback)
+ * const cache = createRateLimitCache({ type: 'auto' });
+ *
+ * // Force Redis
+ * const redisCache = createRateLimitCache({ type: 'redis', redisInstance: 'default' });
+ *
+ * // Force in-memory
+ * const memoryCache = createRateLimitCache({ type: 'memory', maxMemoryEntries: 5000 });
+ * ```
+ */
+export function createRateLimitCache(config: RateLimitCacheConfig = {}): RateLimitCache {
+  const cacheType = config.type || 'auto';
+
+  if (cacheType === 'redis') {
+    return createRedisCache(config);
+  }
+
+  if (cacheType === 'memory') {
+    return createMemoryCache(config);
+  }
+
+  // Auto: Use Redis if available, fall back to memory
+  const redisCache = createRedisCache(config);
+  if (redisCache.isAvailable()) {
+    return redisCache;
+  }
+
+  console.warn(
+    '[RateLimitCache] Redis not available, using in-memory cache. ' +
+    'Rate limits will not sync across server instances.'
+  );
+  return createMemoryCache(config);
+}
+
+/**
+ * Create a no-op cache (for testing or when caching is disabled)
+ */
+export function createNoOpCache(): RateLimitCache {
+  return {
+    name: 'noop',
+    async get(): Promise<CachedLimit | null> { return null; },
+    async set(): Promise<void> { /* noop */ },
+    async increment(): Promise<number | null> { return null; },
+    async delete(): Promise<boolean> { return false; },
+    isAvailable(): boolean { return false; },
+    async shutdown(): Promise<void> { /* noop */ },
+  };
+}

package/src/plugins/rate-limit/stores/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Rate Limit Stores
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresRateLimitStore } from './postgres-store.js';
+export { createRateLimitCache, createNoOpCache } from './cache-store.js';