@qwickapps/server 1.1.6 → 1.1.9

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

@@ -0,0 +1,213 @@
+/**
+ * PostgreSQL Plugin Tests
+ *
+ * Note: These tests use mocks since we don't want to require a real database.
+ * Integration tests should be run separately with a real PostgreSQL instance.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock pg before importing the plugin
+vi.mock('pg', () => {
+  const mockClient = {
+    query: vi.fn().mockResolvedValue({ rows: [] }),
+    release: vi.fn(),
+  };
+
+  const mockPool = {
+    connect: vi.fn().mockResolvedValue(mockClient),
+    query: vi.fn().mockResolvedValue({ rows: [] }),
+    end: vi.fn().mockResolvedValue(undefined),
+    on: vi.fn(),
+    totalCount: 5,
+    idleCount: 3,
+    waitingCount: 0,
+  };
+
+  return {
+    default: {
+      Pool: vi.fn(() => mockPool),
+    },
+    Pool: vi.fn(() => mockPool),
+  };
+});
+
+import {
+  createPostgresPlugin,
+  getPostgres,
+  hasPostgres,
+  type PostgresPluginConfig,
+} from './postgres-plugin.js';
+
+describe('PostgreSQL Plugin', () => {
+  const mockConfig: PostgresPluginConfig = {
+    url: 'postgresql://test:test@localhost:5432/testdb',
+    maxConnections: 10,
+    healthCheck: false, // Disable for unit tests
+  };
+
+  const mockContext = {
+    config: { productName: 'Test', port: 3000 },
+    app: {} as any,
+    router: {} as any,
+    logger: {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    registerHealthCheck: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    // Clean up any registered instances
+    if (hasPostgres('test')) {
+      const db = getPostgres('test');
+      await db.close();
+    }
+  });
+
+  describe('createPostgresPlugin', () => {
+    it('should create a plugin with correct name', () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      expect(plugin.name).toBe('postgres:test');
+    });
+
+    it('should use "default" as instance name when not specified', () => {
+      const plugin = createPostgresPlugin(mockConfig);
+      expect(plugin.name).toBe('postgres:default');
+    });
+
+    it('should have low order number (initialize early)', () => {
+      const plugin = createPostgresPlugin(mockConfig);
+      expect(plugin.order).toBeLessThan(10);
+    });
+  });
+
+  describe('onInit', () => {
+    it('should register the postgres instance', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(hasPostgres('test')).toBe(true);
+    });
+
+    it('should log debug message on successful connection', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(mockContext.logger.debug).toHaveBeenCalledWith(
+        expect.stringContaining('connected')
+      );
+    });
+
+    it('should register health check when enabled', async () => {
+      const configWithHealth = { ...mockConfig, healthCheck: true };
+      const plugin = createPostgresPlugin(configWithHealth, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(mockContext.registerHealthCheck).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'postgres',
+          type: 'custom',
+        })
+      );
+    });
+
+    it('should use custom health check name when provided', async () => {
+      const configWithCustomName = {
+        ...mockConfig,
+        healthCheck: true,
+        healthCheckName: 'custom-db',
+      };
+      const plugin = createPostgresPlugin(configWithCustomName, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(mockContext.registerHealthCheck).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'custom-db',
+        })
+      );
+    });
+  });
+
+  describe('getPostgres', () => {
+    it('should return registered instance', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const db = getPostgres('test');
+      expect(db).toBeDefined();
+      expect(db.query).toBeDefined();
+      expect(db.queryOne).toBeDefined();
+      expect(db.transaction).toBeDefined();
+    });
+
+    it('should throw error for unregistered instance', () => {
+      expect(() => getPostgres('nonexistent')).toThrow(
+        'PostgreSQL instance "nonexistent" not found'
+      );
+    });
+  });
+
+  describe('hasPostgres', () => {
+    it('should return false for unregistered instance', () => {
+      expect(hasPostgres('nonexistent')).toBe(false);
+    });
+
+    it('should return true for registered instance', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(hasPostgres('test')).toBe(true);
+    });
+  });
+
+  describe('PostgresInstance', () => {
+    it('should execute query and return rows', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const db = getPostgres('test');
+      const result = await db.query('SELECT 1');
+      expect(result).toEqual([]);
+    });
+
+    it('should return null from queryOne when no rows', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const db = getPostgres('test');
+      const result = await db.queryOne('SELECT 1');
+      expect(result).toBeNull();
+    });
+
+    it('should return pool stats', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const db = getPostgres('test');
+      const stats = db.getStats();
+      expect(stats).toHaveProperty('total');
+      expect(stats).toHaveProperty('idle');
+      expect(stats).toHaveProperty('waiting');
+    });
+  });
+
+  describe('onShutdown', () => {
+    it('should close pool and unregister instance', async () => {
+      const plugin = createPostgresPlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(hasPostgres('test')).toBe(true);
+
+      await plugin.onShutdown?.();
+
+      expect(hasPostgres('test')).toBe(false);
+    });
+  });
+});

package/src/plugins/postgres-plugin.ts

@@ -0,0 +1,345 @@
+/**
+ * PostgreSQL Plugin
+ *
+ * Provides PostgreSQL database connection pooling and health checks.
+ * Wraps the 'pg' library with a simple, reusable interface.
+ *
+ * ## Features
+ * - Connection pooling with configurable limits
+ * - Automatic health checks with pool stats
+ * - Transaction helpers
+ * - Multiple named instances support
+ * - Graceful shutdown
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createGateway, createPostgresPlugin, getPostgres } from '@qwickapps/server';
+ *
+ * const gateway = createGateway({
+ *   // ... config
+ *   plugins: [
+ *     createPostgresPlugin({
+ *       url: process.env.DATABASE_URL,
+ *       maxConnections: 20,
+ *     }),
+ *   ],
+ * });
+ *
+ * // In your service code:
+ * const db = getPostgres();
+ * const users = await db.query<User>('SELECT * FROM users WHERE active = $1', [true]);
+ * ```
+ *
+ * ## Multiple Databases
+ *
+ * ```typescript
+ * // Register multiple databases with different names
+ * createPostgresPlugin({ url: primaryUrl }, 'primary');
+ * createPostgresPlugin({ url: replicaUrl }, 'replica');
+ *
+ * // Access by name
+ * const primary = getPostgres('primary');
+ * const replica = getPostgres('replica');
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import pg from 'pg';
+import type { ControlPanelPlugin, PluginContext } from '../core/types.js';
+
+const { Pool } = pg;
+
+/**
+ * Configuration for the PostgreSQL plugin
+ */
+export interface PostgresPluginConfig {
+  /** Database connection URL (e.g., postgresql://user:pass@host:5432/db) */
+  url: string;
+
+  /** Maximum number of clients in the pool (default: 20) */
+  maxConnections?: number;
+
+  /** Minimum number of clients in the pool (default: 2) */
+  minConnections?: number;
+
+  /** Idle timeout in milliseconds - close idle clients after this time (default: 30000) */
+  idleTimeoutMs?: number;
+
+  /** Connection timeout in milliseconds - fail if can't connect within this time (default: 5000) */
+  connectionTimeoutMs?: number;
+
+  /** Statement timeout in milliseconds - cancel queries taking longer (default: none) */
+  statementTimeoutMs?: number;
+
+  /** Register a health check for this database (default: true) */
+  healthCheck?: boolean;
+
+  /** Name for the health check (default: 'postgres') */
+  healthCheckName?: string;
+
+  /** Health check interval in milliseconds (default: 30000) */
+  healthCheckInterval?: number;
+
+  /** Called when a client connects (for setup like setting search_path) */
+  onConnect?: (client: pg.PoolClient) => Promise<void>;
+
+  /** Called on pool errors */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Transaction callback function
+ */
+export type TransactionCallback<T> = (client: pg.PoolClient) => Promise<T>;
+
+/**
+ * PostgreSQL instance returned by the plugin
+ */
+export interface PostgresInstance {
+  /** Get a client from the pool (remember to release it!) */
+  getClient(): Promise<pg.PoolClient>;
+
+  /** Execute a query and return rows */
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+
+  /** Execute a query and return first row or null */
+  queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+
+  /** Execute a query and return the full result (includes rowCount, etc.) */
+  queryRaw(sql: string, params?: unknown[]): Promise<pg.QueryResult>;
+
+  /**
+   * Execute multiple queries in a transaction
+   *
+   * @example
+   * ```typescript
+   * const result = await db.transaction(async (client) => {
+   *   await client.query('INSERT INTO users (name) VALUES ($1)', ['Alice']);
+   *   await client.query('INSERT INTO audit_log (action) VALUES ($1)', ['user_created']);
+   *   return { success: true };
+   * });
+   * ```
+   */
+  transaction<T>(callback: TransactionCallback<T>): Promise<T>;
+
+  /** Get the underlying pool (for advanced use cases) */
+  getPool(): pg.Pool;
+
+  /** Get pool statistics */
+  getStats(): { total: number; idle: number; waiting: number };
+
+  /** Close all connections */
+  close(): Promise<void>;
+}
+
+// Global registry of PostgreSQL instances by name
+const instances = new Map<string, PostgresInstance>();
+
+/**
+ * Get a PostgreSQL instance by name
+ *
+ * @param name - Instance name (default: 'default')
+ * @returns The PostgreSQL instance
+ * @throws Error if the instance is not registered
+ *
+ * @example
+ * ```typescript
+ * const db = getPostgres();
+ * const users = await db.query<User>('SELECT * FROM users');
+ * ```
+ */
+export function getPostgres(name = 'default'): PostgresInstance {
+  const instance = instances.get(name);
+  if (!instance) {
+    throw new Error(`PostgreSQL instance "${name}" not found. Did you register the postgres plugin?`);
+  }
+  return instance;
+}
+
+/**
+ * Check if a PostgreSQL instance is registered
+ *
+ * @param name - Instance name (default: 'default')
+ * @returns true if the instance exists
+ */
+export function hasPostgres(name = 'default'): boolean {
+  return instances.has(name);
+}
+
+/**
+ * Create a PostgreSQL plugin
+ *
+ * @param config - PostgreSQL configuration
+ * @param instanceName - Name for this PostgreSQL instance (default: 'default')
+ * @returns A control panel plugin
+ *
+ * @example
+ * ```typescript
+ * createPostgresPlugin({
+ *   url: process.env.DATABASE_URL,
+ *   maxConnections: 20,
+ *   healthCheck: true,
+ * });
+ * ```
+ */
+export function createPostgresPlugin(
+  config: PostgresPluginConfig,
+  instanceName = 'default'
+): ControlPanelPlugin {
+  let pool: pg.Pool | null = null;
+
+  const createInstance = (): PostgresInstance => {
+    if (!pool) {
+      pool = new Pool({
+        connectionString: config.url,
+        max: config.maxConnections ?? 20,
+        min: config.minConnections ?? 2,
+        idleTimeoutMillis: config.idleTimeoutMs ?? 30000,
+        connectionTimeoutMillis: config.connectionTimeoutMs ?? 5000,
+        statement_timeout: config.statementTimeoutMs,
+      });
+
+      // Handle pool errors
+      pool.on('error', (err) => {
+        if (config.onError) {
+          config.onError(err);
+        } else {
+          console.error(`[database:${instanceName}] Pool error:`, err.message);
+        }
+      });
+
+      // Call onConnect for each new client
+      if (config.onConnect) {
+        pool.on('connect', (client) => {
+          config.onConnect!(client).catch((err) => {
+            console.error(`[database:${instanceName}] onConnect error:`, err.message);
+          });
+        });
+      }
+    }
+
+    const instance: PostgresInstance = {
+      async getClient(): Promise<pg.PoolClient> {
+        if (!pool) throw new Error('Database pool not initialized');
+        return pool.connect();
+      },
+
+      async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+        if (!pool) throw new Error('Database pool not initialized');
+        const result = await pool.query(sql, params);
+        return result.rows as T[];
+      },
+
+      async queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+        const rows = await instance.query<T>(sql, params);
+        return rows[0] ?? null;
+      },
+
+      async queryRaw(sql: string, params?: unknown[]): Promise<pg.QueryResult> {
+        if (!pool) throw new Error('Database pool not initialized');
+        return pool.query(sql, params);
+      },
+
+      async transaction<T>(callback: TransactionCallback<T>): Promise<T> {
+        const client = await instance.getClient();
+        try {
+          await client.query('BEGIN');
+          const result = await callback(client);
+          await client.query('COMMIT');
+          return result;
+        } catch (err) {
+          await client.query('ROLLBACK');
+          throw err;
+        } finally {
+          client.release();
+        }
+      },
+
+      getPool(): pg.Pool {
+        if (!pool) throw new Error('Database pool not initialized');
+        return pool;
+      },
+
+      getStats(): { total: number; idle: number; waiting: number } {
+        return {
+          total: pool?.totalCount ?? 0,
+          idle: pool?.idleCount ?? 0,
+          waiting: pool?.waitingCount ?? 0,
+        };
+      },
+
+      async close(): Promise<void> {
+        if (pool) {
+          await pool.end();
+          pool = null;
+        }
+      },
+    };
+
+    return instance;
+  };
+
+  return {
+    name: `postgres:${instanceName}`,
+    order: 5, // Initialize early, before other plugins that may need DB
+
+    async onInit(context: PluginContext): Promise<void> {
+      const { registerHealthCheck, logger } = context;
+
+      // Create and register the instance
+      const instance = createInstance();
+      instances.set(instanceName, instance);
+
+      // Test connection
+      try {
+        await instance.query('SELECT 1');
+        logger.debug(`PostgreSQL "${instanceName}" connected`);
+      } catch (err) {
+        logger.error(`PostgreSQL "${instanceName}" connection failed: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+      }
+
+      // Register health check if enabled
+      if (config.healthCheck !== false) {
+        registerHealthCheck({
+          name: config.healthCheckName ?? 'postgres',
+          type: 'custom',
+          interval: config.healthCheckInterval ?? 30000,
+          timeout: 5000,
+          check: async () => {
+            const start = Date.now();
+            try {
+              await instance.query('SELECT 1');
+              const stats = instance.getStats();
+              return {
+                healthy: true,
+                latency: Date.now() - start,
+                details: {
+                  pool: stats,
+                },
+              };
+            } catch (err) {
+              return {
+                healthy: false,
+                latency: Date.now() - start,
+                details: {
+                  error: err instanceof Error ? err.message : String(err),
+                },
+              };
+            }
+          },
+        });
+      }
+    },
+
+    async onShutdown(): Promise<void> {
+      const instance = instances.get(instanceName);
+      if (instance) {
+        await instance.close();
+        instances.delete(instanceName);
+      }
+    },
+  };
+}

package/ui/src/api/controlPanelApi.ts

@@ -59,7 +59,7 @@ export interface LogEntry {
   timestamp: string;
   level: string;
   message: string;
-  source?: string;
+  namespace?: string;
 }
 
 export interface LogsResponse {

package/ui/src/pages/LogsPage.tsx

@@ -202,11 +202,9 @@ export function LogsPage() {
                     <TableCell sx={{ color: 'var(--theme-text-secondary)', borderColor: 'var(--theme-border)', width: 100 }}>
                       Level
                     </TableCell>
-                    {sources.length > 0 && (
-                      <TableCell sx={{ color: 'var(--theme-text-secondary)', borderColor: 'var(--theme-border)', width: 120 }}>
-                        Source
-                      </TableCell>
-                    )}
+                    <TableCell sx={{ color: 'var(--theme-text-secondary)', borderColor: 'var(--theme-border)', width: 120 }}>
+                      Component
+                    </TableCell>
                     <TableCell sx={{ color: 'var(--theme-text-secondary)', borderColor: 'var(--theme-border)' }}>
                       Message
                     </TableCell>
@@ -230,11 +228,9 @@ export function LogsPage() {
                           }}
                         />
                       </TableCell>
-                      {sources.length > 0 && (
-                        <TableCell sx={{ color: 'var(--theme-text-secondary)', borderColor: 'var(--theme-border)' }}>
-                          {log.source || '-'}
-                        </TableCell>
-                      )}
+                      <TableCell sx={{ color: 'var(--theme-text-secondary)', borderColor: 'var(--theme-border)', fontSize: '0.75rem' }}>
+                        {log.namespace || '-'}
+                      </TableCell>
                       <TableCell sx={{ color: 'var(--theme-text-primary)', borderColor: 'var(--theme-border)', fontFamily: 'monospace', fontSize: '0.8rem', whiteSpace: 'pre-wrap', wordBreak: 'break-all' }}>
                         {log.message}
                       </TableCell>