maqet 0.0.1.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

maqet/ipc/runner_client.py

@@ -0,0 +1,285 @@
+"""
+Runner Client
+
+Client for communicating with VM runner processes via Unix sockets.
+Used by CLI to send commands to running VM runner processes.
+
+Architecture:
+- Each VM has unique socket path
+- Client connects, sends request, receives response, disconnects
+- Synchronous and async interfaces
+- Error handling for connection issues
+"""
+
+import asyncio
+import json
+import os
+import socket
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..constants import Intervals, Retries, Timeouts
+from ..logger import LOG
+from .retry import async_retry_with_backoff, CircuitBreaker
+
+# Optional dependency - imported inline with fallback
+try:
+    import psutil
+
+    PSUTIL_AVAILABLE = True
+except ImportError:
+    PSUTIL_AVAILABLE = False
+
+
+class RunnerClientError(Exception):
+    """Runner client communication errors."""
+
+
+class RunnerClient:
+    """
+    Client for communicating with a VM runner process.
+
+    Used by CLI to send commands to running VM runners via Unix sockets.
+    Provides both synchronous and asynchronous interfaces.
+
+    Example:
+        client = RunnerClient("vm1", state_manager)
+        result = client.send_command("qmp", "query-status")
+    """
+
+    def __init__(self, vm_id: str, state_manager):
+        """
+        Initialize runner client.
+
+        Args:
+            vm_id: VM identifier
+            state_manager: StateManager instance for DB access
+        """
+        self.vm_id = vm_id
+        self.state_manager = state_manager
+        self.socket_path = self._get_socket_path()
+        self._circuit_breaker = CircuitBreaker(
+            failure_threshold=5, timeout=60.0
+        )
+
+        LOG.debug(f"RunnerClient initialized for {vm_id}")
+
+    def is_runner_running(self) -> bool:
+        """
+        Check if VM runner process is running.
+
+        Uses psutil if available for accurate check, otherwise
+        falls back to checking if socket exists.
+
+        Returns:
+            True if runner is running, False otherwise
+        """
+        # Get VM from database
+        vm = self.state_manager.get_vm(self.vm_id)
+        if not vm or not vm.runner_pid:
+            return False
+
+        # Check if process exists (if psutil available)
+        if PSUTIL_AVAILABLE:
+            return psutil.pid_exists(vm.runner_pid)
+        else:
+            # Fallback: check if socket exists
+            return self.socket_path.exists()
+
+    @async_retry_with_backoff(
+        max_attempts=Retries.IPC_MAX_RETRIES,
+        backoff_base=Intervals.IPC_BACKOFF_BASE,
+        exceptions=(ConnectionRefusedError, FileNotFoundError, OSError),
+    )
+    async def _connect_to_socket(self):
+        """
+        Connect to Unix socket with retry logic.
+
+        Internal method that handles connection with automatic retry
+        on transient failures.
+
+        Returns:
+            Tuple of (reader, writer) for socket communication
+
+        Raises:
+            ConnectionRefusedError: If connection refused
+            FileNotFoundError: If socket doesn't exist
+            OSError: On other connection errors
+        """
+        return await asyncio.wait_for(
+            asyncio.open_unix_connection(str(self.socket_path)),
+            timeout=Timeouts.IPC_CONNECT,
+        )
+
+    async def send_command_async(
+        self, method: str, *args, **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Send command to VM runner asynchronously.
+
+        Args:
+            method: Method name (e.g., "qmp", "stop", "status", "ping")
+            *args: Method arguments
+            **kwargs: Method keyword arguments
+
+        Returns:
+            Result dictionary from runner
+
+        Raises:
+            RunnerClientError: If runner not running or communication fails
+        """
+        # Check circuit breaker
+        if self._circuit_breaker.is_open():
+            raise RunnerClientError(
+                f"Circuit breaker open for {self.vm_id}. "
+                f"Too many consecutive failures. Try again later."
+            )
+
+        # Check runner running
+        if not self.is_runner_running():
+            raise RunnerClientError(
+                f"VM runner for {self.vm_id} is not running. "
+                f"Start VM first with: maqet start {self.vm_id}"
+            )
+
+        # Check socket exists
+        if not self.socket_path.exists():
+            raise RunnerClientError(
+                f"Socket not found: {self.socket_path}. "
+                f"VM runner may have crashed."
+            )
+
+        # Build request
+        request = {"method": method, "args": list(args), "kwargs": kwargs}
+
+        LOG.debug(f"Sending IPC request: method={method}")
+
+        try:
+            # Connect to Unix socket with retry logic
+            reader, writer = await self._connect_to_socket()
+
+            try:
+                # Send request
+                request_data = json.dumps(request).encode("utf-8")
+                writer.write(request_data)
+                await writer.drain()
+
+                # Receive response (up to 1MB)
+                response_data = await asyncio.wait_for(
+                    reader.read(1024 * 1024), timeout=Timeouts.IPC_COMMAND
+                )
+                if not response_data:
+                    raise RunnerClientError("Empty response from runner")
+
+                # Parse response
+                try:
+                    response = json.loads(response_data.decode("utf-8"))
+                except json.JSONDecodeError as e:
+                    raise RunnerClientError(f"Invalid JSON response: {e}")
+
+                # Check response status
+                if response.get("status") == "error":
+                    raise RunnerClientError(response.get("error", "Unknown error"))
+
+                LOG.debug(f"IPC response received: status={response.get('status')}")
+
+                # Record success for circuit breaker
+                self._circuit_breaker.record_success()
+
+                return response.get("result", {})
+
+            finally:
+                # Always close connection
+                try:
+                    writer.close()
+                    await writer.wait_closed()
+                except Exception as e:
+                    LOG.debug(f"Error closing connection: {e}")
+
+        except ConnectionRefusedError as e:
+            self._circuit_breaker.record_failure()
+            raise RunnerClientError(
+                f"Connection refused. VM runner for {self.vm_id} "
+                f"may have crashed or stopped. Error: {e}"
+            )
+        except FileNotFoundError as e:
+            self._circuit_breaker.record_failure()
+            raise RunnerClientError(
+                f"Socket not found: {self.socket_path}. "
+                f"VM runner may have exited. Error: {e}"
+            )
+        except asyncio.TimeoutError as e:
+            self._circuit_breaker.record_failure()
+            raise RunnerClientError(
+                f"IPC operation timed out for {self.vm_id}. "
+                f"Runner may be unresponsive. Error: {e}"
+            )
+        except OSError as e:
+            self._circuit_breaker.record_failure()
+            raise RunnerClientError(f"Communication error: {e}")
+        except RunnerClientError:
+            # Already a RunnerClientError, don't wrap again
+            self._circuit_breaker.record_failure()
+            raise
+        except Exception as e:
+            self._circuit_breaker.record_failure()
+            raise RunnerClientError(f"Unexpected error: {e}")
+
+    def send_command(self, method: str, *args, **kwargs) -> Dict[str, Any]:
+        """
+        Send command to VM runner synchronously.
+
+        Convenience wrapper around send_command_async() for synchronous usage.
+
+        Args:
+            method: Method name (e.g., "qmp", "stop", "status", "ping")
+            *args: Method arguments
+            **kwargs: Method keyword arguments
+
+        Returns:
+            Result dictionary from runner
+
+        Raises:
+            RunnerClientError: If runner not running or communication fails
+        """
+        return asyncio.run(self.send_command_async(method, *args, **kwargs))
+
+    def ping(self) -> bool:
+        """
+        Ping VM runner to check if it's responsive.
+
+        Returns:
+            True if runner responds to ping, False otherwise
+        """
+        try:
+            result = self.send_command("ping")
+            return result == "pong"
+        except RunnerClientError:
+            return False
+
+    def _get_socket_path(self) -> Path:
+        """
+        Get Unix socket path for this VM.
+
+        Socket location: XDG_RUNTIME_DIR/maqet/sockets/{vm_id}.sock
+        Falls back to /tmp/maqet-{uid}/sockets/ if XDG_RUNTIME_DIR not available.
+
+        Returns:
+            Path to Unix socket
+        """
+        # Get runtime directory (prefer XDG_RUNTIME_DIR)
+        runtime_dir_base = os.environ.get(
+            "XDG_RUNTIME_DIR", f"/run/user/{os.getuid()}"
+        )
+        if not Path(runtime_dir_base).exists():
+            # Fallback to /tmp
+            runtime_dir_base = f"/tmp/maqet-{os.getuid()}"
+
+        runtime_dir = Path(runtime_dir_base) / "maqet"
+        socket_dir = runtime_dir / "sockets"
+
+        return socket_dir / f"{self.vm_id}.sock"
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"RunnerClient(vm_id={self.vm_id}, socket={self.socket_path})"

maqet/ipc/unix_socket_server.py

@@ -0,0 +1,239 @@
+"""
+Unix Socket IPC Server
+
+Simple Unix domain socket server for IPC between CLI and VM runner.
+Uses JSON-RPC style protocol for request/response communication.
+
+Architecture:
+- Each VM runner process has its own Unix socket
+- Non-blocking async I/O using asyncio
+- Simple request/response pattern
+- Socket cleanup on server stop
+"""
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+from ..constants import Timeouts
+from ..logger import LOG
+
+
+class UnixSocketIPCServerError(Exception):
+    """Unix socket IPC server errors."""
+
+
+class UnixSocketIPCServer:
+    """
+    Unix domain socket server for IPC between CLI and VM runner.
+
+    Protocol: JSON-RPC style
+    - Client sends: {"method": "qmp", "args": [...], "kwargs": {...}}
+    - Server responds: {"status": "success", "result": ...} or
+                       {"status": "error", "error": "..."}
+
+    Socket lifecycle:
+    1. Server starts, binds to socket path
+    2. Accepts connections from CLI clients
+    3. Reads JSON request, calls handler
+    4. Writes JSON response
+    5. Closes connection
+    """
+
+    def __init__(
+        self, socket_path: Path, handler: Callable[[Dict[str, Any]], Dict[str, Any]]
+    ):
+        """
+        Initialize Unix socket server.
+
+        Args:
+            socket_path: Path to Unix socket file
+            handler: Async function to handle requests
+                     Takes request dict, returns response dict
+        """
+        self.socket_path = Path(socket_path)
+        self.handler = handler
+        self.server: Optional[asyncio.Server] = None
+        self._running = False
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+
+        LOG.debug(f"UnixSocketIPCServer initialized for {socket_path}")
+
+    async def start(self) -> None:
+        """
+        Start listening on Unix socket.
+
+        Process:
+        1. Remove existing socket if present (stale socket handling)
+        2. Create Unix socket server
+        3. Start accepting connections
+        4. Keep server running until stop() called
+
+        Raises:
+            UnixSocketIPCServerError: If socket already in use or bind fails
+        """
+        # Store event loop for cross-thread communication
+        self._loop = asyncio.get_running_loop()
+
+        # Remove existing socket if present
+        if self.socket_path.exists():
+            # Try to connect to check if someone is using it
+            try:
+                reader, writer = await asyncio.wait_for(
+                    asyncio.open_unix_connection(str(self.socket_path)),
+                    timeout=Timeouts.IPC_HEALTH_CHECK,
+                )
+                writer.close()
+                await writer.wait_closed()
+                # Someone is using it
+                raise UnixSocketIPCServerError(
+                    f"Socket already in use: {self.socket_path}"
+                )
+            except (ConnectionRefusedError, FileNotFoundError, asyncio.TimeoutError):
+                # Stale socket, remove it
+                LOG.debug(f"Removing stale socket {self.socket_path}")
+                self.socket_path.unlink()
+
+        # Create Unix socket server
+        try:
+            self.server = await asyncio.start_unix_server(
+                self._handle_client, path=str(self.socket_path)
+            )
+            self._running = True
+            LOG.info(f"IPC server listening on {self.socket_path}")
+
+            # Keep server running
+            async with self.server:
+                await self.server.serve_forever()
+
+        except asyncio.CancelledError:
+            # Server was stopped via stop() - this is normal
+            LOG.debug("IPC server cancelled (normal shutdown)")
+        except Exception as e:
+            raise UnixSocketIPCServerError(f"Failed to start IPC server: {e}")
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        """
+        Handle single client connection.
+
+        Process:
+        1. Read JSON request from client
+        2. Parse and validate request
+        3. Call handler function
+        4. Write JSON response to client
+        5. Close connection
+
+        Args:
+            reader: Async stream reader
+            writer: Async stream writer
+        """
+        try:
+            # Read request (up to 1MB)
+            data = await reader.read(1024 * 1024)
+            if not data:
+                return
+
+            # Parse JSON request
+            try:
+                request = json.loads(data.decode("utf-8"))
+            except json.JSONDecodeError as e:
+                response = {"status": "error", "error": f"Invalid JSON: {e}"}
+                writer.write(json.dumps(response).encode("utf-8"))
+                await writer.drain()
+                return
+
+            LOG.debug(f"IPC request: {request.get('method', 'unknown')}")
+
+            # Call handler
+            try:
+                response = await self.handler(request)
+            except Exception as e:
+                LOG.error(f"Handler error: {e}")
+                response = {"status": "error", "error": str(e)}
+
+            # Write response
+            response_data = json.dumps(response).encode("utf-8")
+            writer.write(response_data)
+            await writer.drain()
+
+            LOG.debug(f"IPC response: {response.get('status', 'unknown')}")
+
+        except Exception as e:
+            LOG.error(f"Error handling client: {e}")
+
+        finally:
+            # Close connection
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception as e:
+                LOG.debug(f"Error closing connection: {e}")
+
+    async def stop(self) -> None:
+        """
+        Stop server and cleanup socket (async version).
+
+        Process:
+        1. Close server (stop accepting connections)
+        2. Remove socket file
+
+        Note: This should be called from within the same event loop as start().
+        For cross-thread stopping, use stop_sync() instead.
+        """
+        LOG.debug("Stopping IPC server")
+        self._running = False
+
+        # Close server
+        if self.server:
+            self.server.close()
+            await self.server.wait_closed()
+
+        # Remove socket file
+        if self.socket_path.exists():
+            try:
+                self.socket_path.unlink()
+                LOG.debug(f"Removed socket {self.socket_path}")
+            except Exception as e:
+                LOG.warning(f"Failed to remove socket: {e}")
+
+    def stop_sync(self) -> None:
+        """
+        Stop server from another thread (synchronous).
+
+        This method is thread-safe and can be called from the main thread
+        to stop the IPC server running in a background thread.
+
+        Process:
+        1. Mark server as stopped
+        2. Close server socket (cancels serve_forever)
+        3. Remove socket file from filesystem
+        """
+        LOG.debug("Stopping IPC server (sync)")
+        self._running = False
+
+        # Close server socket from any thread
+        # This will cause serve_forever() to raise CancelledError
+        if self.server:
+            # Call server.close() in a thread-safe way
+            if self._loop and self._loop.is_running():
+                # Schedule close in the IPC server's event loop
+                self._loop.call_soon_threadsafe(self.server.close)
+            else:
+                # Event loop not running, close directly
+                self.server.close()
+
+        # Remove socket file (filesystem operation, thread-safe)
+        if self.socket_path.exists():
+            try:
+                self.socket_path.unlink()
+                LOG.debug(f"Removed socket {self.socket_path}")
+            except Exception as e:
+                LOG.warning(f"Failed to remove socket: {e}")
+
+    @property
+    def is_running(self) -> bool:
+        """Check if server is running."""
+        return self._running