@qwickapps/server 1.2.0 → 1.3.0

package/src/plugins/bans/stores/postgres-store.ts

@@ -0,0 +1,195 @@
+/**
+ * PostgreSQL Ban Store
+ *
+ * Ban storage implementation using PostgreSQL.
+ * Requires the 'pg' package and the Users plugin to be installed.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  BanStore,
+  Ban,
+  CreateBanInput,
+  RemoveBanInput,
+  PostgresBanStoreConfig,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+/**
+ * Create a PostgreSQL ban store
+ *
+ * @param config Configuration including a pg Pool instance or a function that returns one
+ * @returns BanStore implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresBanStore } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = postgresBanStore({ pool });
+ *
+ * // Or with lazy initialization:
+ * const store = postgresBanStore({ pool: () => getPostgres().getPool() });
+ * ```
+ */
+export function postgresBanStore(config: PostgresBanStoreConfig): BanStore {
+  const {
+    pool: poolOrFn,
+    tableName = 'user_bans',
+    schema = 'public',
+    autoCreateTables = true,
+  } = config;
+
+  // Helper to get pool (supports lazy initialization via function)
+  const getPool = (): PgPool => {
+    const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+    return pool as PgPool;
+  };
+
+  const tableFullName = `"${schema}"."${tableName}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      // Create bans table
+      // Note: This does NOT have a foreign key to users table
+      // The relationship is enforced at the application level via Users Plugin
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${tableFullName} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID NOT NULL,
+          reason TEXT NOT NULL,
+          banned_by VARCHAR(255) NOT NULL,
+          banned_at TIMESTAMPTZ DEFAULT NOW(),
+          expires_at TIMESTAMPTZ,
+          is_active BOOLEAN DEFAULT TRUE,
+          removed_at TIMESTAMPTZ,
+          removed_by VARCHAR(255),
+          metadata JSONB DEFAULT '{}'
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${tableFullName}(user_id);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_is_active ON ${tableFullName}(is_active);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_expires_at ON ${tableFullName}(expires_at) WHERE expires_at IS NOT NULL;
+      `);
+    },
+
+    async isBanned(userId: string): Promise<boolean> {
+      const ban = await this.getActiveBan(userId);
+      return ban !== null;
+    },
+
+    async getActiveBan(userId: string): Promise<Ban | null> {
+      const result = await getPool().query(
+        `SELECT * FROM ${tableFullName}
+         WHERE user_id = $1 AND is_active = TRUE
+         AND (expires_at IS NULL OR expires_at > NOW())`,
+        [userId]
+      );
+      return (result.rows[0] as Ban) || null;
+    },
+
+    async createBan(input: CreateBanInput): Promise<Ban> {
+      const expiresAt = input.duration
+        ? new Date(Date.now() + input.duration * 1000)
+        : null;
+
+      // Deactivate any existing active bans for this user
+      await getPool().query(
+        `UPDATE ${tableFullName}
+         SET is_active = FALSE, removed_at = NOW(), removed_by = $2
+         WHERE user_id = $1 AND is_active = TRUE`,
+        [input.user_id, input.banned_by]
+      );
+
+      // Create new ban
+      const result = await getPool().query(
+        `INSERT INTO ${tableFullName} (user_id, reason, banned_by, expires_at, metadata)
+         VALUES ($1, $2, $3, $4, $5)
+         RETURNING *`,
+        [
+          input.user_id,
+          input.reason,
+          input.banned_by,
+          expiresAt,
+          JSON.stringify(input.metadata || {}),
+        ]
+      );
+
+      return result.rows[0] as Ban;
+    },
+
+    async removeBan(input: RemoveBanInput): Promise<boolean> {
+      const result = await getPool().query(
+        `UPDATE ${tableFullName}
+         SET is_active = FALSE, removed_at = NOW(), removed_by = $2
+         WHERE user_id = $1 AND is_active = TRUE
+         RETURNING *`,
+        [input.user_id, input.removed_by]
+      );
+
+      return (result.rowCount ?? 0) > 0;
+    },
+
+    async listBans(userId: string): Promise<Ban[]> {
+      const result = await getPool().query(
+        `SELECT * FROM ${tableFullName}
+         WHERE user_id = $1
+         ORDER BY banned_at DESC`,
+        [userId]
+      );
+      return result.rows as Ban[];
+    },
+
+    async listActiveBans(options: { limit?: number; offset?: number } = {}): Promise<{
+      bans: Ban[];
+      total: number;
+    }> {
+      const { limit = 50, offset = 0 } = options;
+
+      // Get total count
+      const countResult = await getPool().query(
+        `SELECT COUNT(*) FROM ${tableFullName}
+         WHERE is_active = TRUE AND (expires_at IS NULL OR expires_at > NOW())`
+      );
+      const total = parseInt((countResult.rows[0] as { count: string }).count, 10);
+
+      // Get bans
+      const result = await getPool().query(
+        `SELECT * FROM ${tableFullName}
+         WHERE is_active = TRUE AND (expires_at IS NULL OR expires_at > NOW())
+         ORDER BY banned_at DESC
+         LIMIT $1 OFFSET $2`,
+        [limit, offset]
+      );
+
+      return {
+        bans: result.rows as Ban[],
+        total,
+      };
+    },
+
+    async cleanupExpiredBans(): Promise<number> {
+      const result = await getPool().query(
+        `UPDATE ${tableFullName}
+         SET is_active = FALSE
+         WHERE is_active = TRUE AND expires_at IS NOT NULL AND expires_at <= NOW()`
+      );
+
+      return result.rowCount ?? 0;
+    },
+
+    async shutdown(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/bans/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Bans Plugin Types
+ *
+ * Type definitions for ban management.
+ * Bans are always on USER entities (by user_id), not emails.
+ * Email is just an identifier to resolve to a user.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { User } from '../users/types.js';
+
+/**
+ * Ban record
+ */
+export interface Ban {
+  /** Primary key - UUID */
+  id: string;
+  /** User ID being banned */
+  user_id: string;
+  /** Reason for the ban */
+  reason: string;
+  /** Who created the ban (user ID or system) */
+  banned_by: string;
+  /** When the ban was created */
+  banned_at: Date;
+  /** When the ban expires (null = permanent) */
+  expires_at?: Date;
+  /** Whether the ban is currently active */
+  is_active: boolean;
+  /** When the ban was removed */
+  removed_at?: Date;
+  /** Who removed the ban */
+  removed_by?: string;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Ban creation payload
+ */
+export interface CreateBanInput {
+  user_id: string;
+  reason: string;
+  banned_by: string;
+  /** Duration in seconds (null = permanent) */
+  duration?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Ban removal payload
+ */
+export interface RemoveBanInput {
+  user_id: string;
+  removed_by: string;
+  note?: string;
+}
+
+/**
+ * Ban store interface - storage backend for bans
+ */
+export interface BanStore {
+  /** Store name (e.g., 'postgres', 'memory') */
+  name: string;
+
+  /** Initialize the store (create tables, etc.) */
+  initialize(): Promise<void>;
+
+  /** Check if user is banned */
+  isBanned(userId: string): Promise<boolean>;
+
+  /** Get active ban for user */
+  getActiveBan(userId: string): Promise<Ban | null>;
+
+  /** Create a ban */
+  createBan(input: CreateBanInput): Promise<Ban>;
+
+  /** Remove a ban */
+  removeBan(input: RemoveBanInput): Promise<boolean>;
+
+  /** List bans for a user (including history) */
+  listBans(userId: string): Promise<Ban[]>;
+
+  /** List all active bans */
+  listActiveBans(options?: { limit?: number; offset?: number }): Promise<{
+    bans: Ban[];
+    total: number;
+  }>;
+
+  /** Cleanup expired bans */
+  cleanupExpiredBans(): Promise<number>;
+
+  /** Shutdown the store */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Ban callbacks
+ */
+export interface BanCallbacks {
+  /** Called when a user is banned */
+  onBan?: (user: User, ban: Ban) => Promise<void>;
+  /** Called when a ban is removed */
+  onUnban?: (user: User) => Promise<void>;
+}
+
+/**
+ * Bans plugin configuration
+ */
+export interface BansPluginConfig {
+  /** Ban storage backend */
+  store: BanStore;
+  /** Support temporary bans (with expiration) */
+  supportTemporary?: boolean;
+  /** Callbacks */
+  callbacks?: BanCallbacks;
+  /** API configuration */
+  api?: {
+    /** API route prefix (default: '/api/bans') */
+    prefix?: string;
+    /** Enable API endpoints */
+    enabled?: boolean;
+  };
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * PostgreSQL ban store configuration
+ */
+export interface PostgresBanStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: unknown | (() => unknown);
+  /** Bans table name (default: 'user_bans') */
+  tableName?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}

package/src/plugins/cache-plugin.test.ts

@@ -9,6 +9,27 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 // Mock ioredis before importing the plugin
 vi.mock('ioredis', () => {
+  // Create a mock stream that emits keys in batches
+  const createMockScanStream = (keys: string[]) => {
+    const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
+    return {
+      on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+        if (!handlers[event]) handlers[event] = [];
+        handlers[event].push(handler);
+        // Simulate async emission after all handlers are registered
+        if (event === 'error') {
+          setTimeout(() => {
+            // Emit data in batches
+            handlers['data']?.forEach(h => h(keys));
+            // Then emit end
+            handlers['end']?.forEach(h => h());
+          }, 0);
+        }
+        return { on: vi.fn() };
+      }),
+    };
+  };
+
   const mockClient = {
     get: vi.fn().mockResolvedValue(null),
     setex: vi.fn().mockResolvedValue('OK'),
@@ -19,6 +40,7 @@ vi.mock('ioredis', () => {
     incr: vi.fn().mockResolvedValue(1),
     incrby: vi.fn().mockResolvedValue(5),
     keys: vi.fn().mockResolvedValue([]),
+    scanStream: vi.fn(() => createMockScanStream(['test:key1', 'test:key2', 'test:key3'])),
     info: vi.fn().mockResolvedValue('used_memory_human:1.5M\n'),
     dbsize: vi.fn().mockResolvedValue(100),
     ping: vi.fn().mockResolvedValue('PONG'),
@@ -38,6 +60,7 @@ import {
   hasCache,
   type CachePluginConfig,
 } from './cache-plugin.js';
+import type { PluginRegistry } from '../core/plugin-registry.js';
 
 describe('Cache Plugin', () => {
   const mockConfig: CachePluginConfig = {
@@ -47,21 +70,39 @@ describe('Cache Plugin', () => {
     healthCheck: false, // Disable for unit tests
   };
 
-  const mockContext = {
-    config: { productName: 'Test', port: 3000 },
-    app: {} as any,
-    router: {} as any,
-    logger: {
+  // Create a mock registry that matches the new Plugin interface
+  const createMockRegistry = (): PluginRegistry => ({
+    hasPlugin: vi.fn().mockReturnValue(false),
+    getPlugin: vi.fn().mockReturnValue(null),
+    listPlugins: vi.fn().mockReturnValue([]),
+    addRoute: vi.fn(),
+    addMenuItem: vi.fn(),
+    addPage: vi.fn(),
+    addWidget: vi.fn(),
+    getRoutes: vi.fn().mockReturnValue([]),
+    getMenuItems: vi.fn().mockReturnValue([]),
+    getPages: vi.fn().mockReturnValue([]),
+    getWidgets: vi.fn().mockReturnValue([]),
+    getConfig: vi.fn().mockReturnValue({}),
+    setConfig: vi.fn().mockResolvedValue(undefined),
+    subscribe: vi.fn().mockReturnValue(() => {}),
+    emit: vi.fn(),
+    registerHealthCheck: vi.fn(),
+    getApp: vi.fn().mockReturnValue({} as any),
+    getRouter: vi.fn().mockReturnValue({} as any),
+    getLogger: vi.fn().mockReturnValue({
       debug: vi.fn(),
       info: vi.fn(),
       warn: vi.fn(),
       error: vi.fn(),
-    },
-    registerHealthCheck: vi.fn(),
-  };
+    }),
+  });
+
+  let mockRegistry: PluginRegistry;
 
   beforeEach(() => {
     vi.clearAllMocks();
+    mockRegistry = createMockRegistry();
   });
 
   afterEach(async () => {
@@ -75,33 +116,34 @@ describe('Cache Plugin', () => {
   describe('createCachePlugin', () => {
     it('should create a plugin with correct name', () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      expect(plugin.name).toBe('cache:test');
+      expect(plugin.name).toBe('Redis Cache (test)');
     });
 
     it('should use "default" as instance name when not specified', () => {
       const plugin = createCachePlugin(mockConfig);
-      expect(plugin.name).toBe('cache:default');
+      expect(plugin.name).toBe('Redis Cache (default)');
     });
 
-    it('should have low order number (initialize early)', () => {
-      const plugin = createCachePlugin(mockConfig);
-      expect(plugin.order).toBeLessThan(10);
+    it('should have correct plugin id', () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      expect(plugin.id).toBe('cache:test');
     });
   });
 
-  describe('onInit', () => {
+  describe('onStart', () => {
     it('should register the cache instance', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       expect(hasCache('test')).toBe(true);
     });
 
     it('should log debug message on successful connection', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
-      expect(mockContext.logger.debug).toHaveBeenCalledWith(
+      const logger = mockRegistry.getLogger('cache:test');
+      expect(logger.debug).toHaveBeenCalledWith(
         expect.stringContaining('connected')
       );
     });
@@ -109,9 +151,9 @@ describe('Cache Plugin', () => {
     it('should register health check when enabled', async () => {
       const configWithHealth = { ...mockConfig, healthCheck: true };
       const plugin = createCachePlugin(configWithHealth, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
-      expect(mockContext.registerHealthCheck).toHaveBeenCalledWith(
+      expect(mockRegistry.registerHealthCheck).toHaveBeenCalledWith(
         expect.objectContaining({
           name: 'redis',
           type: 'custom',
@@ -126,9 +168,9 @@ describe('Cache Plugin', () => {
         healthCheckName: 'custom-cache',
       };
       const plugin = createCachePlugin(configWithCustomName, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
-      expect(mockContext.registerHealthCheck).toHaveBeenCalledWith(
+      expect(mockRegistry.registerHealthCheck).toHaveBeenCalledWith(
         expect.objectContaining({
           name: 'custom-cache',
         })
@@ -139,7 +181,7 @@ describe('Cache Plugin', () => {
   describe('getCache', () => {
     it('should return registered instance', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       expect(cache).toBeDefined();
@@ -162,7 +204,7 @@ describe('Cache Plugin', () => {
 
     it('should return true for registered instance', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       expect(hasCache('test')).toBe(true);
     });
@@ -171,7 +213,7 @@ describe('Cache Plugin', () => {
   describe('CacheInstance', () => {
     it('should get value and parse JSON', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       // Mock will return null by default
@@ -181,7 +223,7 @@ describe('Cache Plugin', () => {
 
     it('should set value with JSON stringification', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       await cache.set('key', { foo: 'bar' }, 3600);
@@ -190,7 +232,7 @@ describe('Cache Plugin', () => {
 
     it('should return cache stats', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       const stats = await cache.getStats();
@@ -200,7 +242,7 @@ describe('Cache Plugin', () => {
 
     it('should check if key exists', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       const exists = await cache.exists('key');
@@ -209,7 +251,7 @@ describe('Cache Plugin', () => {
 
     it('should get TTL for a key', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       const ttl = await cache.ttl('key');
@@ -218,22 +260,53 @@ describe('Cache Plugin', () => {
 
     it('should increment a value', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       const cache = getCache('test');
       const value = await cache.incr('counter');
       expect(typeof value).toBe('number');
     });
+
+    it('should scan keys using cursor-based iteration', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onStart({}, mockRegistry);
+
+      const cache = getCache('test');
+      const keys = await cache.scanKeys('*');
+
+      // Mock returns ['test:key1', 'test:key2', 'test:key3']
+      // After prefix removal, should be ['key1', 'key2', 'key3']
+      expect(Array.isArray(keys)).toBe(true);
+      expect(keys).toHaveLength(3);
+      expect(keys).toContain('key1');
+      expect(keys).toContain('key2');
+      expect(keys).toContain('key3');
+    });
+
+    it('should pass count option to scanStream', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onStart({}, mockRegistry);
+
+      const cache = getCache('test');
+      const client = cache.getClient();
+
+      await cache.scanKeys('*', { count: 500 });
+
+      expect(client.scanStream).toHaveBeenCalledWith({
+        match: 'test:*',
+        count: 500,
+      });
+    });
   });
 
-  describe('onShutdown', () => {
+  describe('onStop', () => {
     it('should close client and unregister instance', async () => {
       const plugin = createCachePlugin(mockConfig, 'test');
-      await plugin.onInit?.(mockContext as any);
+      await plugin.onStart({}, mockRegistry);
 
       expect(hasCache('test')).toBe(true);
 
-      await plugin.onShutdown?.();
+      await plugin.onStop();
 
       expect(hasCache('test')).toBe(false);
     });