claude-mpm 3.4.10__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/services/socketio/handlers/connection_handler.py

@@ -0,0 +1,333 @@
+"""
+Enhanced Connection Event Handler for Socket.IO.
+
+WHY: This module provides robust connection handling with state tracking,
+event replay on reconnection, and health monitoring integration.
+
+DESIGN DECISION: Centralized connection event handling ensures consistent
+state management and provides resilient event delivery across reconnections.
+"""
+
+from datetime import datetime, timezone
+
+from .base import BaseEventHandler
+
+
+class EnhancedConnectionEventHandler(BaseEventHandler):
+    """
+    Handles Socket.IO connection events with enhanced robustness.
+
+    Features:
+    - Persistent client tracking across reconnections
+    - Event replay on reconnection
+    - Connection health monitoring
+    - Acknowledgment system for guaranteed delivery
+    """
+
+    def register_events(self):
+        """Register enhanced connection event handlers."""
+        sio = self.server.core.sio
+
+        @sio.event
+        async def connect(sid, environ, auth):
+            """Handle client connection with enhanced tracking."""
+            try:
+                # Extract client ID from auth or create new
+                client_id = None
+                if auth and isinstance(auth, dict):
+                    client_id = auth.get("client_id")
+
+                # Register connection with manager
+                if self.server.connection_manager:
+                    conn = await self.server.connection_manager.register_connection(
+                        sid, client_id
+                    )
+
+                    # Add to server's connected clients
+                    self.server.connected_clients.add(sid)
+                    self.server.stats["connections_total"] += 1
+
+                    # Store client info
+                    self.server.client_info[sid] = {
+                        "client_id": conn.client_id,
+                        "connected_at": datetime.now(timezone.utc).isoformat(),
+                        "user_agent": environ.get("HTTP_USER_AGENT", "unknown"),
+                        "remote_addr": environ.get("REMOTE_ADDR", "unknown"),
+                    }
+
+                    # Send client ID back for future reconnections
+                    await sio.emit(
+                        "connection_established",
+                        {
+                            "client_id": conn.client_id,
+                            "sid": sid,
+                            "timestamp": datetime.now(timezone.utc).isoformat(),
+                            "server_version": self.get_server_version(),
+                        },
+                        room=sid,
+                    )
+
+                    # Send current server status
+                    await self._send_server_status(sid)
+
+                    # Check for events to replay
+                    last_sequence = 0
+                    if auth and isinstance(auth, dict):
+                        last_sequence = auth.get("last_sequence", 0)
+
+                    if last_sequence > 0:
+                        replay_events = (
+                            await self.server.connection_manager.get_replay_events(
+                                sid, last_sequence
+                            )
+                        )
+
+                        if replay_events:
+                            self.logger.info(
+                                f"Replaying {len(replay_events)} events for client {conn.client_id}"
+                            )
+
+                            # Send replay events in batch
+                            await sio.emit(
+                                "event_replay",
+                                {
+                                    "events": replay_events,
+                                    "count": len(replay_events),
+                                    "from_sequence": last_sequence,
+                                },
+                                room=sid,
+                            )
+
+                    # Send event history for initial population
+                    if (
+                        hasattr(self.server, "event_history")
+                        and self.server.event_history
+                    ):
+                        history_data = list(self.server.event_history)
+                        await sio.emit(
+                            "event_history",
+                            {"events": history_data, "count": len(history_data)},
+                            room=sid,
+                        )
+
+                    self.logger.info(
+                        f"Client connected: {conn.client_id} (sid: {sid}, "
+                        f"reconnect: {conn.metrics.reconnect_count > 0})"
+                    )
+                else:
+                    # Fallback to basic connection tracking
+                    self.server.connected_clients.add(sid)
+                    self.server.stats["connections_total"] += 1
+
+                    self.server.client_info[sid] = {
+                        "connected_at": datetime.now(timezone.utc).isoformat(),
+                        "user_agent": environ.get("HTTP_USER_AGENT", "unknown"),
+                        "remote_addr": environ.get("REMOTE_ADDR", "unknown"),
+                    }
+
+                    await self._send_server_status(sid)
+
+                    if (
+                        hasattr(self.server, "event_history")
+                        and self.server.event_history
+                    ):
+                        history_data = list(self.server.event_history)
+                        await sio.emit(
+                            "event_history",
+                            {"events": history_data, "count": len(history_data)},
+                            room=sid,
+                        )
+
+                    self.logger.info(f"Client connected: {sid}")
+
+            except Exception as e:
+                self.logger.error(f"Error handling connection for {sid}: {e}")
+
+        @sio.event
+        async def disconnect(sid):
+            """Handle client disconnection with state preservation."""
+            try:
+                # Get disconnection reason if available
+                reason = "client_disconnect"
+
+                # Unregister from connection manager but preserve state
+                if self.server.connection_manager:
+                    await self.server.connection_manager.unregister_connection(
+                        sid, reason
+                    )
+
+                # Remove from connected clients
+                if sid in self.server.connected_clients:
+                    self.server.connected_clients.remove(sid)
+
+                # Remove client info
+                if sid in self.server.client_info:
+                    client_info = self.server.client_info[sid]
+                    del self.server.client_info[sid]
+
+                    client_id = client_info.get("client_id", sid)
+                    self.logger.info(f"Client disconnected: {client_id} (sid: {sid})")
+                else:
+                    self.logger.info(f"Client disconnected: {sid}")
+
+            except Exception as e:
+                self.logger.error(f"Error handling disconnection for {sid}: {e}")
+
+        @sio.event
+        async def ping(sid):
+            """Handle ping from client for health monitoring."""
+            try:
+                # Update activity in connection manager - CRITICAL for preventing stale connections
+                if self.server.connection_manager:
+                    await self.server.connection_manager.update_activity(sid, "ping")
+
+                # Send pong response with timestamp
+                await sio.emit(
+                    "pong",
+                    {
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
+                        "server_time": datetime.now(timezone.utc).timestamp(),
+                    },
+                    room=sid,
+                )
+
+            except Exception as e:
+                self.logger.error(f"Error handling ping from {sid}: {e}")
+
+        @sio.event
+        async def acknowledge_event(sid, data):
+            """Handle event acknowledgment from client."""
+            try:
+                if not isinstance(data, dict):
+                    return
+
+                sequence = data.get("sequence")
+                if sequence and self.server.connection_manager:
+                    await self.server.connection_manager.acknowledge_event(
+                        sid, sequence
+                    )
+
+                    # Optional: Send confirmation
+                    await sio.emit(
+                        "ack_confirmed",
+                        {
+                            "sequence": sequence,
+                            "timestamp": datetime.now(timezone.utc).isoformat(),
+                        },
+                        room=sid,
+                    )
+
+            except Exception as e:
+                self.logger.error(f"Error handling acknowledgment from {sid}: {e}")
+
+        @sio.event
+        async def request_replay(sid, data):
+            """Handle replay request from client after reconnection."""
+            try:
+                if not isinstance(data, dict):
+                    return
+
+                last_sequence = data.get("last_sequence", 0)
+
+                if self.server.connection_manager:
+                    replay_events = (
+                        await self.server.connection_manager.get_replay_events(
+                            sid, last_sequence
+                        )
+                    )
+
+                    if replay_events:
+                        await sio.emit(
+                            "event_replay",
+                            {
+                                "events": replay_events,
+                                "count": len(replay_events),
+                                "from_sequence": last_sequence,
+                            },
+                            room=sid,
+                        )
+                    else:
+                        await sio.emit(
+                            "event_replay",
+                            {
+                                "events": [],
+                                "count": 0,
+                                "from_sequence": last_sequence,
+                                "message": "No events to replay",
+                            },
+                            room=sid,
+                        )
+
+            except Exception as e:
+                self.logger.error(f"Error handling replay request from {sid}: {e}")
+
+        @sio.event
+        async def get_connection_stats(sid):
+            """Get connection statistics for debugging."""
+            try:
+                stats = {
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                    "total_connections": len(self.server.connected_clients),
+                    "server_stats": self.server.stats,
+                }
+
+                if self.server.connection_manager:
+                    conn = self.server.connection_manager.get_connection(sid)
+                    if conn:
+                        stats["connection"] = {
+                            "client_id": conn.client_id,
+                            "state": conn.state.value,
+                            "connected_at": conn.connected_at,
+                            "quality": conn.calculate_quality(),
+                            "metrics": {
+                                "events_sent": conn.metrics.events_sent,
+                                "events_acked": conn.metrics.events_acked,
+                                "events_buffered": conn.metrics.events_buffered,
+                                "reconnect_count": conn.metrics.reconnect_count,
+                            },
+                        }
+
+                    stats["manager_metrics"] = (
+                        self.server.connection_manager.get_metrics()
+                    )
+
+                await sio.emit("connection_stats", stats, room=sid)
+
+            except Exception as e:
+                self.logger.error(f"Error getting connection stats for {sid}: {e}")
+
+        # Heartbeat handler removed - Using Socket.IO's built-in ping/pong instead
+        # This prevents conflicting heartbeat systems that can cause disconnections
+
+        self.logger.info("Enhanced connection event handlers registered")
+
+    async def _send_server_status(self, sid: str):
+        """Send current server status to a client."""
+        try:
+            status_data = {
+                "server_running": self.server.running,
+                "claude_status": self.server.claude_status,
+                "claude_pid": self.server.claude_pid,
+                "session_id": self.server.session_id,
+                "connected_clients": len(self.server.connected_clients),
+                "server_start_time": (
+                    self.server.stats.get("start_time").isoformat()
+                    if self.server.stats.get("start_time")
+                    else None
+                ),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+
+            await self.server.core.sio.emit("server_status", status_data, room=sid)
+
+        except Exception as e:
+            self.logger.error(f"Error sending server status to {sid}: {e}")
+
+    def get_server_version(self) -> str:
+        """Get server version for client info."""
+        try:
+            from claude_mpm.services.version_service import VersionService
+
+            return VersionService().get_version()
+        except Exception:
+            return "unknown"

claude_mpm/services/socketio/handlers/file.py

@@ -0,0 +1,263 @@
+"""File operation event handlers for Socket.IO.
+
+WHY: This module handles file-related events including reading file content
+safely with security checks. Separating file operations improves security
+auditing and makes it easier to add file-related features.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ....core.typing_utils import EventData
+from ....core.unified_paths import get_project_root
+from .base import BaseEventHandler
+
+
+class FileEventHandler(BaseEventHandler):
+    """Handles file operation Socket.IO events.
+
+    WHY: File operations require careful security considerations and
+    consistent error handling. Having a dedicated handler ensures
+    all file operations follow the same security patterns.
+    """
+
+    def register_events(self) -> None:
+        """Register file operation event handlers."""
+        self.logger.info(
+            "[FileEventHandler] Starting registration of read_file event handler"
+        )
+
+        # Capture self reference to avoid closure issues
+        handler_self = self
+
+        @self.sio.event
+        async def read_file(sid, data):
+            """Read file contents safely.
+
+            WHY: The dashboard needs to display file contents when users
+            click on files, but we must ensure secure file access with
+            proper validation and size limits.
+            """
+            handler_self.logger.info(
+                f"[FileEventHandler] Received read_file event from {sid} with data: {data}"
+            )
+            try:
+                file_path = data.get("file_path")
+                working_dir = data.get("working_dir", Path.cwd())
+                max_size = data.get("max_size", 1024 * 1024)  # 1MB default limit
+
+                if not file_path:
+                    handler_self.logger.warning(
+                        f"[FileEventHandler] Missing file_path in request from {sid}"
+                    )
+                    await handler_self.emit_to_client(
+                        sid,
+                        "file_content_response",
+                        {
+                            "success": False,
+                            "error": "file_path is required",
+                            "file_path": file_path,
+                        },
+                    )
+                    return
+
+                # Use the shared file reading logic
+                handler_self.logger.info(
+                    f"[FileEventHandler] Reading file: {file_path} from working_dir: {working_dir}"
+                )
+                result = await handler_self._read_file_safely(
+                    file_path, working_dir, max_size
+                )
+
+                # Send the result back to the client
+                handler_self.logger.info(
+                    f"[FileEventHandler] Sending file_content_response to {sid}, success: {result.get('success', False)}"
+                )
+                await handler_self.emit_to_client(sid, "file_content_response", result)
+                handler_self.logger.info(
+                    f"[FileEventHandler] Response sent successfully to {sid}"
+                )
+
+            except Exception as e:
+                handler_self.logger.error(
+                    f"[FileEventHandler] Exception in read_file handler: {e}",
+                    exc_info=True,
+                )
+                handler_self.log_error("read_file", e, data)
+                await handler_self.emit_to_client(
+                    sid,
+                    "file_content_response",
+                    {
+                        "success": False,
+                        "error": str(e),
+                        "file_path": data.get("file_path", "unknown"),
+                    },
+                )
+                handler_self.logger.info(
+                    f"[FileEventHandler] Error response sent to {sid}"
+                )
+
+        # Log successful registration
+        self.logger.info(
+            "[FileEventHandler] read_file event handler registered successfully"
+        )
+
+    async def _read_file_safely(
+        self,
+        file_path: str,
+        working_dir: Optional[str] = None,
+        max_size: int = 1024 * 1024,
+    ) -> EventData:
+        """Safely read file content with security checks.
+
+        WHY: File reading must be secure to prevent directory traversal attacks
+        and resource exhaustion. This method centralizes all security checks
+        and provides consistent error handling.
+
+        Args:
+            file_path: Path to the file to read
+            working_dir: Working directory (defaults to current directory)
+            max_size: Maximum file size in bytes
+
+        Returns:
+            dict: Response with success status, content, and metadata
+        """
+        try:
+            if working_dir is None:
+                working_dir = Path.cwd()
+
+            # Resolve absolute path based on working directory
+            file_path_obj = Path(file_path)
+            if not file_path_obj.is_absolute():
+                full_path = Path(working_dir) / file_path
+            else:
+                full_path = file_path_obj
+
+            # Security check: ensure file is within working directory or project
+            try:
+                real_path = full_path.resolve()
+                real_working_dir = Path(working_dir).resolve()
+
+                # Allow access to files within working directory or the project root
+                project_root = Path(get_project_root()).resolve()
+                allowed_paths = [real_working_dir, project_root]
+
+                is_allowed = any(
+                    str(real_path).startswith(str(allowed_path))
+                    for allowed_path in allowed_paths
+                )
+
+                if not is_allowed:
+                    return {
+                        "success": False,
+                        "error": "Access denied: file is outside allowed directories",
+                        "file_path": file_path,
+                    }
+
+            except Exception as path_error:
+                self.logger.error(f"Path validation error: {path_error}")
+                return {
+                    "success": False,
+                    "error": "Invalid file path",
+                    "file_path": file_path,
+                }
+
+            # Check if file exists
+            if not real_path.exists():
+                return {
+                    "success": False,
+                    "error": "File does not exist",
+                    "file_path": file_path,
+                }
+
+            # Check if it's a file (not directory)
+            if not real_path.is_file():
+                return {
+                    "success": False,
+                    "error": "Path is not a file",
+                    "file_path": file_path,
+                }
+
+            # Check file size
+            file_size = real_path.stat().st_size
+            if file_size > max_size:
+                return {
+                    "success": False,
+                    "error": f"File too large ({file_size} bytes). Maximum allowed: {max_size} bytes",
+                    "file_path": file_path,
+                    "file_size": file_size,
+                }
+
+            # Read file content
+            try:
+                with Path(real_path).open(
+                    encoding="utf-8",
+                ) as f:
+                    content = f.read()
+
+                # Get file extension for syntax highlighting hint
+                ext = real_path.suffix
+
+                return {
+                    "success": True,
+                    "file_path": file_path,
+                    "content": content,
+                    "file_size": file_size,
+                    "extension": ext.lower(),
+                    "encoding": "utf-8",
+                }
+
+            except UnicodeDecodeError:
+                # Try reading as binary if UTF-8 fails
+                return self._read_binary_file(real_path, file_path, file_size)
+
+        except Exception as e:
+            self.logger.error(f"Error in _read_file_safely: {e}")
+            return {"success": False, "error": str(e), "file_path": file_path}
+
+    def _read_binary_file(
+        self, real_path: str, file_path: str, file_size: int
+    ) -> Dict[str, Any]:
+        """Handle binary or non-UTF8 files.
+
+        WHY: Not all files are UTF-8 encoded. We need to handle other
+        encodings gracefully and detect binary files that shouldn't
+        be displayed as text.
+        """
+        try:
+            with real_path.open("rb") as f:
+                binary_content = f.read()
+
+            # Check if it's a text file by looking for common text patterns
+            try:
+                text_content = binary_content.decode("latin-1")
+                if "\x00" in text_content:
+                    # Binary file
+                    return {
+                        "success": False,
+                        "error": "File appears to be binary and cannot be displayed as text",
+                        "file_path": file_path,
+                        "file_size": file_size,
+                    }
+                # Text file with different encoding
+                ext = real_path.suffix
+                return {
+                    "success": True,
+                    "file_path": file_path,
+                    "content": text_content,
+                    "file_size": file_size,
+                    "extension": ext.lower(),
+                    "encoding": "latin-1",
+                }
+            except Exception:
+                return {
+                    "success": False,
+                    "error": "File encoding not supported",
+                    "file_path": file_path,
+                }
+        except Exception as read_error:
+            return {
+                "success": False,
+                "error": f"Failed to read file: {read_error!s}",
+                "file_path": file_path,
+            }