@libredb/studio 0.9.7

package/src/lib/db/errors.ts

@@ -0,0 +1,317 @@
+/**
+ * Database Error Classes
+ * Custom error types for database operations
+ */
+
+import type { DatabaseType } from './types';
+import { ApiErrorCode } from '@/lib/api/error-codes';
+
+// ============================================================================
+// Base Database Error
+// ============================================================================
+
+/**
+ * Base error class for all database-related errors
+ */
+export class DatabaseError extends Error {
+  constructor(
+    message: string,
+    public readonly provider?: DatabaseType,
+    public readonly code?: ApiErrorCode,
+    public readonly query?: string
+  ) {
+    super(message);
+    this.name = 'DatabaseError';
+    Object.setPrototypeOf(this, DatabaseError.prototype);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      provider: this.provider,
+      code: this.code,
+      // Don't expose full query in production for security
+      query: this.query ? this.query.substring(0, 100) + '...' : undefined,
+    };
+  }
+}
+
+// ============================================================================
+// Configuration Errors
+// ============================================================================
+
+/**
+ * Configuration error - missing or invalid configuration
+ */
+export class DatabaseConfigError extends DatabaseError {
+  constructor(message: string, provider?: DatabaseType) {
+    super(message, provider, ApiErrorCode.CONFIG_ERROR);
+    this.name = 'DatabaseConfigError';
+    Object.setPrototypeOf(this, DatabaseConfigError.prototype);
+  }
+}
+
+// ============================================================================
+// Connection Errors
+// ============================================================================
+
+/**
+ * Connection error - failed to connect to database
+ */
+export class ConnectionError extends DatabaseError {
+  constructor(
+    message: string,
+    provider?: DatabaseType,
+    public readonly host?: string,
+    public readonly port?: number
+  ) {
+    super(message, provider, ApiErrorCode.CONNECTION_ERROR);
+    this.name = 'ConnectionError';
+    Object.setPrototypeOf(this, ConnectionError.prototype);
+  }
+}
+
+/**
+ * Authentication error - invalid credentials
+ */
+export class AuthenticationError extends DatabaseError {
+  constructor(message: string, provider?: DatabaseType) {
+    super(message, provider, ApiErrorCode.AUTH_ERROR);
+    this.name = 'AuthenticationError';
+    Object.setPrototypeOf(this, AuthenticationError.prototype);
+  }
+}
+
+/**
+ * Pool exhausted error - no available connections in pool
+ */
+export class PoolExhaustedError extends DatabaseError {
+  constructor(
+    message: string,
+    provider?: DatabaseType,
+    public readonly poolSize?: number
+  ) {
+    super(message, provider, ApiErrorCode.POOL_EXHAUSTED);
+    this.name = 'PoolExhaustedError';
+    Object.setPrototypeOf(this, PoolExhaustedError.prototype);
+  }
+}
+
+// ============================================================================
+// Query Errors
+// ============================================================================
+
+/**
+ * Query error - SQL syntax or execution error
+ */
+export class QueryError extends DatabaseError {
+  constructor(
+    message: string,
+    provider?: DatabaseType,
+    query?: string,
+    public readonly position?: number,
+    public readonly detail?: string
+  ) {
+    super(message, provider, ApiErrorCode.QUERY_ERROR, query);
+    this.name = 'QueryError';
+    Object.setPrototypeOf(this, QueryError.prototype);
+  }
+}
+
+/**
+ * Timeout error - query or connection timeout
+ */
+export class TimeoutError extends DatabaseError {
+  constructor(
+    message: string,
+    provider?: DatabaseType,
+    public readonly timeout?: number,
+    query?: string
+  ) {
+    super(message, provider, ApiErrorCode.TIMEOUT_ERROR, query);
+    this.name = 'TimeoutError';
+    Object.setPrototypeOf(this, TimeoutError.prototype);
+  }
+}
+
+/**
+ * Query cancelled error - user-initiated cancellation
+ */
+export class QueryCancelledError extends DatabaseError {
+  constructor(message: string, provider?: DatabaseType, query?: string) {
+    super(message, provider, ApiErrorCode.QUERY_CANCELLED, query);
+    this.name = 'QueryCancelledError';
+    Object.setPrototypeOf(this, QueryCancelledError.prototype);
+  }
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isDatabaseError(error: unknown): error is DatabaseError {
+  return error instanceof DatabaseError;
+}
+
+export function isConnectionError(error: unknown): error is ConnectionError {
+  return error instanceof ConnectionError;
+}
+
+export function isQueryError(error: unknown): error is QueryError {
+  return error instanceof QueryError;
+}
+
+export function isTimeoutError(error: unknown): error is TimeoutError {
+  return error instanceof TimeoutError;
+}
+
+export function isAuthenticationError(error: unknown): error is AuthenticationError {
+  return error instanceof AuthenticationError;
+}
+
+export function isQueryCancelledError(error: unknown): error is QueryCancelledError {
+  return error instanceof QueryCancelledError;
+}
+
+// ============================================================================
+// Error Mapping Utilities
+// ============================================================================
+
+/**
+ * Check if an error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (!isDatabaseError(error)) {
+    // Network errors are typically retryable
+    if (error instanceof TypeError && error.message.includes('fetch')) {
+      return true;
+    }
+    return false;
+  }
+
+  // Auth and config errors are not retryable
+  if (error instanceof AuthenticationError || error instanceof DatabaseConfigError) {
+    return false;
+  }
+
+  // Query syntax errors are not retryable
+  if (error instanceof QueryError && error.position !== undefined) {
+    return false;
+  }
+
+  // Connection and timeout errors may be retryable
+  return true;
+}
+
+/**
+ * Map native database errors to our error types
+ */
+export function mapDatabaseError(
+  error: unknown,
+  provider: DatabaseType,
+  query?: string
+): DatabaseError {
+  if (isDatabaseError(error)) {
+    return error;
+  }
+
+  if (!(error instanceof Error)) {
+    return new DatabaseError(String(error), provider);
+  }
+
+  const message = error.message.toLowerCase();
+
+  // Connection errors
+  if (
+    message.includes('econnrefused') ||
+    message.includes('connection refused') ||
+    message.includes('connect etimedout') ||
+    message.includes('getaddrinfo')
+  ) {
+    return new ConnectionError(
+      `Failed to connect to ${provider} database: ${error.message}`,
+      provider
+    );
+  }
+
+  // Authentication errors
+  if (
+    message.includes('password') ||
+    message.includes('authentication') ||
+    message.includes('access denied') ||
+    message.includes('permission denied')
+  ) {
+    return new AuthenticationError(
+      `Authentication failed: ${error.message}`,
+      provider
+    );
+  }
+
+  // Query cancellation (must check before timeout — 'canceling statement' is cancellation, not timeout)
+  if (
+    message.includes('canceling statement') ||
+    message.includes('query execution was interrupted') ||
+    message.includes('query was cancelled') ||
+    message.includes('kill query')
+  ) {
+    return new QueryCancelledError(
+      'Query was cancelled',
+      provider,
+      query
+    );
+  }
+
+  // Timeout errors
+  if (
+    message.includes('timeout') ||
+    message.includes('timed out')
+  ) {
+    return new TimeoutError(
+      `Query timeout: ${error.message}`,
+      provider,
+      undefined,
+      query
+    );
+  }
+
+  // Oracle errors
+  if (message.includes('ora-01017') || message.includes('invalid username/password')) {
+    return new AuthenticationError(`Authentication failed: ${error.message}`, provider);
+  }
+  if (message.includes('ora-12541') || message.includes('ora-12154') || message.includes('tns:')) {
+    return new ConnectionError(`Failed to connect to Oracle: ${error.message}`, provider);
+  }
+  if (message.includes('ora-00942')) {
+    return new QueryError(`Table or view does not exist: ${error.message}`, provider, query);
+  }
+
+  // MSSQL errors
+  if (message.includes('login failed')) {
+    return new AuthenticationError(`Authentication failed: ${error.message}`, provider);
+  }
+  if (message.includes('cannot open database')) {
+    return new ConnectionError(`Database not found: ${error.message}`, provider);
+  }
+
+  // Query errors (PostgreSQL specific)
+  if (message.includes('syntax error') || message.includes('column') || message.includes('relation')) {
+    return new QueryError(
+      error.message,
+      provider,
+      query,
+      (error as { position?: number }).position
+    );
+  }
+
+  // Pool errors
+  if (message.includes('pool') || message.includes('too many connections')) {
+    return new PoolExhaustedError(
+      `Connection pool error: ${error.message}`,
+      provider
+    );
+  }
+
+  // Generic database error
+  return new DatabaseError(error.message, provider, undefined, query);
+}

package/src/lib/db/factory.ts

@@ -0,0 +1,324 @@
+/**
+ * Database Provider Factory
+ * Creates appropriate provider instance based on connection type
+ * Uses dynamic imports to reduce memory footprint - providers are loaded on demand
+ */
+
+import {
+  type DatabaseProvider,
+  type DatabaseConnection,
+  type ProviderOptions,
+} from './types';
+import { DatabaseConfigError } from './errors';
+import { createSSHTunnel, closeSSHTunnel } from '@/lib/ssh/tunnel';
+import { logger } from '@/lib/logger';
+
+// ============================================================================
+// Provider Factory
+// ============================================================================
+
+/**
+ * Create a database provider based on connection configuration
+ * Uses dynamic imports to load providers on-demand, reducing initial memory usage
+ *
+ * @param connection - Database connection configuration
+ * @param options - Optional provider options (pooling, timeout, etc.)
+ * @returns Promise<DatabaseProvider> instance
+ * @throws DatabaseConfigError if connection type is not supported
+ *
+ * @example
+ * // SQL Database
+ * const provider = await createDatabaseProvider({
+ *   id: '1',
+ *   name: 'My PostgreSQL',
+ *   type: 'postgres',
+ *   host: 'localhost',
+ *   port: 5432,
+ *   database: 'mydb',
+ *   user: 'admin',
+ *   password: 'secret',
+ *   createdAt: new Date(),
+ * });
+ *
+ * // MongoDB
+ * const mongoProvider = await createDatabaseProvider({
+ *   id: '2',
+ *   name: 'My MongoDB',
+ *   type: 'mongodb',
+ *   connectionString: 'mongodb://localhost:27017/mydb',
+ *   createdAt: new Date(),
+ * });
+ *
+ * await provider.connect();
+ * const result = await provider.query('SELECT * FROM users');
+ * await provider.disconnect();
+ */
+export async function createDatabaseProvider(
+  connection: DatabaseConnection,
+  options: ProviderOptions = {}
+): Promise<DatabaseProvider> {
+  // Sanitize user-controlled values to prevent log injection
+  const sanitize = (v: string) => v.replace(/[\r\n]/g, ' ').replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
+  console.log(`[DB] Creating ${sanitize(connection.type)} provider for "${sanitize(connection.name || '')}"`);
+
+  switch (connection.type) {
+    // SQL Databases - dynamically imported to reduce memory
+    case 'postgres': {
+      const { PostgresProvider } = await import('./providers/sql/postgres');
+      return new PostgresProvider(connection, options);
+    }
+
+    case 'mysql': {
+      const { MySQLProvider } = await import('./providers/sql/mysql');
+      return new MySQLProvider(connection, options);
+    }
+
+    case 'sqlite': {
+      const { SQLiteProvider } = await import('./providers/sql/sqlite');
+      return new SQLiteProvider(connection, options);
+    }
+
+    case 'oracle': {
+      const { OracleProvider } = await import('./providers/sql/oracle');
+      return new OracleProvider(connection, options);
+    }
+
+    case 'mssql': {
+      const { MSSQLProvider } = await import('./providers/sql/mssql');
+      return new MSSQLProvider(connection, options);
+    }
+
+    // Document Databases - dynamically imported
+    case 'mongodb': {
+      const { MongoDBProvider } = await import('./providers/document/mongodb');
+      return new MongoDBProvider(connection, options);
+    }
+
+    // Key-Value Stores - dynamically imported
+    case 'redis': {
+      const { RedisProvider } = await import('./providers/keyvalue/redis');
+      return new RedisProvider(connection, options);
+    }
+
+    default:
+      throw new DatabaseConfigError(
+        `Unknown database type: ${connection.type}. Supported types: postgres, mysql, sqlite, oracle, mssql, mongodb, redis`,
+        connection.type
+      );
+  }
+}
+
+// ============================================================================
+// Provider Cache (for connection reuse)
+// ============================================================================
+
+interface CachedProvider {
+  provider: DatabaseProvider;
+  lastUsed: number;
+}
+
+const providerCache = new Map<string, CachedProvider>();
+
+/** Idle timeout: evict providers unused for 30 minutes */
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+/** Sweep interval: check for idle providers every 5 minutes */
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Evict providers that have been idle longer than maxIdleMs.
+ * Called by the periodic sweep timer, but also exported for direct testing.
+ *
+ * @returns number of evicted providers
+ */
+export async function evictIdleProviders(maxIdleMs: number = IDLE_TIMEOUT_MS): Promise<number> {
+  const now = Date.now();
+  let evicted = 0;
+
+  for (const [id, entry] of providerCache) {
+    if (now - entry.lastUsed >= maxIdleMs) {
+      logger.info(`[DB] Evicting idle provider: ${id} (idle ${Math.round((now - entry.lastUsed) / 60000)}min)`);
+      try {
+        await entry.provider.disconnect();
+      } catch (error) {
+        logger.warn(`[DB] Error disconnecting idle provider ${id}`, { connectionId: id, error: String(error) });
+      }
+      providerCache.delete(id);
+      // Also close SSH tunnel
+      try {
+        await closeSSHTunnel(id);
+      } catch { /* ignore */ }
+      evicted++;
+    }
+  }
+
+  // Stop sweeping if cache is empty
+  if (providerCache.size === 0 && sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+
+  return evicted;
+}
+
+function startIdleSweep(): void {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => { evictIdleProviders(); }, SWEEP_INTERVAL_MS);
+  // Allow process to exit even if timer is running
+  if (sweepTimer && typeof sweepTimer === 'object' && 'unref' in sweepTimer) {
+    sweepTimer.unref();
+  }
+}
+
+/**
+ * Get or create a database provider with caching
+ * Useful for API routes to reuse connections
+ *
+ * @param connection - Database connection configuration
+ * @param options - Optional provider options
+ * @returns Cached or new DatabaseProvider instance
+ */
+export async function getOrCreateProvider(
+  connection: DatabaseConnection,
+  options: ProviderOptions = {}
+): Promise<DatabaseProvider> {
+  const cacheKey = connection.id;
+
+  // Check cache
+  const cached = providerCache.get(cacheKey);
+
+  if (cached?.provider.isConnected()) {
+    cached.lastUsed = Date.now();
+    return cached.provider;
+  }
+
+  // If SSH tunnel is configured, create tunnel first and rewrite connection
+  let effectiveConnection = connection;
+  let tunnel: Awaited<ReturnType<typeof createSSHTunnel>> | null = null;
+  if (connection.sshTunnel?.enabled && connection.host && connection.port) {
+    tunnel = await createSSHTunnel(
+      connection.id,
+      connection.sshTunnel,
+      connection.host,
+      connection.port
+    );
+    // Rewrite connection to point to local tunnel endpoint
+    effectiveConnection = {
+      ...connection,
+      host: tunnel.localHost,
+      port: tunnel.localPort,
+    };
+  }
+
+  // Create new provider (async - dynamically loads the provider module)
+  const provider = await createDatabaseProvider(effectiveConnection, options);
+  try {
+    await provider.connect();
+  } catch (error) {
+    // Clean up SSH tunnel if provider connect fails to prevent FD leak
+    if (tunnel) {
+      await tunnel.close().catch(() => {});
+    }
+    throw error;
+  }
+
+  // Cache it
+  providerCache.set(cacheKey, { provider, lastUsed: Date.now() });
+
+  // Start idle sweep if not already running
+  startIdleSweep();
+
+  return provider;
+}
+
+/**
+ * Remove a provider from cache and disconnect
+ */
+export async function removeProvider(connectionId: string): Promise<void> {
+  const cached = providerCache.get(connectionId);
+
+  if (cached) {
+    try {
+      await cached.provider.disconnect();
+    } catch (error) {
+      logger.warn(`Error disconnecting provider ${connectionId}`, { connectionId, error: String(error) });
+    }
+    providerCache.delete(connectionId);
+  }
+
+  // Close SSH tunnel if exists
+  try {
+    await closeSSHTunnel(connectionId);
+  } catch (error) {
+    logger.warn(`Error closing SSH tunnel for ${connectionId}`, { connectionId, error: String(error) });
+  }
+}
+
+/**
+ * Clear all cached providers
+ */
+export async function clearProviderCache(): Promise<void> {
+  // Stop idle sweep
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+
+  const disconnectPromises: Promise<void>[] = [];
+
+  for (const [id, entry] of providerCache) {
+    disconnectPromises.push(
+      entry.provider.disconnect().catch((error) => {
+        console.error(`[DB] Error disconnecting provider ${id}:`, error);
+      })
+    );
+  }
+
+  await Promise.all(disconnectPromises);
+  providerCache.clear();
+}
+
+/**
+ * Get cache statistics
+ */
+export function getProviderCacheStats(): { size: number; connections: string[] } {
+  return {
+    size: providerCache.size,
+    connections: Array.from(providerCache.keys()),
+  };
+}
+
+// ============================================================================
+// Graceful Shutdown
+// ============================================================================
+
+let shutdownRegistered = false;
+
+/**
+ * Register process signal handlers for graceful shutdown.
+ * Safe to call multiple times — handlers are only registered once.
+ */
+export function registerShutdownHandlers(): void {
+  if (shutdownRegistered) return;
+  shutdownRegistered = true;
+
+  const shutdown = async (signal: string) => {
+    logger.info(`[DB] Received ${signal}, closing all database connections...`);
+    try {
+      await clearProviderCache();
+      logger.info('[DB] All database connections closed gracefully');
+    } catch (error) {
+      logger.error('[DB] Error during graceful shutdown', { error: String(error) });
+    }
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+// Auto-register on server-side (not during tests)
+if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'test') {
+  registerShutdownHandlers();
+}