@dynamicu/chromedebug-mcp 2.2.0

package/src/services/unified-session-manager.js

@@ -0,0 +1,678 @@
+/**
+ * Unified Session Manager - Single source of truth for Chrome Debug MCP sessions
+ * Consolidates process tracking, port discovery, and resource management
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import net from 'net';
+
+/**
+ * Unified Session Manager - handles all session-related resources atomically
+ */
+export class UnifiedSessionManager {
+  constructor(options = {}) {
+    this.sessionId = options.sessionId || this.generateSessionId();
+    this.skipCleanup = options.skipCleanup || false;
+    this.verbose = options.verbose || false;
+
+    // Session file paths
+    this.sessionDir = path.join(os.tmpdir(), 'chromedebug-sessions');
+    this.sessionFile = path.join(this.sessionDir, `${this.sessionId}.json`);
+    this.lockFile = null;
+
+    // Session state
+    this.state = {
+      sessionId: this.sessionId,
+      pid: process.pid,
+      startTime: Date.now(),
+      port: null,
+      processes: [],
+      locks: [],
+      heartbeat: Date.now()
+    };
+
+    this.heartbeatInterval = null;
+    this.initialized = false;
+    this.cleanupHandlersRegistered = false;
+    this.eventHandlers = new Map(); // Track event handlers for cleanup
+  }
+
+  /**
+   * Generate cryptographically secure session ID
+   */
+  generateSessionId() {
+    return 'session_' + crypto.randomBytes(16).toString('hex');
+  }
+
+  /**
+   * Initialize session with atomic operations
+   */
+  async initialize() {
+    if (this.initialized) return this.state;
+
+    try {
+      // Ensure session directory exists
+      await this.ensureSessionDirectory();
+
+      // Clean up stale sessions first (if not skipping cleanup)
+      if (!this.skipCleanup) {
+        await this.cleanupStaleSessions();
+      }
+
+      // Atomically create session file
+      await this.createSessionFile();
+
+      // Find and allocate port
+      const port = await this.allocatePort();
+      this.state.port = port;
+
+      // Update session file with port
+      await this.updateSessionFile();
+
+      // Start heartbeat
+      this.startHeartbeat();
+
+      // Setup cleanup handlers
+      this.setupCleanupHandlers();
+
+      this.initialized = true;
+
+      if (this.verbose) {
+        console.log(`Session initialized: ${this.sessionId}`);
+        console.log(`  PID: ${this.state.pid}`);
+        console.log(`  Port: ${this.state.port}`);
+        console.log(`  Session file: ${this.sessionFile}`);
+      }
+
+      return this.state;
+    } catch (error) {
+      await this.cleanup();
+      throw new Error(`Failed to initialize session: ${error.message}`);
+    }
+  }
+
+  /**
+   * Ensure session directory exists with proper permissions
+   */
+  async ensureSessionDirectory() {
+    try {
+      await fs.promises.mkdir(this.sessionDir, {
+        recursive: true,
+        mode: 0o700 // Only owner can read/write
+      });
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Atomically create session file
+   */
+  async createSessionFile() {
+    try {
+      const sessionData = JSON.stringify(this.state, null, 2);
+
+      // Atomic write - fails if file exists
+      await fs.promises.writeFile(this.sessionFile, sessionData, {
+        flag: 'wx',
+        mode: 0o600 // Only owner can read/write
+      });
+
+    } catch (error) {
+      if (error.code === 'EEXIST') {
+        throw new Error(`Session ${this.sessionId} already exists`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Update session file atomically
+   */
+  async updateSessionFile() {
+    this.state.heartbeat = Date.now();
+
+    const tempFile = `${this.sessionFile}.tmp`;
+    const sessionData = JSON.stringify(this.state, null, 2);
+
+    try {
+      // Defensive check: verify session file exists before updating
+      await fs.promises.access(this.sessionFile);
+
+      // Write to temp file first
+      await fs.promises.writeFile(tempFile, sessionData, { mode: 0o600 });
+
+      // Atomic rename
+      await fs.promises.rename(tempFile, this.sessionFile);
+    } catch (error) {
+      // Clean up temp file if it exists
+      try {
+        await fs.promises.unlink(tempFile);
+      } catch {}
+
+      // Handle specific error cases
+      if (error.code === 'ENOENT') {
+        throw new Error(`Session file does not exist: ${this.sessionFile}`);
+      } else if (error.code === 'EPERM' || error.code === 'EACCES') {
+        throw new Error(`Permission denied accessing session file: ${this.sessionFile}`);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Allocate an available port with atomic check-and-lock to prevent race conditions
+   */
+  async allocatePort() {
+    const preferredPorts = [
+      // Original range (maintain backward compatibility)
+      3000, 3001, 3002, 3028, 3029, 3030, 3031, 3032, 3033, 3034, 3035, 3036,
+      // Safer fallback ranges (avoid common service conflicts)
+      8080, 8081, 8082, 8083, 8084, 8085, 8086, 8087, 8088, 8089, 8090,
+      9000, 9001, 9002, 9003, 9004, 9005, 9006, 9007, 9008, 9009, 9010
+    ];
+
+    for (const port of preferredPorts) {
+      // ATOMIC: Check availability AND lock in single operation to prevent race conditions
+      const lockResult = await this.atomicPortCheckAndLock(port);
+      if (lockResult.success) {
+        this.lockFile = lockResult.lockFile;
+        return port;
+      }
+    }
+
+    throw new Error('No available ports found');
+  }
+
+  /**
+   * Check if port is available
+   */
+  async isPortAvailable(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+
+      server.once('error', () => resolve(false));
+      server.once('listening', () => {
+        server.close();
+        resolve(true);
+      });
+
+      server.listen(port);
+    });
+  }
+
+  /**
+   * Try to atomically lock a port
+   */
+  async tryLockPort(port) {
+    const lockDir = path.join(this.sessionDir, 'port-locks');
+    const lockFile = path.join(lockDir, `port-${port}.lock`);
+
+    try {
+      await fs.promises.mkdir(lockDir, { recursive: true, mode: 0o700 });
+
+      const lockData = {
+        sessionId: this.sessionId,
+        port,
+        pid: process.pid,
+        timestamp: Date.now()
+      };
+
+      // Atomic lock creation
+      await fs.promises.writeFile(lockFile, JSON.stringify(lockData), {
+        flag: 'wx',
+        mode: 0o600
+      });
+
+      return { success: true, lockFile };
+    } catch (error) {
+      if (error.code === 'EEXIST') {
+        // Check if lock is stale
+        return await this.handleStaleLock(lockFile, port);
+      }
+      return { success: false };
+    }
+  }
+
+  /**
+   * Handle potentially stale port locks
+   */
+  async handleStaleLock(lockFile, port) {
+    try {
+      const lockData = JSON.parse(await fs.promises.readFile(lockFile, 'utf8'));
+      const lockAge = Date.now() - lockData.timestamp;
+
+      // 30 second timeout for locks
+      if (lockAge > 30000) {
+        await fs.promises.unlink(lockFile);
+        return await this.tryLockPort(port);
+      }
+
+      return { success: false };
+    } catch (error) {
+      // Corrupted lock file, try to remove and retry
+      try {
+        await fs.promises.unlink(lockFile);
+        return await this.tryLockPort(port);
+      } catch {
+        return { success: false };
+      }
+    }
+  }
+
+  /**
+   * Atomically check port availability and acquire lock to prevent race conditions
+   * This combines the port availability check with lock acquisition in one operation
+   */
+  async atomicPortCheckAndLock(port) {
+    const lockDir = path.join(this.sessionDir, 'port-locks');
+    const lockFile = path.join(lockDir, `port-${port}.lock`);
+
+    try {
+      // Ensure lock directory exists
+      await fs.promises.mkdir(lockDir, { recursive: true, mode: 0o700 });
+
+      // First, attempt to acquire the lock atomically
+      // If this fails, the port is already locked by another session
+      const lockData = {
+        sessionId: this.sessionId,
+        port,
+        pid: process.pid,
+        timestamp: Date.now()
+      };
+
+      try {
+        // Atomic lock creation - will fail if file already exists
+        await fs.promises.writeFile(lockFile, JSON.stringify(lockData), {
+          flag: 'wx', // Create file, fail if exists (atomic)
+          mode: 0o600
+        });
+      } catch (error) {
+        if (error.code === 'EEXIST') {
+          // Lock already exists, check if it's stale
+          return await this.handleStaleLock(lockFile, port);
+        }
+        return { success: false, error: error.message };
+      }
+
+      // Lock acquired, now verify port is actually available
+      const isAvailable = await this.isPortAvailable(port);
+
+      if (!isAvailable) {
+        // Port is locked by us but not actually available, release lock
+        try {
+          await fs.promises.unlink(lockFile);
+        } catch {}
+        return { success: false, error: 'Port not available despite successful lock' };
+      }
+
+      // Success: port is available and locked by us
+      return { success: true, lockFile };
+
+    } catch (error) {
+      // Clean up any partial state
+      try {
+        await fs.promises.unlink(lockFile);
+      } catch {}
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Register a process for tracking
+   */
+  async registerProcess(pid, type = 'unknown') {
+    const processInfo = {
+      pid,
+      type,
+      startTime: Date.now()
+    };
+
+    this.state.processes.push(processInfo);
+    await this.updateSessionFile();
+
+    if (this.verbose) {
+      console.log(`Registered process: PID ${pid} (${type}) [Session: ${this.sessionId}]`);
+    }
+  }
+
+  /**
+   * Unregister a process
+   */
+  async unregisterProcess(pid) {
+    this.state.processes = this.state.processes.filter(p => p.pid !== pid);
+    await this.updateSessionFile();
+
+    if (this.verbose) {
+      console.log(`Unregistered process: PID ${pid} [Session: ${this.sessionId}]`);
+    }
+  }
+
+  /**
+   * Start heartbeat to keep session alive
+   */
+  startHeartbeat() {
+    this.heartbeatInterval = setInterval(async () => {
+      try {
+        await this.updateSessionFile();
+      } catch (error) {
+        // Handle specific error cases that indicate session cleanup
+        if (error.code === 'ENOENT' || error.message.includes('Session file does not exist')) {
+          if (this.verbose) {
+            console.log(`Session file removed, stopping heartbeat for session ${this.sessionId}`);
+          }
+          this.stopHeartbeat();
+          return;
+        }
+
+        // Handle permission errors gracefully
+        if (error.code === 'EPERM' || error.code === 'EACCES' || error.message.includes('Permission denied')) {
+          console.warn(`Heartbeat permission error for session ${this.sessionId}:`, error.message);
+          this.stopHeartbeat();
+          return;
+        }
+
+        // Log other errors but don't stop heartbeat
+        console.error(`Heartbeat failed for session ${this.sessionId}:`, error.message);
+      }
+    }, 10000); // 10 second heartbeat
+  }
+
+  /**
+   * Stop heartbeat timer and update state
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+
+      // Update state consistency when heartbeat stops
+      this.initialized = false;
+
+      if (this.verbose) {
+        console.log(`Heartbeat stopped for session ${this.sessionId}`);
+      }
+    }
+  }
+
+  /**
+   * Get session information
+   */
+  getSessionInfo() {
+    return {
+      ...this.state,
+      sessionFile: this.sessionFile,
+      lockFile: this.lockFile,
+      initialized: this.initialized
+    };
+  }
+
+  /**
+   * Find all active sessions
+   */
+  static async findActiveSessions() {
+    const sessionDir = path.join(os.tmpdir(), 'chromedebug-sessions');
+    const sessions = [];
+
+    try {
+      const files = await fs.promises.readdir(sessionDir);
+      const sessionFiles = files.filter(f => f.endsWith('.json') && f.startsWith('session_'));
+
+      for (const file of sessionFiles) {
+        try {
+          const sessionData = JSON.parse(
+            await fs.promises.readFile(path.join(sessionDir, file), 'utf8')
+          );
+
+          // Check if session is still alive (heartbeat within 30 seconds)
+          const heartbeatAge = Date.now() - sessionData.heartbeat;
+          if (heartbeatAge < 30000) {
+            sessions.push(sessionData);
+          }
+        } catch (error) {
+          // Skip corrupted session files
+        }
+      }
+    } catch (error) {
+      // Directory might not exist
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Clean up stale sessions
+   */
+  async cleanupStaleSessions() {
+    const sessionDir = path.join(os.tmpdir(), 'chromedebug-sessions');
+
+    try {
+      const files = await fs.promises.readdir(sessionDir);
+      let cleanedCount = 0;
+
+      for (const file of files) {
+        if (!file.endsWith('.json') || !file.startsWith('session_')) continue;
+
+        const sessionFile = path.join(sessionDir, file);
+
+        try {
+          const sessionData = JSON.parse(await fs.promises.readFile(sessionFile, 'utf8'));
+          const heartbeatAge = Date.now() - sessionData.heartbeat;
+
+          // Clean up sessions with heartbeat older than 1 minute
+          if (heartbeatAge > 60000) {
+            await fs.promises.unlink(sessionFile);
+            cleanedCount++;
+
+            if (this.verbose) {
+              console.log(`Cleaned up stale session: ${sessionData.sessionId}`);
+            }
+          }
+        } catch (error) {
+          // Remove corrupted session files
+          try {
+            await fs.promises.unlink(sessionFile);
+            cleanedCount++;
+          } catch {}
+        }
+      }
+
+      // Also clean up stale port locks
+      await this.cleanupStalePortLocks();
+
+      if (cleanedCount > 0 && this.verbose) {
+        console.log(`Cleaned up ${cleanedCount} stale sessions`);
+      }
+    } catch (error) {
+      // Directory might not exist
+    }
+  }
+
+  /**
+   * Clean up stale port locks
+   */
+  async cleanupStalePortLocks() {
+    const lockDir = path.join(this.sessionDir, 'port-locks');
+
+    try {
+      const files = await fs.promises.readdir(lockDir);
+
+      for (const file of files) {
+        if (!file.startsWith('port-') || !file.endsWith('.lock')) continue;
+
+        const lockFile = path.join(lockDir, file);
+
+        try {
+          const lockData = JSON.parse(await fs.promises.readFile(lockFile, 'utf8'));
+          const lockAge = Date.now() - lockData.timestamp;
+
+          // Clean up locks older than 30 seconds
+          if (lockAge > 30000) {
+            await fs.promises.unlink(lockFile);
+          }
+        } catch (error) {
+          // Remove corrupted lock files
+          try {
+            await fs.promises.unlink(lockFile);
+          } catch {}
+        }
+      }
+    } catch (error) {
+      // Directory might not exist
+    }
+  }
+
+  /**
+   * Setup cleanup handlers for graceful shutdown (prevents memory leaks)
+   */
+  setupCleanupHandlers() {
+    // Prevent duplicate event handlers
+    if (this.cleanupHandlersRegistered) {
+      return;
+    }
+
+    const cleanup = async (reason) => {
+      if (this.verbose) {
+        console.log(`Session ${this.sessionId} exiting (${reason}), cleaning up...`);
+      }
+      await this.cleanup();
+    };
+
+    // Create bound handlers and store them for removal
+    const exitHandler = () => cleanup('exit');
+    const sigintHandler = async () => {
+      await cleanup('SIGINT');
+      process.exit(0);
+    };
+    const sigtermHandler = async () => {
+      await cleanup('SIGTERM');
+      process.exit(0);
+    };
+    const uncaughtExceptionHandler = async (error) => {
+      console.error('Uncaught exception:', error);
+      await cleanup('uncaughtException');
+      process.exit(1);
+    };
+
+    // Store handlers for cleanup
+    this.eventHandlers.set('exit', exitHandler);
+    this.eventHandlers.set('SIGINT', sigintHandler);
+    this.eventHandlers.set('SIGTERM', sigtermHandler);
+    this.eventHandlers.set('uncaughtException', uncaughtExceptionHandler);
+
+    // Register event handlers
+    process.on('exit', exitHandler);
+    process.on('SIGINT', sigintHandler);
+    process.on('SIGTERM', sigtermHandler);
+    process.on('uncaughtException', uncaughtExceptionHandler);
+
+    this.cleanupHandlersRegistered = true;
+  }
+
+  /**
+   * Remove event handlers to prevent memory leaks
+   */
+  removeCleanupHandlers() {
+    if (!this.cleanupHandlersRegistered) {
+      return;
+    }
+
+    // Remove all registered event handlers
+    for (const [event, handler] of this.eventHandlers) {
+      process.removeListener(event, handler);
+    }
+
+    // Clear the handlers map
+    this.eventHandlers.clear();
+    this.cleanupHandlersRegistered = false;
+  }
+
+  /**
+   * Clean up all session resources
+   */
+  async cleanup() {
+    try {
+      // Remove event handlers to prevent memory leaks
+      this.removeCleanupHandlers();
+
+      // Stop heartbeat
+      this.stopHeartbeat();
+
+      // Release port lock
+      if (this.lockFile) {
+        try {
+          await fs.promises.unlink(this.lockFile);
+        } catch {}
+      }
+
+      // Remove session file
+      try {
+        await fs.promises.unlink(this.sessionFile);
+      } catch {}
+
+      if (this.verbose) {
+        console.log(`Session ${this.sessionId} cleaned up`);
+      }
+    } catch (error) {
+      console.error(`Error during session cleanup:`, error.message);
+    }
+  }
+}
+
+// Global session manager instance
+let globalSessionManager = null;
+
+/**
+ * Get or create the global session manager
+ */
+export function getSessionManager(options = {}) {
+  if (!globalSessionManager) {
+    globalSessionManager = new UnifiedSessionManager(options);
+  }
+  return globalSessionManager;
+}
+
+/**
+ * Initialize session management with options
+ */
+export async function initializeSessionManager(options = {}) {
+  const sessionManager = getSessionManager(options);
+  await sessionManager.initialize();
+  return sessionManager;
+}
+
+/**
+ * Get current session information
+ */
+export function getSessionInfo() {
+  return globalSessionManager ? globalSessionManager.getSessionInfo() : null;
+}
+
+/**
+ * Register a process for tracking
+ */
+export async function registerProcess(pid, type = 'unknown') {
+  if (globalSessionManager) {
+    await globalSessionManager.registerProcess(pid, type);
+  }
+}
+
+/**
+ * Unregister a process
+ */
+export async function unregisterProcess(pid) {
+  if (globalSessionManager) {
+    await globalSessionManager.unregisterProcess(pid);
+  }
+}
+
+/**
+ * Find all active sessions
+ */
+export const findActiveSessions = UnifiedSessionManager.findActiveSessions;