spindb 0.4.1 → 0.5.3

package/core/port-manager.ts

@@ -3,12 +3,21 @@ import { exec } from 'child_process'
 import { promisify } from 'util'
 import { existsSync } from 'fs'
 import { readdir, readFile } from 'fs/promises'
-import { defaults } from '../config/defaults'
+import { defaults, getSupportedEngines } from '../config/defaults'
 import { paths } from '../config/paths'
+import { logDebug } from './error-handler'
 import type { ContainerConfig, PortResult } from '../types'
 
 const execAsync = promisify(exec)
 
+/**
+ * Options for finding an available port
+ */
+type FindPortOptions = {
+  preferredPort?: number
+  portRange?: { start: number; end: number }
+}
+
 export class PortManager {
   /**
    * Check if a specific port is available
@@ -36,12 +45,13 @@ export class PortManager {
   }
 
   /**
-   * Find the next available port starting from the default
+   * Find the next available port starting from the preferred port
    * Returns the port number and whether it's the default port
    */
-  async findAvailablePort(
-    preferredPort: number = defaults.port,
-  ): Promise<PortResult> {
+  async findAvailablePort(options: FindPortOptions = {}): Promise<PortResult> {
+    const preferredPort = options.preferredPort ?? defaults.port
+    const portRange = options.portRange ?? defaults.portRange
+
     // First try the preferred port
     if (await this.isPortAvailable(preferredPort)) {
       return {
@@ -51,11 +61,7 @@ export class PortManager {
     }
 
     // Scan for available ports in the range
-    for (
-      let port = defaults.portRange.start;
-      port <= defaults.portRange.end;
-      port++
-    ) {
+    for (let port = portRange.start; port <= portRange.end; port++) {
       if (port === preferredPort) continue // Already tried this one
 
       if (await this.isPortAvailable(port)) {
@@ -67,7 +73,7 @@ export class PortManager {
     }
 
     throw new Error(
-      `No available ports found in range ${defaults.portRange.start}-${defaults.portRange.end}`,
+      `No available ports found in range ${portRange.start}-${portRange.end}`,
     )
   }
 
@@ -78,13 +84,17 @@ export class PortManager {
     try {
       const { stdout } = await execAsync(`lsof -i :${port} -P -n | head -5`)
       return stdout.trim()
-    } catch {
+    } catch (error) {
+      logDebug('Could not determine port user', {
+        port,
+        error: error instanceof Error ? error.message : String(error),
+      })
       return null
     }
   }
 
   /**
-   * Get all ports currently assigned to containers
+   * Get all ports currently assigned to containers across all engines
    */
   async getContainerPorts(): Promise<number[]> {
     const containersDir = paths.containers
@@ -94,18 +104,29 @@ export class PortManager {
     }
 
     const ports: number[] = []
-    const entries = await readdir(containersDir, { withFileTypes: true })
-
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        const configPath = `${containersDir}/${entry.name}/container.json`
-        if (existsSync(configPath)) {
-          try {
-            const content = await readFile(configPath, 'utf8')
-            const config = JSON.parse(content) as ContainerConfig
-            ports.push(config.port)
-          } catch {
-            // Skip invalid configs
+    const engines = getSupportedEngines()
+
+    for (const engine of engines) {
+      const engineDir = paths.getEngineContainersPath(engine)
+      if (!existsSync(engineDir)) continue
+
+      const entries = await readdir(engineDir, { withFileTypes: true })
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const configPath = paths.getContainerConfigPath(entry.name, {
+            engine,
+          })
+          if (existsSync(configPath)) {
+            try {
+              const content = await readFile(configPath, 'utf8')
+              const config = JSON.parse(content) as ContainerConfig
+              ports.push(config.port)
+            } catch (error) {
+              logDebug('Skipping invalid container config', {
+                configPath,
+                error: error instanceof Error ? error.message : String(error),
+              })
+            }
           }
         }
       }
@@ -118,8 +139,10 @@ export class PortManager {
    * Find an available port that's not in use by any process AND not assigned to any container
    */
   async findAvailablePortExcludingContainers(
-    preferredPort: number = defaults.port,
+    options: FindPortOptions = {},
   ): Promise<PortResult> {
+    const preferredPort = options.preferredPort ?? defaults.port
+    const portRange = options.portRange ?? defaults.portRange
     const containerPorts = await this.getContainerPorts()
 
     // First try the preferred port
@@ -134,11 +157,7 @@ export class PortManager {
     }
 
     // Scan for available ports in the range
-    for (
-      let port = defaults.portRange.start;
-      port <= defaults.portRange.end;
-      port++
-    ) {
+    for (let port = portRange.start; port <= portRange.end; port++) {
       if (containerPorts.includes(port)) continue // Skip ports used by containers
       if (port === preferredPort) continue // Already tried this one
 
@@ -151,7 +170,7 @@ export class PortManager {
     }
 
     throw new Error(
-      `No available ports found in range ${defaults.portRange.start}-${defaults.portRange.end}`,
+      `No available ports found in range ${portRange.start}-${portRange.end}`,
     )
   }
 }

package/core/process-manager.ts

@@ -3,6 +3,7 @@ import { promisify } from 'util'
 import { existsSync } from 'fs'
 import { readFile } from 'fs/promises'
 import { paths } from '../config/paths'
+import { logDebug } from './error-handler'
 import type { ProcessResult, StatusResult } from '../types'
 
 const execAsync = promisify(exec)
@@ -202,10 +203,14 @@ export class ProcessManager {
   }
 
   /**
-   * Check if PostgreSQL is running by looking for PID file
+   * Check if a database server is running by looking for PID file
    */
-  async isRunning(containerName: string): Promise<boolean> {
-    const pidFile = paths.getContainerPidPath(containerName)
+  async isRunning(
+    containerName: string,
+    options: { engine: string },
+  ): Promise<boolean> {
+    const { engine } = options
+    const pidFile = paths.getContainerPidPath(containerName, { engine })
     if (!existsSync(pidFile)) {
       return false
     }
@@ -217,16 +222,25 @@ export class ProcessManager {
       // Check if process is still running
       process.kill(pid, 0)
       return true
-    } catch {
+    } catch (error) {
+      logDebug('PID file check failed', {
+        containerName,
+        engine: options.engine,
+        error: error instanceof Error ? error.message : String(error),
+      })
       return false
     }
   }
 
   /**
-   * Get the PID of a running PostgreSQL server
+   * Get the PID of a running database server
    */
-  async getPid(containerName: string): Promise<number | null> {
-    const pidFile = paths.getContainerPidPath(containerName)
+  async getPid(
+    containerName: string,
+    options: { engine: string },
+  ): Promise<number | null> {
+    const { engine } = options
+    const pidFile = paths.getContainerPidPath(containerName, { engine })
     if (!existsSync(pidFile)) {
       return null
     }
@@ -234,7 +248,11 @@ export class ProcessManager {
     try {
       const content = await readFile(pidFile, 'utf8')
       return parseInt(content.split('\n')[0], 10)
-    } catch {
+    } catch (error) {
+      logDebug('Failed to read PID file', {
+        pidFile,
+        error: error instanceof Error ? error.message : String(error),
+      })
       return null
     }
   }

package/core/start-with-retry.ts

@@ -0,0 +1,167 @@
+/**
+ * Start with Retry
+ *
+ * Handles port race conditions by automatically retrying with a new port
+ * when the original port becomes unavailable between check and bind.
+ */
+
+import { portManager } from './port-manager'
+import { containerManager } from './container-manager'
+import { logWarning, logDebug } from './error-handler'
+import type { BaseEngine } from '../engines/base-engine'
+import type { ContainerConfig } from '../types'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type StartWithRetryOptions = {
+  engine: BaseEngine
+  config: ContainerConfig
+  maxRetries?: number // Default: 3
+  onPortChange?: (oldPort: number, newPort: number) => void
+}
+
+export type StartWithRetryResult = {
+  success: boolean
+  finalPort: number
+  retriesUsed: number
+  error?: Error
+}
+
+// =============================================================================
+// Port Error Detection
+// =============================================================================
+
+/**
+ * Check if an error is a port-in-use error
+ */
+function isPortInUseError(err: unknown): boolean {
+  const message = (err as Error)?.message?.toLowerCase() || ''
+  return (
+    message.includes('address already in use') ||
+    message.includes('eaddrinuse') ||
+    (message.includes('port') && message.includes('in use')) ||
+    message.includes('could not bind') ||
+    message.includes('socket already in use')
+  )
+}
+
+// =============================================================================
+// Start with Retry Implementation
+// =============================================================================
+
+/**
+ * Start a database container with automatic port retry on conflict
+ *
+ * This handles the race condition where a port is available when checked
+ * but taken by the time the database server tries to bind to it.
+ */
+export async function startWithRetry(
+  options: StartWithRetryOptions,
+): Promise<StartWithRetryResult> {
+  const { engine, config, maxRetries = 3, onPortChange } = options
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      logDebug(`Starting ${engine.name} (attempt ${attempt}/${maxRetries})`, {
+        containerName: config.name,
+        port: config.port,
+      })
+
+      await engine.start(config)
+
+      return {
+        success: true,
+        finalPort: config.port,
+        retriesUsed: attempt - 1,
+      }
+    } catch (err) {
+      const isPortError = isPortInUseError(err)
+
+      logDebug(`Start attempt ${attempt} failed`, {
+        containerName: config.name,
+        port: config.port,
+        isPortError,
+        error: err instanceof Error ? err.message : String(err),
+      })
+
+      if (isPortError && attempt < maxRetries) {
+        const oldPort = config.port
+
+        // Find a new available port, excluding the one that just failed
+        const { port: newPort } = await portManager.findAvailablePort({
+          portRange: getEnginePortRange(config.engine),
+        })
+
+        // Update config with new port
+        config.port = newPort
+        await containerManager.updateConfig(config.name, { port: newPort })
+
+        // Notify caller of port change
+        if (onPortChange) {
+          onPortChange(oldPort, newPort)
+        }
+
+        // Log and retry
+        logWarning(
+          `Port ${oldPort} is in use, retrying with port ${newPort}...`,
+        )
+        continue
+      }
+
+      // Not a port error or max retries exceeded
+      return {
+        success: false,
+        finalPort: config.port,
+        retriesUsed: attempt - 1,
+        error: err instanceof Error ? err : new Error(String(err)),
+      }
+    }
+  }
+
+  // Should never reach here, but TypeScript needs a return
+  return {
+    success: false,
+    finalPort: config.port,
+    retriesUsed: maxRetries,
+    error: new Error('Max retries exceeded'),
+  }
+}
+
+/**
+ * Get the port range for an engine
+ */
+function getEnginePortRange(engine: string): { start: number; end: number } {
+  // Import defaults dynamically to avoid circular dependency
+  // These are the standard ranges from config/defaults.ts
+  if (engine === 'postgresql') {
+    return { start: 5432, end: 5500 }
+  }
+  if (engine === 'mysql') {
+    return { start: 3306, end: 3400 }
+  }
+  // Default fallback range
+  return { start: 5432, end: 6000 }
+}
+
+/**
+ * Wrapper that simplifies the common use case
+ */
+export async function startContainerWithRetry(
+  engine: BaseEngine,
+  config: ContainerConfig,
+  options?: {
+    onPortChange?: (oldPort: number, newPort: number) => void
+  },
+): Promise<void> {
+  const result = await startWithRetry({
+    engine,
+    config,
+    onPortChange: options?.onPortChange,
+  })
+
+  if (!result.success && result.error) {
+    throw result.error
+  }
+}

package/core/transaction-manager.ts

@@ -0,0 +1,170 @@
+/**
+ * Transaction Manager
+ *
+ * Provides rollback support for multi-step operations like container creation.
+ * If any step fails, all previously completed steps are rolled back in reverse order.
+ */
+
+import { logError, logDebug, ErrorCodes } from './error-handler'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type RollbackAction = {
+  description: string
+  execute: () => Promise<void>
+}
+
+// =============================================================================
+// Transaction Manager Implementation
+// =============================================================================
+
+/**
+ * Manages a stack of rollback actions for transactional operations.
+ *
+ * Usage:
+ * ```typescript
+ * const tx = new TransactionManager()
+ *
+ * try {
+ *   await createDirectory()
+ *   tx.addRollback({
+ *     description: 'Delete directory',
+ *     execute: () => deleteDirectory()
+ *   })
+ *
+ *   await initDatabase()
+ *   // Directory rollback covers this too
+ *
+ *   await startServer()
+ *   tx.addRollback({
+ *     description: 'Stop server',
+ *     execute: () => stopServer()
+ *   })
+ *
+ *   tx.commit() // Success - clear rollback stack
+ * } catch (err) {
+ *   await tx.rollback() // Error - undo everything
+ *   throw err
+ * }
+ * ```
+ */
+export class TransactionManager {
+  private rollbackStack: RollbackAction[] = []
+  private committed = false
+
+  /**
+   * Add a rollback action to the stack.
+   * Actions are executed in reverse order during rollback.
+   */
+  addRollback(action: RollbackAction): void {
+    if (this.committed) {
+      throw new Error('Cannot add rollback action after commit')
+    }
+    this.rollbackStack.push(action)
+    logDebug(`Added rollback action: ${action.description}`, {
+      totalActions: this.rollbackStack.length,
+    })
+  }
+
+  /**
+   * Execute all rollbacks in reverse order.
+   * Continues even if individual rollback actions fail.
+   */
+  async rollback(): Promise<void> {
+    if (this.committed) {
+      logDebug('Skipping rollback - transaction was committed')
+      return
+    }
+
+    if (this.rollbackStack.length === 0) {
+      logDebug('No rollback actions to execute')
+      return
+    }
+
+    logDebug(`Starting rollback of ${this.rollbackStack.length} actions`)
+
+    // Execute in reverse order (LIFO)
+    while (this.rollbackStack.length > 0) {
+      const action = this.rollbackStack.pop()!
+
+      try {
+        logDebug(`Executing rollback: ${action.description}`)
+        await action.execute()
+        logDebug(`Rollback successful: ${action.description}`)
+      } catch (err) {
+        // Log error but continue with other rollbacks
+        logError({
+          code: ErrorCodes.ROLLBACK_FAILED,
+          message: `Failed to rollback: ${action.description}`,
+          severity: 'warning',
+          context: {
+            error: err instanceof Error ? err.message : String(err),
+          },
+        })
+      }
+    }
+
+    logDebug('Rollback complete')
+  }
+
+  /**
+   * Mark the transaction as committed.
+   * Clears the rollback stack since we don't need to undo anything.
+   */
+  commit(): void {
+    if (this.committed) {
+      return // Already committed
+    }
+
+    logDebug(`Committing transaction with ${this.rollbackStack.length} actions`)
+    this.rollbackStack = []
+    this.committed = true
+  }
+
+  /**
+   * Check if the transaction has been committed.
+   */
+  isCommitted(): boolean {
+    return this.committed
+  }
+
+  /**
+   * Get the number of pending rollback actions.
+   */
+  getPendingCount(): number {
+    return this.rollbackStack.length
+  }
+}
+
+/**
+ * Helper function to execute an operation with automatic rollback on failure.
+ *
+ * Usage:
+ * ```typescript
+ * await withTransaction(async (tx) => {
+ *   await step1()
+ *   tx.addRollback({ description: 'Undo step1', execute: undoStep1 })
+ *
+ *   await step2()
+ *   tx.addRollback({ description: 'Undo step2', execute: undoStep2 })
+ *
+ *   // If we get here without throwing, transaction commits automatically
+ * })
+ * ```
+ */
+export async function withTransaction<T>(
+  operation: (tx: TransactionManager) => Promise<T>,
+): Promise<T> {
+  const tx = new TransactionManager()
+
+  try {
+    const result = await operation(tx)
+    tx.commit()
+    return result
+  } catch (err) {
+    await tx.rollback()
+    throw err
+  }
+}

package/engines/index.ts

@@ -1,4 +1,5 @@
 import { postgresqlEngine } from './postgresql'
+import { mysqlEngine } from './mysql'
 import type { BaseEngine } from './base-engine'
 import type { EngineInfo } from '../types'
 
@@ -6,9 +7,13 @@ import type { EngineInfo } from '../types'
  * Registry of available database engines
  */
 export const engines: Record<string, BaseEngine> = {
+  // PostgreSQL and aliases
   postgresql: postgresqlEngine,
-  postgres: postgresqlEngine, // Alias
-  pg: postgresqlEngine, // Alias
+  postgres: postgresqlEngine,
+  pg: postgresqlEngine,
+  // MySQL and aliases
+  mysql: mysqlEngine,
+  mariadb: mysqlEngine, // MariaDB is MySQL-compatible
 }
 
 /**