@qwickapps/server 1.3.1 → 1.5.0

package/src/plugins/rate-limit/strategies/token-bucket.ts

@@ -0,0 +1,154 @@
+/**
+ * Token Bucket Rate Limit Strategy
+ *
+ * Implements a token bucket algorithm that allows bursts while maintaining
+ * a long-term rate limit.
+ *
+ * How it works:
+ * - Bucket starts full with `maxRequests` tokens
+ * - Each request consumes 1 token
+ * - Tokens refill at a constant rate (maxRequests / windowMs)
+ * - If no tokens available, request is rate limited
+ *
+ * Pros:
+ * - Allows short bursts of traffic
+ * - Smooth long-term rate limiting
+ *
+ * Cons:
+ * - More complex state management
+ * - Can allow more requests than fixed/sliding in short bursts
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  Strategy,
+  StrategyOptions,
+  StrategyContext,
+  LimitStatus,
+  CachedLimit,
+} from '../types.js';
+
+/**
+ * Calculate tokens to refill based on time elapsed
+ */
+function calculateRefill(
+  lastRefill: number,
+  maxTokens: number,
+  refillRatePerMs: number
+): { tokens: number; newLastRefill: number } {
+  const now = Date.now();
+  const elapsed = now - lastRefill;
+  const tokensToAdd = elapsed * refillRatePerMs;
+
+  return {
+    tokens: Math.min(maxTokens, tokensToAdd),
+    newLastRefill: now,
+  };
+}
+
+/**
+ * Create the token bucket strategy
+ */
+export function createTokenBucketStrategy(): Strategy {
+  return {
+    name: 'token-bucket',
+
+    async check(
+      key: string,
+      options: StrategyOptions,
+      context: StrategyContext
+    ): Promise<LimitStatus> {
+      const { maxRequests, windowMs, increment = true } = options;
+      const { store, cache, userId, tenantId, ipAddress } = context;
+
+      const now = Date.now();
+      // Refill rate: how many tokens per millisecond
+      const refillRatePerMs = maxRequests / windowMs;
+
+      // Try cache first
+      let cached = await cache.get(key);
+      let tokensRemaining = maxRequests; // Start with full bucket
+      let lastRefill = now;
+
+      if (cached && cached.tokensRemaining !== undefined && cached.lastRefill !== undefined) {
+        // Cache hit - calculate current tokens with refill
+        const refill = calculateRefill(cached.lastRefill, maxRequests, refillRatePerMs);
+        tokensRemaining = Math.min(maxRequests, (cached.tokensRemaining || 0) + refill.tokens);
+        lastRefill = refill.newLastRefill;
+      } else {
+        // Cache miss - check store
+        const stored = await store.get(key, userId);
+        if (stored && stored.tokensRemaining !== undefined && stored.lastRefill) {
+          const refill = calculateRefill(
+            stored.lastRefill.getTime(),
+            maxRequests,
+            refillRatePerMs
+          );
+          tokensRemaining = Math.min(maxRequests, (stored.tokensRemaining || 0) + refill.tokens);
+          lastRefill = refill.newLastRefill;
+        }
+        // If no stored data, start with full bucket
+      }
+
+      // Check if limited (less than 1 full token)
+      const limited = tokensRemaining < 1;
+
+      // Calculate when next token will be available
+      const timeUntilNextToken = limited ? Math.ceil((1 - tokensRemaining) / refillRatePerMs) : 0;
+      const resetAt = Math.ceil((now + timeUntilNextToken) / 1000);
+      const retryAfter = Math.max(0, Math.ceil(timeUntilNextToken / 1000));
+
+      // Calculate remaining (floor to show integer tokens)
+      const remaining = Math.max(0, Math.floor(tokensRemaining) - (increment && !limited ? 1 : 0));
+
+      // Consume token if requested and not limited
+      if (increment && !limited) {
+        const newTokens = tokensRemaining - 1;
+
+        // Update store with new token count
+        // We use a special increment that sets tokens instead of incrementing count
+        const updated = await store.increment(key, {
+          maxRequests,
+          windowMs,
+          strategy: 'token-bucket',
+          userId,
+          tenantId,
+          ipAddress,
+          amount: -1, // Signal to set tokens, not increment count
+        });
+
+        // Update cache
+        const newCached: CachedLimit = {
+          count: Math.floor(maxRequests - newTokens), // Count as consumed tokens
+          maxRequests,
+          windowStart: now,
+          windowEnd: now + windowMs,
+          strategy: 'token-bucket',
+          tokensRemaining: newTokens,
+          lastRefill,
+        };
+        await cache.set(key, newCached, windowMs);
+
+        return {
+          limited: false,
+          current: Math.floor(maxRequests - newTokens),
+          limit: maxRequests,
+          remaining: Math.floor(newTokens),
+          resetAt,
+          retryAfter: 0,
+        };
+      }
+
+      // Return status without consuming
+      return {
+        limited,
+        current: Math.floor(maxRequests - tokensRemaining),
+        limit: maxRequests,
+        remaining,
+        resetAt,
+        retryAfter,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,338 @@
+/**
+ * Rate Limit Plugin Types
+ *
+ * Type definitions for the rate limiting plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+
+// ============================================
+// Strategy Types
+// ============================================
+
+export type RateLimitStrategy = 'sliding-window' | 'fixed-window' | 'token-bucket';
+
+/**
+ * Result from a rate limit check
+ */
+export interface LimitStatus {
+  /** Whether the limit has been exceeded */
+  limited: boolean;
+  /** Current request count in window */
+  current: number;
+  /** Maximum requests allowed */
+  limit: number;
+  /** Remaining requests in window */
+  remaining: number;
+  /** When the current window resets (Unix timestamp in seconds) */
+  resetAt: number;
+  /** Seconds until reset (for Retry-After header) */
+  retryAfter: number;
+}
+
+/**
+ * Strategy interface - all strategies must implement this
+ */
+export interface Strategy {
+  name: RateLimitStrategy;
+
+  /**
+   * Check if the key is rate limited and optionally increment counter
+   */
+  check(
+    key: string,
+    options: StrategyOptions,
+    context: StrategyContext
+  ): Promise<LimitStatus>;
+}
+
+export interface StrategyOptions {
+  maxRequests: number;
+  windowMs: number;
+  /** Whether to increment the counter (default: true) */
+  increment?: boolean;
+}
+
+export interface StrategyContext {
+  store: RateLimitStore;
+  cache: RateLimitCache;
+  userId?: string;
+  tenantId?: string;
+  ipAddress?: string;
+}
+
+// ============================================
+// Store Types
+// ============================================
+
+/**
+ * Stored rate limit record
+ */
+export interface StoredLimit {
+  id: string;
+  key: string;
+  count: number;
+  maxRequests: number;
+  windowMs: number;
+  windowStart: Date;
+  windowEnd: Date;
+  strategy: RateLimitStrategy;
+  userId?: string;
+  tenantId?: string;
+  ipAddress?: string;
+  /** Token bucket: remaining tokens */
+  tokensRemaining?: number;
+  /** Token bucket: last refill time */
+  lastRefill?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Options for incrementing a rate limit
+ */
+export interface IncrementOptions {
+  maxRequests: number;
+  windowMs: number;
+  strategy: RateLimitStrategy;
+  userId?: string;
+  tenantId?: string;
+  ipAddress?: string;
+  /** Amount to increment by (default: 1) */
+  amount?: number;
+}
+
+/**
+ * Rate limit store interface - implementations handle persistence
+ */
+export interface RateLimitStore {
+  /** Store name for logging */
+  name: string;
+
+  /** Initialize store (create tables, indexes, RLS) */
+  initialize(): Promise<void>;
+
+  /** Get current limit status for a key */
+  get(key: string, userId?: string): Promise<StoredLimit | null>;
+
+  /** Increment counter for a key, returns updated record */
+  increment(key: string, options: IncrementOptions): Promise<StoredLimit>;
+
+  /** Clear a specific limit */
+  clear(key: string, userId?: string): Promise<boolean>;
+
+  /** Clean up expired limits, returns count of deleted records */
+  cleanup(): Promise<number>;
+
+  /** Shutdown store */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * PostgreSQL store configuration
+ */
+export interface PostgresRateLimitStoreConfig {
+  /**
+   * PostgreSQL pool instance or function that returns one.
+   * Use a function for lazy initialization.
+   */
+  pool: unknown | (() => unknown);
+
+  /** Table name (default: 'rate_limits') */
+  tableName?: string;
+
+  /** Schema name (default: 'public') */
+  schema?: string;
+
+  /** Auto-create tables on initialize (default: true) */
+  autoCreateTables?: boolean;
+
+  /** Enable RLS policies (default: true) */
+  enableRLS?: boolean;
+}
+
+// ============================================
+// Cache Types
+// ============================================
+
+/**
+ * Cached rate limit entry
+ */
+export interface CachedLimit {
+  count: number;
+  maxRequests: number;
+  windowStart: number; // Unix timestamp ms
+  windowEnd: number; // Unix timestamp ms
+  strategy: RateLimitStrategy;
+  /** Token bucket specific */
+  tokensRemaining?: number;
+  lastRefill?: number;
+}
+
+/**
+ * Rate limit cache interface
+ */
+export interface RateLimitCache {
+  /** Cache name for logging */
+  name: string;
+
+  /** Get cached limit for a key */
+  get(key: string): Promise<CachedLimit | null>;
+
+  /** Set cached limit with TTL */
+  set(key: string, value: CachedLimit, ttlMs: number): Promise<void>;
+
+  /** Atomic increment of count, returns new count */
+  increment(key: string, amount?: number): Promise<number | null>;
+
+  /** Delete a cached entry */
+  delete(key: string): Promise<boolean>;
+
+  /** Check if cache is available */
+  isAvailable(): boolean;
+
+  /** Shutdown cache */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Cache store configuration
+ */
+export interface RateLimitCacheConfig {
+  /**
+   * Cache type:
+   * - 'redis': Use Redis via cache plugin
+   * - 'memory': Use in-memory cache
+   * - 'auto': Use Redis if available, fall back to memory
+   */
+  type?: 'redis' | 'memory' | 'auto';
+
+  /** Redis cache instance name (default: 'default') */
+  redisInstance?: string;
+
+  /** Default TTL in milliseconds (default: 60000) */
+  defaultTtlMs?: number;
+
+  /** Max in-memory entries (default: 10000) */
+  maxMemoryEntries?: number;
+
+  /** Key prefix for cache entries (default: 'ratelimit:') */
+  keyPrefix?: string;
+}
+
+// ============================================
+// Middleware Types
+// ============================================
+
+/**
+ * Express middleware options
+ */
+export interface RateLimitMiddlewareOptions {
+  /** Time window in milliseconds (default: 60000 = 1 min) */
+  windowMs?: number;
+
+  /** Max requests per window (static or dynamic) */
+  max?: number | ((req: Request) => number | Promise<number>);
+
+  /** Generate the rate limit key from request */
+  keyGenerator?: (req: Request) => string | Promise<string>;
+
+  /** Skip rate limiting for certain requests */
+  skip?: (req: Request) => boolean | Promise<boolean>;
+
+  /** Custom handler when limit is exceeded */
+  handler?: (req: Request, res: Response, next: NextFunction, status: LimitStatus) => void;
+
+  /** Strategy to use (default: 'sliding-window') */
+  strategy?: RateLimitStrategy;
+
+  /** Include standard rate limit headers (default: true) */
+  headers?: boolean;
+
+  /** Key prefix for this middleware instance */
+  keyPrefix?: string;
+}
+
+// ============================================
+// Plugin Types
+// ============================================
+
+/**
+ * Rate limit plugin configuration
+ */
+export interface RateLimitPluginConfig {
+  /**
+   * PostgreSQL store configuration (required for persistence)
+   */
+  store: RateLimitStore;
+
+  /**
+   * Default limits applied when not specified per-route
+   */
+  defaults?: {
+    /** Time window in milliseconds (default: 60000 = 1 min) */
+    windowMs?: number;
+    /** Max requests per window (default: 100) */
+    maxRequests?: number;
+    /** Strategy to use (default: 'sliding-window') */
+    strategy?: RateLimitStrategy;
+  };
+
+  /**
+   * Cache configuration
+   */
+  cache?: RateLimitCacheConfig;
+
+  /**
+   * Auto-cleanup configuration
+   */
+  cleanup?: {
+    /** Enable auto-cleanup of expired limits (default: true) */
+    enabled?: boolean;
+    /** Cleanup interval in milliseconds (default: 300000 = 5 min) */
+    intervalMs?: number;
+  };
+
+  /**
+   * API routes configuration
+   */
+  api?: {
+    /** Enable status API endpoints (default: true) */
+    enabled?: boolean;
+    /** Route prefix (default: '/rate-limit') */
+    prefix?: string;
+  };
+
+  /**
+   * UI configuration
+   */
+  ui?: {
+    /** Enable UI menu item and config page (default: true) */
+    enabled?: boolean;
+  };
+
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+/**
+ * Options for checking a rate limit programmatically
+ */
+export interface CheckLimitOptions {
+  /** Max requests (uses plugin default if not specified) */
+  maxRequests?: number;
+  /** Window in milliseconds (uses plugin default if not specified) */
+  windowMs?: number;
+  /** Strategy (uses plugin default if not specified) */
+  strategy?: RateLimitStrategy;
+  /** User ID for scoped limits */
+  userId?: string;
+  /** Tenant ID for scoped limits */
+  tenantId?: string;
+  /** IP address for scoped limits */
+  ipAddress?: string;
+  /** Whether to increment counter (default: true) */
+  increment?: boolean;
+}