@qwickapps/server 1.3.1 → 1.5.0

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

@@ -0,0 +1,402 @@
+/**
+ * PostgreSQL Rate Limit Store
+ *
+ * Rate limit storage implementation using PostgreSQL with Row-Level Security (RLS).
+ * Follows the same pattern as the preferences plugin's postgres-store.
+ *
+ * RLS Context Pattern:
+ * Each operation uses an explicit transaction and sets `app.current_user_id`
+ * as a transaction-local configuration variable. The RLS policy checks this
+ * variable to enforce that users can only access their own rate limits.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  RateLimitStore,
+  PostgresRateLimitStoreConfig,
+  StoredLimit,
+  IncrementOptions,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+  connect(): Promise<PgPoolClient>;
+}
+
+interface PgPoolClient {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+  release(): void;
+}
+
+/**
+ * Execute a function within an RLS-protected transaction
+ *
+ * This helper ensures that:
+ * 1. All queries run within the same transaction
+ * 2. The RLS context is set before any data access
+ * 3. The transaction is properly committed or rolled back
+ *
+ * @param pool PostgreSQL pool
+ * @param userId User ID to set as the RLS context (optional for IP-only limits)
+ * @param callback Function to execute within the transaction
+ */
+async function withRLSContext<T>(
+  pool: PgPool,
+  userId: string | undefined,
+  callback: (client: PgPoolClient) => Promise<T>
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    // Set transaction-local user context for RLS
+    // If no userId, set to empty string (allows IP-only limits via RLS policy)
+    await client.query(
+      "SELECT set_config('app.current_user_id', $1, true)",
+      [userId || '']
+    );
+    const result = await callback(client);
+    await client.query('COMMIT');
+    return result;
+  } catch (error) {
+    await client.query('ROLLBACK');
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+/**
+ * Create a PostgreSQL rate limit store with RLS
+ *
+ * @param config Configuration including a pg Pool instance
+ * @returns RateLimitStore implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresRateLimitStore } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = postgresRateLimitStore({ pool });
+ *
+ * // Or with lazy initialization:
+ * const store = postgresRateLimitStore({ pool: () => getPostgres().getPool() });
+ * ```
+ */
+export function postgresRateLimitStore(config: PostgresRateLimitStoreConfig): RateLimitStore {
+  const {
+    pool: poolOrFn,
+    tableName = 'rate_limits',
+    schema = 'public',
+    autoCreateTables = true,
+    enableRLS = true,
+  } = config;
+
+  // Helper to get pool (supports lazy initialization via function)
+  const getPool = (): PgPool => {
+    const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+    if (!pool || typeof (pool as PgPool).query !== 'function') {
+      throw new Error('Invalid pool: must have query method');
+    }
+    return pool as PgPool;
+  };
+
+  const tableFullName = `"${schema}"."${tableName}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      const pool = getPool();
+
+      // Create table
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS ${tableFullName} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+          -- Scope identifiers (nullable, use what applies)
+          user_id UUID,
+          tenant_id UUID,
+          ip_address INET,
+
+          -- Limit key (composite identifier)
+          limit_key VARCHAR(500) NOT NULL,
+
+          -- Strategy and configuration
+          strategy VARCHAR(50) NOT NULL DEFAULT 'sliding-window',
+          max_requests INTEGER NOT NULL,
+          window_ms INTEGER NOT NULL,
+
+          -- Current state
+          current_count INTEGER DEFAULT 0,
+          window_start TIMESTAMPTZ NOT NULL,
+          window_end TIMESTAMPTZ NOT NULL,
+
+          -- Token bucket specific (nullable)
+          tokens_remaining NUMERIC,
+          last_refill TIMESTAMPTZ,
+
+          -- Metadata
+          metadata JSONB,
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW()
+        );
+      `);
+
+      // Create indexes
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_key ON ${tableFullName}(limit_key);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_key_window ON ${tableFullName}(limit_key, window_start);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_user ON ${tableFullName}(user_id) WHERE user_id IS NOT NULL;
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_tenant ON ${tableFullName}(tenant_id) WHERE tenant_id IS NOT NULL;
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_cleanup ON ${tableFullName}(window_end);
+      `);
+
+      // Enable RLS if configured
+      if (enableRLS) {
+        await pool.query(`
+          ALTER TABLE ${tableFullName} ENABLE ROW LEVEL SECURITY;
+          ALTER TABLE ${tableFullName} FORCE ROW LEVEL SECURITY;
+        `);
+
+        // Create or replace the RLS policy
+        // Drop existing policy first to avoid errors on re-initialization
+        await pool.query(`
+          DROP POLICY IF EXISTS "${tableName}_access" ON ${tableFullName};
+        `);
+
+        // RLS policy: Users can access their own limits OR IP-only limits (no user)
+        await pool.query(`
+          CREATE POLICY "${tableName}_access" ON ${tableFullName}
+            FOR ALL
+            USING (
+              user_id::text = current_setting('app.current_user_id', true)
+              OR (user_id IS NULL AND current_setting('app.current_user_id', true) = '')
+            )
+            WITH CHECK (
+              user_id::text = current_setting('app.current_user_id', true)
+              OR (user_id IS NULL AND current_setting('app.current_user_id', true) = '')
+            );
+        `);
+      }
+    },
+
+    async get(key: string, userId?: string): Promise<StoredLimit | null> {
+      return withRLSContext(getPool(), userId, async (client) => {
+        const result = await client.query(
+          `SELECT * FROM ${tableFullName}
+           WHERE limit_key = $1
+           AND window_end > NOW()
+           ORDER BY window_start DESC
+           LIMIT 1`,
+          [key]
+        );
+
+        if (result.rows.length === 0) {
+          return null;
+        }
+
+        const row = result.rows[0] as Record<string, unknown>;
+        return {
+          id: row.id as string,
+          key: row.limit_key as string,
+          count: row.current_count as number,
+          maxRequests: row.max_requests as number,
+          windowMs: row.window_ms as number,
+          windowStart: new Date(row.window_start as string),
+          windowEnd: new Date(row.window_end as string),
+          strategy: row.strategy as StoredLimit['strategy'],
+          userId: row.user_id as string | undefined,
+          tenantId: row.tenant_id as string | undefined,
+          ipAddress: row.ip_address as string | undefined,
+          tokensRemaining: row.tokens_remaining as number | undefined,
+          lastRefill: row.last_refill ? new Date(row.last_refill as string) : undefined,
+          createdAt: new Date(row.created_at as string),
+          updatedAt: new Date(row.updated_at as string),
+        };
+      });
+    },
+
+    async increment(key: string, options: IncrementOptions): Promise<StoredLimit> {
+      const { maxRequests, windowMs, strategy, userId, tenantId, ipAddress, amount = 1 } = options;
+
+      return withRLSContext(getPool(), userId, async (client) => {
+        const now = new Date();
+        const windowStart = new Date(now.getTime() - (now.getTime() % windowMs));
+        const windowEnd = new Date(windowStart.getTime() + windowMs);
+
+        // For token bucket, handle differently
+        if (strategy === 'token-bucket') {
+          // Get existing record or create new one
+          const existing = await client.query(
+            `SELECT * FROM ${tableFullName}
+             WHERE limit_key = $1
+             ORDER BY created_at DESC
+             LIMIT 1`,
+            [key]
+          );
+
+          if (existing.rows.length > 0) {
+            const row = existing.rows[0] as Record<string, unknown>;
+            const lastRefill = row.last_refill ? new Date(row.last_refill as string).getTime() : now.getTime();
+            const tokensRemaining = row.tokens_remaining as number ?? maxRequests;
+
+            // Calculate refill
+            const elapsed = now.getTime() - lastRefill;
+            const refillRate = maxRequests / windowMs;
+            const newTokens = Math.min(maxRequests, tokensRemaining + elapsed * refillRate - 1);
+
+            await client.query(
+              `UPDATE ${tableFullName}
+               SET tokens_remaining = $1,
+                   last_refill = $2,
+                   current_count = $3,
+                   updated_at = NOW()
+               WHERE id = $4`,
+              [newTokens, now, Math.floor(maxRequests - newTokens), row.id]
+            );
+
+            return {
+              id: row.id as string,
+              key,
+              count: Math.floor(maxRequests - newTokens),
+              maxRequests,
+              windowMs,
+              windowStart: new Date(row.window_start as string),
+              windowEnd: new Date(row.window_end as string),
+              strategy,
+              userId,
+              tenantId,
+              ipAddress,
+              tokensRemaining: newTokens,
+              lastRefill: now,
+              createdAt: new Date(row.created_at as string),
+              updatedAt: now,
+            };
+          }
+
+          // Create new record with full bucket minus 1
+          const newTokens = maxRequests - 1;
+          const insertResult = await client.query(
+            `INSERT INTO ${tableFullName}
+             (limit_key, strategy, max_requests, window_ms, current_count,
+              window_start, window_end, user_id, tenant_id, ip_address,
+              tokens_remaining, last_refill)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+             RETURNING *`,
+            [key, strategy, maxRequests, windowMs, 1, windowStart, windowEnd,
+             userId || null, tenantId || null, ipAddress || null, newTokens, now]
+          );
+
+          const row = insertResult.rows[0] as Record<string, unknown>;
+          return {
+            id: row.id as string,
+            key,
+            count: 1,
+            maxRequests,
+            windowMs,
+            windowStart,
+            windowEnd,
+            strategy,
+            userId,
+            tenantId,
+            ipAddress,
+            tokensRemaining: newTokens,
+            lastRefill: now,
+            createdAt: now,
+            updatedAt: now,
+          };
+        }
+
+        // For sliding-window and fixed-window, use UPDATE-then-INSERT pattern
+        // This avoids needing a unique constraint on (limit_key, window_start)
+
+        // First try to update existing record in current window
+        const updateResult = await client.query(
+          `UPDATE ${tableFullName}
+           SET current_count = current_count + $1,
+               updated_at = NOW()
+           WHERE limit_key = $2
+             AND window_start = $3
+           RETURNING *`,
+          [amount, key, windowStart]
+        );
+
+        if (updateResult.rows.length > 0) {
+          const row = updateResult.rows[0] as Record<string, unknown>;
+          return {
+            id: row.id as string,
+            key,
+            count: row.current_count as number,
+            maxRequests,
+            windowMs,
+            windowStart,
+            windowEnd,
+            strategy,
+            userId,
+            tenantId,
+            ipAddress,
+            createdAt: new Date(row.created_at as string),
+            updatedAt: now,
+          };
+        }
+
+        // No existing record - insert new
+        const insertResult = await client.query(
+          `INSERT INTO ${tableFullName}
+           (limit_key, strategy, max_requests, window_ms, current_count,
+            window_start, window_end, user_id, tenant_id, ip_address)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+           RETURNING *`,
+          [key, strategy, maxRequests, windowMs, amount, windowStart, windowEnd,
+           userId || null, tenantId || null, ipAddress || null]
+        );
+
+        const row = insertResult.rows[0] as Record<string, unknown>;
+        return {
+          id: row.id as string,
+          key,
+          count: amount,
+          maxRequests,
+          windowMs,
+          windowStart,
+          windowEnd,
+          strategy,
+          userId,
+          tenantId,
+          ipAddress,
+          createdAt: now,
+          updatedAt: now,
+        };
+      });
+    },
+
+    async clear(key: string, userId?: string): Promise<boolean> {
+      return withRLSContext(getPool(), userId, async (client) => {
+        const result = await client.query(
+          `DELETE FROM ${tableFullName} WHERE limit_key = $1`,
+          [key]
+        );
+        return (result.rowCount ?? 0) > 0;
+      });
+    },
+
+    async cleanup(): Promise<number> {
+      const pool = getPool();
+      // Cleanup runs without RLS context as it's a system operation
+      // We use a direct query without user context
+      const result = await pool.query(
+        `DELETE FROM ${tableFullName} WHERE window_end < NOW()`
+      );
+      return result.rowCount ?? 0;
+    },
+
+    async shutdown(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/rate-limit/strategies/fixed-window.ts

@@ -0,0 +1,116 @@
+/**
+ * Fixed Window Rate Limit Strategy
+ *
+ * Implements a simple fixed window algorithm where requests are counted
+ * within discrete time windows. When a new window starts, the count resets.
+ *
+ * Pros:
+ * - Simple to implement and understand
+ * - Low memory overhead
+ *
+ * Cons:
+ * - Burst at boundary: allows 2x requests if timed at window edge
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  Strategy,
+  StrategyOptions,
+  StrategyContext,
+  LimitStatus,
+  CachedLimit,
+} from '../types.js';
+
+/**
+ * Create the fixed window strategy
+ */
+export function createFixedWindowStrategy(): Strategy {
+  return {
+    name: 'fixed-window',
+
+    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();
+      const windowStart = now - (now % windowMs); // Align to window boundary
+      const windowEnd = windowStart + windowMs;
+
+      // Try cache first
+      let cached = await cache.get(key);
+      let currentCount = 0;
+
+      if (cached && cached.windowStart === windowStart) {
+        // Cache hit and same window
+        currentCount = cached.count;
+      } else if (cached && cached.windowEnd <= now) {
+        // Window expired - reset count
+        currentCount = 0;
+      } else {
+        // Cache miss - check store
+        const stored = await store.get(key, userId);
+        if (stored) {
+          const storedWindowStart = stored.windowStart.getTime();
+          if (storedWindowStart === windowStart) {
+            currentCount = stored.count;
+          }
+          // If different window, count is 0 (new window)
+        }
+      }
+
+      // Check if limited
+      const limited = currentCount >= maxRequests;
+      const remaining = Math.max(0, maxRequests - currentCount - (increment && !limited ? 1 : 0));
+      const resetAt = Math.ceil(windowEnd / 1000);
+      const retryAfter = Math.max(0, Math.ceil((windowEnd - now) / 1000));
+
+      // Increment if requested and not limited
+      if (increment && !limited) {
+        // Increment in store
+        const updated = await store.increment(key, {
+          maxRequests,
+          windowMs,
+          strategy: 'fixed-window',
+          userId,
+          tenantId,
+          ipAddress,
+          amount: 1,
+        });
+
+        // Update cache
+        const newCached: CachedLimit = {
+          count: updated.count,
+          maxRequests,
+          windowStart,
+          windowEnd,
+          strategy: 'fixed-window',
+        };
+        await cache.set(key, newCached, windowMs);
+
+        return {
+          limited: false,
+          current: updated.count,
+          limit: maxRequests,
+          remaining: Math.max(0, maxRequests - updated.count),
+          resetAt,
+          retryAfter,
+        };
+      }
+
+      // Return status without incrementing
+      return {
+        limited,
+        current: currentCount,
+        limit: maxRequests,
+        remaining,
+        resetAt,
+        retryAfter,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Rate Limit Strategies
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { createSlidingWindowStrategy } from './sliding-window.js';
+export { createFixedWindowStrategy } from './fixed-window.js';
+export { createTokenBucketStrategy } from './token-bucket.js';
+
+import type { Strategy, RateLimitStrategy } from '../types.js';
+import { createSlidingWindowStrategy } from './sliding-window.js';
+import { createFixedWindowStrategy } from './fixed-window.js';
+import { createTokenBucketStrategy } from './token-bucket.js';
+
+/**
+ * Get a strategy by name
+ */
+export function getStrategy(name: RateLimitStrategy): Strategy {
+  switch (name) {
+    case 'sliding-window':
+      return createSlidingWindowStrategy();
+    case 'fixed-window':
+      return createFixedWindowStrategy();
+    case 'token-bucket':
+      return createTokenBucketStrategy();
+    default:
+      throw new Error(`Unknown rate limit strategy: ${name}`);
+  }
+}

package/src/plugins/rate-limit/strategies/sliding-window.ts

@@ -0,0 +1,157 @@
+/**
+ * Sliding Window Rate Limit Strategy
+ *
+ * Implements a sliding window algorithm that provides smooth rate limiting
+ * without the "burst at boundary" problem of fixed windows.
+ *
+ * The algorithm works by:
+ * 1. Tracking request timestamps within a sliding window
+ * 2. On each request, counting requests in the current window
+ * 3. Old requests "slide out" as time passes
+ *
+ * For performance, we approximate using weighted window counting:
+ * - current_window_count + (previous_window_count * overlap_percentage)
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  Strategy,
+  StrategyOptions,
+  StrategyContext,
+  LimitStatus,
+  CachedLimit,
+} from '../types.js';
+
+/**
+ * Calculate the sliding window count using weighted approximation
+ */
+function calculateSlidingCount(
+  currentCount: number,
+  previousCount: number,
+  windowMs: number,
+  windowStart: number
+): number {
+  const now = Date.now();
+  const elapsed = now - windowStart;
+  const overlap = Math.max(0, windowMs - elapsed) / windowMs;
+
+  // Weighted count: all of current window + portion of previous that overlaps
+  return Math.floor(currentCount + previousCount * overlap);
+}
+
+/**
+ * Create the sliding window strategy
+ */
+export function createSlidingWindowStrategy(): Strategy {
+  return {
+    name: 'sliding-window',
+
+    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();
+      const windowStart = now - (now % windowMs); // Align to window boundary
+      const windowEnd = windowStart + windowMs;
+
+      // Try cache first
+      let cached = await cache.get(key);
+      let currentCount = 0;
+      let previousCount = 0;
+
+      if (cached && cached.windowEnd > now) {
+        // Cache hit and window is still valid
+        currentCount = cached.count;
+
+        // For sliding window, we also need previous window's count
+        // This is stored in the cache with a special key
+        const prevCached = await cache.get(`${key}:prev`);
+        if (prevCached) {
+          previousCount = prevCached.count;
+        }
+      } else {
+        // Cache miss or expired - check store
+        const stored = await store.get(key, userId);
+        if (stored && stored.windowEnd.getTime() > now) {
+          currentCount = stored.count;
+        }
+      }
+
+      // Calculate sliding window count
+      const slidingCount = calculateSlidingCount(
+        currentCount,
+        previousCount,
+        windowMs,
+        windowStart
+      );
+
+      // Check if limited
+      const limited = slidingCount >= maxRequests;
+      const remaining = Math.max(0, maxRequests - slidingCount - (increment && !limited ? 1 : 0));
+      const resetAt = Math.ceil(windowEnd / 1000);
+      const retryAfter = Math.max(0, Math.ceil((windowEnd - now) / 1000));
+
+      // Increment if requested and not limited
+      if (increment && !limited) {
+        // Check if we're in a new window - if so, save old count as previous
+        if (cached && cached.windowStart !== windowStart && cached.windowStart > 0) {
+          // Window rolled over - save old window's data as previous
+          const prevCached: CachedLimit = {
+            count: cached.count,
+            maxRequests,
+            windowStart: cached.windowStart,
+            windowEnd: cached.windowEnd,
+            strategy: 'sliding-window',
+          };
+          // Save previous window for overlap calculation (keep for 2x window duration)
+          await cache.set(`${key}:prev`, prevCached, windowMs * 2);
+        }
+
+        // Increment in store
+        const updated = await store.increment(key, {
+          maxRequests,
+          windowMs,
+          strategy: 'sliding-window',
+          userId,
+          tenantId,
+          ipAddress,
+          amount: 1,
+        });
+
+        // Update cache with current window
+        const newCached: CachedLimit = {
+          count: updated.count,
+          maxRequests,
+          windowStart,
+          windowEnd,
+          strategy: 'sliding-window',
+        };
+        await cache.set(key, newCached, windowMs);
+
+        return {
+          limited: false,
+          current: updated.count,
+          limit: maxRequests,
+          remaining: Math.max(0, maxRequests - updated.count),
+          resetAt,
+          retryAfter,
+        };
+      }
+
+      // Return status without incrementing
+      return {
+        limited,
+        current: slidingCount,
+        limit: maxRequests,
+        remaining,
+        resetAt,
+        retryAfter,
+      };
+    },
+  };
+}