@dynamicu/chromedebug-mcp 2.2.0

package/src/services/session-manager.js

@@ -0,0 +1,497 @@
+/**
+ * SessionManager - Core session isolation for Chrome Debug
+ * 
+ * Provides UUID-based session management to prevent conflicts when multiple
+ * Claude Code sessions launch Chrome simultaneously.
+ * 
+ * Key Features:
+ * - UUID-based session identification
+ * - Isolated Chrome profile directories
+ * - Process tracking and cleanup
+ * - Heartbeat mechanism integration
+ * - Safe cleanup of only dead sessions
+ */
+
+import { randomUUID } from 'crypto';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { findAvailablePort, findAvailablePortWithLock, releasePortLock } from '../utils.js';
+import { ProjectManager } from './project-manager.js';
+
+export class SessionManager {
+  constructor(database = null) {
+    this.database = database;
+    this.sessionId = randomUUID();
+    this.sessionData = null;
+    this.heartbeatInterval = null;
+    
+    // Project management for path resolution
+    this.projectManager = new ProjectManager();
+    this._projectModeInitialized = false;
+    
+    // Session configuration
+    this.HEARTBEAT_INTERVAL = 30000; // 30 seconds
+    this.STALE_THRESHOLD = 5 * 60 * 1000; // 5 minutes
+    
+    // Add process cleanup handlers to ensure port locks are released
+    this.setupProcessCleanupHandlers();
+  }
+
+  /**
+   * Setup process cleanup handlers to ensure port locks are released on exit
+   */
+  setupProcessCleanupHandlers() {
+    // Handle graceful shutdown
+    const cleanupHandler = async () => {
+      if (this.sessionData && this.sessionData.portLockFile) {
+        try {
+          await releasePortLock(this.sessionData.portLockFile);
+          console.log(`[SessionManager] Released port lock on process exit for session ${this.sessionData.sessionId}`);
+        } catch (error) {
+          console.warn('[SessionManager] Error releasing port lock on exit:', error);
+        }
+      }
+    };
+
+    process.on('exit', cleanupHandler);
+    process.on('SIGINT', cleanupHandler);
+    process.on('SIGTERM', cleanupHandler);
+    process.on('uncaughtException', cleanupHandler);
+  }
+
+  /**
+   * Initializes project mode if available (called automatically when needed)
+   */
+  async initializeProjectMode() {
+    if (this._projectModeInitialized) {
+      return; // Already initialized
+    }
+
+    try {
+      const projectInfo = this.projectManager.detectProject();
+      if (projectInfo) {
+        await this.projectManager.initializeProjectStructure();
+        console.log(`[SessionManager] Using project-local storage: ${this.projectManager.getCurrentMode()}`);
+      } else {
+        console.log('[SessionManager] Using global storage mode');
+      }
+    } catch (error) {
+      console.warn('[SessionManager] Failed to initialize project mode, falling back to global:', error.message);
+    } finally {
+      this._projectModeInitialized = true;
+    }
+  }
+
+  /**
+   * Creates a new isolated session with UUID-based profile path
+   * @param {number} preferredPort - Preferred debug port (optional)
+   * @returns {Promise<SessionData>} Created session data
+   */
+  async createSession(preferredPort = null) {
+    // Ensure project mode is initialized
+    await this.initializeProjectMode();
+    
+    try {
+      // Generate session metadata
+      const sessionId = this.sessionId;
+      const startTime = new Date();
+      const lastHeartbeat = new Date();
+
+      // Find available debug port with atomic lock coordination to prevent race conditions
+      const pidOffset = process.pid % 100;
+      const sessionOffset = parseInt(sessionId.split('-')[0], 16) % 50; // Use UUID for randomization
+      const basePort = preferredPort || (9222 + pidOffset + sessionOffset);
+      const portLockResult = await findAvailablePortWithLock(basePort, basePort + 200, sessionId);
+      const debugPort = portLockResult.port;
+
+      // Create UUID-based profile path using project-local or global storage
+      const sessionPrefix = sessionId.split('-')[0]; // First part of UUID for brevity
+      const timestamp = Date.now();
+      
+      let profilePath;
+      if (this.projectManager.isProjectModeAvailable()) {
+        // Use project-local sessions directory
+        const sessionsDir = this.projectManager.getProjectSessionsDir();
+        profilePath = path.join(sessionsDir, `${sessionPrefix}-${timestamp}`, 'profile');
+      } else {
+        // Use global temp directory (existing behavior)
+        profilePath = path.join(
+          os.tmpdir(),
+          `chromedebug-${sessionPrefix}-${timestamp}`
+        );
+      }
+
+      // Create the profile directory
+      await fs.mkdir(profilePath, { recursive: true });
+
+      // Store session data
+      this.sessionData = {
+        sessionId,
+        processId: null, // Will be set when Chrome launches
+        startTime,
+        lastHeartbeat,
+        profilePath,
+        debugPort,
+        portLockFile: portLockResult.lockFile // Store lock file for cleanup
+      };
+
+      console.log(`[SessionManager] Created session ${sessionId} with profile: ${profilePath}`);
+      
+      // Start heartbeat automatically
+      this.startHeartbeat();
+
+      return { ...this.sessionData };
+    } catch (error) {
+      console.error('[SessionManager] Failed to create session:', error);
+      throw new Error(`Session creation failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Updates the heartbeat timestamp for this session
+   * @returns {Promise<void>}
+   */
+  async updateHeartbeat() {
+    if (this.sessionData) {
+      this.sessionData.lastHeartbeat = new Date();
+      console.log(`[SessionManager] Updated heartbeat for session ${this.sessionData.sessionId}`);
+    }
+  }
+
+  /**
+   * Starts automatic heartbeat updates for this session
+   */
+  startHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+    }
+
+    this.heartbeatInterval = setInterval(async () => {
+      await this.updateHeartbeat();
+    }, this.HEARTBEAT_INTERVAL);
+
+    console.log(`[SessionManager] Started heartbeat for session ${this.sessionId}`);
+  }
+
+  /**
+   * Stops heartbeat for this session
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+      console.log(`[SessionManager] Stopped heartbeat for session ${this.sessionId}`);
+    }
+  }
+
+  /**
+   * Checks if a process is still alive
+   * @param {number} pid - Process ID to check
+   * @returns {boolean} True if process is alive
+   */
+  isProcessAlive(pid) {
+    if (!pid) return false;
+    
+    try {
+      process.kill(pid, 0); // Signal 0 just checks if process exists
+      return true;
+    } catch (error) {
+      if (error.code === 'ESRCH') {
+        return false; // Process does not exist
+      }
+      // Other errors (like EPERM) mean process exists but we can't signal it
+      return true;
+    }
+  }
+
+  /**
+   * Checks if this session is alive (process + heartbeat)
+   * @param {string} sessionId - Session ID to check
+   * @returns {Promise<boolean>} True if session is alive
+   */
+  async isSessionAlive(sessionId = null) {
+    const targetSessionId = sessionId || this.sessionId;
+    
+    if (!this.sessionData || this.sessionData.sessionId !== targetSessionId) {
+      return false;
+    }
+
+    // Check process health
+    if (this.sessionData.processId && !this.isProcessAlive(this.sessionData.processId)) {
+      return false;
+    }
+
+    // Check heartbeat freshness
+    const now = new Date();
+    const timeSinceHeartbeat = now.getTime() - this.sessionData.lastHeartbeat.getTime();
+    
+    if (timeSinceHeartbeat > this.STALE_THRESHOLD) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Sets the Chrome process ID for this session
+   * @param {number} processId - Chrome process ID
+   */
+  setProcessId(processId) {
+    if (this.sessionData) {
+      this.sessionData.processId = processId;
+      console.log(`[SessionManager] Set process ID ${processId} for session ${this.sessionId}`);
+    }
+  }
+
+  /**
+   * Gets current session data
+   * @param {string} sessionId - Session ID to get data for
+   * @returns {Promise<SessionData|null>} Session data or null if not found
+   */
+  async getSessionData(sessionId = null) {
+    const targetSessionId = sessionId || this.sessionId;
+    
+    if (this.sessionData && this.sessionData.sessionId === targetSessionId) {
+      return { ...this.sessionData };
+    }
+    
+    return null;
+  }
+
+  /**
+   * Safely cleans up a directory if it's a Chrome Debug directory
+   * @param {string} dirPath - Directory path to clean up
+   * @param {boolean} isProjectLocal - Whether this is a project-local directory
+   * @returns {Promise<boolean>} True if cleaned successfully
+   */
+  async safeCleanupDirectory(dirPath, isProjectLocal = false) {
+    if (!dirPath || typeof dirPath !== 'string') {
+      return false;
+    }
+
+    try {
+      const resolvedPath = path.resolve(dirPath);
+      
+      // Security validation based on directory type
+      if (isProjectLocal) {
+        // Validate project-local directory is within project sessions directory
+        if (this.projectManager.isProjectModeAvailable()) {
+          const projectSessionsDir = path.resolve(this.projectManager.getProjectSessionsDir());
+          if (!resolvedPath.startsWith(projectSessionsDir)) {
+            console.warn(`[SessionManager] Refusing to clean unsafe project directory: ${dirPath}`);
+            return false;
+          }
+        } else {
+          console.warn(`[SessionManager] Cannot clean project directory when not in project mode: ${dirPath}`);
+          return false;
+        }
+      } else {
+        // Validate global directory is within temp and has chromedebug prefix
+        const tmpDir = os.tmpdir();
+        const resolvedTmpDir = path.resolve(tmpDir);
+        
+        if (!resolvedPath.startsWith(resolvedTmpDir) || 
+            !path.basename(resolvedPath).startsWith('chromedebug-')) {
+          console.warn(`[SessionManager] Refusing to clean unsafe global directory: ${dirPath}`);
+          return false;
+        }
+      }
+
+      await fs.rm(resolvedPath, { recursive: true, force: true });
+      console.log(`[SessionManager] Cleaned up ${isProjectLocal ? 'project-local' : 'global'} directory: ${resolvedPath}`);
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return true; // Directory doesn't exist, consider it cleaned
+      }
+      console.error(`[SessionManager] Failed to cleanup directory ${dirPath}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Cleans up stale Chrome Debug sessions
+   * Only cleans sessions with dead processes AND stale heartbeats
+   * @returns {Promise<CleanupResult>} Cleanup results
+   */
+  async cleanupStaleSessions() {
+    const cleanupResult = {
+      cleanedSessions: [],
+      failedCleanups: [],
+      activeSessionsRemaining: 0
+    };
+
+    try {
+      const dirsToCheck = [];
+      
+      // Check project-local sessions if available
+      if (this.projectManager.isProjectModeAvailable()) {
+        try {
+          const projectSessionsDir = this.projectManager.getProjectSessionsDir();
+          const projectEntries = await fs.readdir(projectSessionsDir);
+          dirsToCheck.push(...projectEntries.map(entry => ({
+            name: entry,
+            fullPath: path.join(projectSessionsDir, entry),
+            isProjectLocal: true
+          })));
+        } catch (error) {
+          console.warn('[SessionManager] Could not read project sessions directory:', error.message);
+        }
+      }
+      
+      // Also check global temp directory for compatibility
+      const tmpDir = os.tmpdir();
+      const tmpEntries = await fs.readdir(tmpDir);
+      const chromePilotDirs = tmpEntries.filter(entry => entry.startsWith('chromedebug-'));
+      dirsToCheck.push(...chromePilotDirs.map(entry => ({
+        name: entry,
+        fullPath: path.join(tmpDir, entry),
+        isProjectLocal: false
+      })));
+
+      console.log(`[SessionManager] Found ${dirsToCheck.length} directories to evaluate`);
+
+      for (const dirInfo of dirsToCheck) {
+        try {
+          const dirPath = dirInfo.fullPath;
+          const dirName = dirInfo.name;
+          
+          // Skip our own active session
+          if (this.sessionData && 
+              (dirPath === this.sessionData.profilePath || 
+               dirPath === path.dirname(this.sessionData.profilePath))) {
+            const isAlive = await this.isSessionAlive();
+            if (isAlive) {
+              cleanupResult.activeSessionsRemaining++;
+              continue;
+            }
+          }
+
+          // Try to extract session info from directory name
+          const parts = dirName.split('-');
+          let timestamp = null;
+          
+          if (dirInfo.isProjectLocal) {
+            // Project-local format: {sessionPrefix}-{timestamp}
+            if (parts.length >= 2) {
+              timestamp = parseInt(parts[parts.length - 1], 10);
+            }
+          } else {
+            // Global format: chromedebug-{sessionPrefix}-{timestamp}
+            if (parts.length >= 3) {
+              timestamp = parseInt(parts[parts.length - 1], 10);
+            }
+          }
+          
+          if (!isNaN(timestamp)) {
+            const age = Date.now() - timestamp;
+            if (age > this.STALE_THRESHOLD) {
+              const cleaned = await this.safeCleanupDirectory(dirPath, dirInfo.isProjectLocal);
+              if (cleaned) {
+                cleanupResult.cleanedSessions.push(dirName);
+              } else {
+                cleanupResult.failedCleanups.push({ sessionId: dirName, reason: 'Cleanup failed' });
+              }
+            } else {
+              cleanupResult.activeSessionsRemaining++;
+            }
+          }
+        } catch (error) {
+          console.error(`[SessionManager] Error evaluating directory ${dirInfo.name}:`, error);
+          cleanupResult.failedCleanups.push({ sessionId: dirInfo.name, reason: error.message });
+        }
+      }
+
+      console.log(`[SessionManager] Cleanup complete: ${cleanupResult.cleanedSessions.length} cleaned, ${cleanupResult.activeSessionsRemaining} active remaining`);
+    } catch (error) {
+      console.error('[SessionManager] Error during stale session cleanup:', error);
+      throw error;
+    }
+
+    return cleanupResult;
+  }
+
+  /**
+   * Forces cleanup of a specific session (for error recovery)
+   * @param {string} sessionId - Session ID to clean up
+   * @returns {Promise<boolean>} True if cleaned successfully
+   */
+  async forceCleanupSession(sessionId) {
+    if (!sessionId || typeof sessionId !== 'string') {
+      throw new Error('Invalid session ID provided for cleanup');
+    }
+
+    try {
+      // If it's our own session, clean it up directly
+      if (this.sessionData && this.sessionData.sessionId === sessionId) {
+        this.stopHeartbeat();
+        
+        if (this.sessionData.processId) {
+          try {
+            process.kill(this.sessionData.processId, 'SIGTERM');
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            
+            // Force kill if still alive
+            if (this.isProcessAlive(this.sessionData.processId)) {
+              process.kill(this.sessionData.processId, 'SIGKILL');
+            }
+          } catch (error) {
+            console.warn(`[SessionManager] Error killing process ${this.sessionData.processId}:`, error);
+          }
+        }
+
+        const cleaned = await this.safeCleanupDirectory(this.sessionData.profilePath);
+        
+        // Release port lock
+        if (this.sessionData.portLockFile) {
+          try {
+            await releasePortLock(this.sessionData.portLockFile);
+            console.log(`[SessionManager] Released port lock for session ${sessionId}`);
+          } catch (error) {
+            console.warn(`[SessionManager] Error releasing port lock for session ${sessionId}:`, error);
+          }
+        }
+        
+        // Reset session data
+        this.sessionData = null;
+        
+        return cleaned;
+      } else {
+        throw new Error(`Cannot force cleanup session ${sessionId}: session not found or not owned by this manager`);
+      }
+    } catch (error) {
+      console.error(`[SessionManager] Error in force cleanup of session ${sessionId}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets current storage mode information
+   * @returns {object} Storage mode info
+   */
+  getStorageInfo() {
+    return {
+      mode: this.projectManager.getCurrentMode(),
+      projectInfo: this.projectManager.projectInfo,
+      isProjectModeAvailable: this.projectManager.isProjectModeAvailable(),
+      projectStructure: this.projectManager.isProjectModeAvailable() 
+        ? this.projectManager.getProjectStructure() 
+        : null,
+      globalStructure: this.projectManager.getGlobalStructure()
+    };
+  }
+
+  /**
+   * Cleanup method called when SessionManager is destroyed
+   */
+  async cleanup() {
+    console.log(`[SessionManager] Cleaning up session manager for ${this.sessionId}`);
+    
+    this.stopHeartbeat();
+    
+    if (this.sessionData) {
+      await this.forceCleanupSession(this.sessionData.sessionId);
+    }
+  }
+}