hysn-firecracker-python 1.0.3.post0__py3-none-any.whl

firecracker/process.py

@@ -0,0 +1,438 @@
+import os
+import time
+import psutil
+import subprocess
+from datetime import datetime
+from firecracker.logger import Logger
+from firecracker.config import MicroVMConfig
+from firecracker.exceptions import ProcessError
+from tenacity import (
+    retry,
+    stop_after_delay,
+    wait_fixed,
+    retry_if_exception_type,
+    stop_after_attempt,
+)
+
+
+class ProcessManager:
+    """Manages process-related operations for Firecracker microVMs."""
+
+    def __init__(self, verbose: bool = False, level: str = "INFO"):
+        self._logger = Logger(level=level, verbose=verbose)
+        self._config = MicroVMConfig()
+        self._config.verbose = verbose
+
+    def start(self, id: str, args: list) -> int:
+        """Start a Firecracker process.
+
+        Args:
+            id (str): The ID of the Firecracker VM
+            args (list): List of command arguments
+
+        Returns:
+            int: Process ID if successful
+
+        Raises:
+            ProcessError: If process fails to start or becomes defunct
+        """
+        try:
+            cmd = [self._config.binary_path] + args
+
+            log_path = f"{self._config.data_path}/{id}/firecracker.log"
+            pid_path = f"{self._config.data_path}/{id}/firecracker.pid"
+
+            # Get parent's process group
+            parent_pgid = os.getpgid(0)
+
+            process = subprocess.Popen(
+                cmd,
+                stdout=open(log_path, "w"),
+                stderr=subprocess.DEVNULL,
+                stdin=subprocess.DEVNULL,
+                # Explicitly set to parent's group
+                preexec_fn=lambda: os.setpgid(0, parent_pgid),
+            )
+
+            time.sleep(0.5)
+
+            if process.poll() is not None:
+                raise ProcessError("Firecracker process exited during startup")
+
+            proc = psutil.Process(process.pid)
+            if proc.status() == psutil.STATUS_ZOMBIE:
+                raise ProcessError("Firecracker process became defunct")
+
+            try:
+                proc.wait(timeout=1)
+            except psutil.TimeoutExpired:
+                pass
+            except psutil.NoSuchProcess:
+                raise ProcessError("Firecracker process disappeared during startup")
+
+            with open(pid_path, "w") as f:
+                f.write(str(process.pid))
+
+            if self._logger.verbose:
+                self._logger.debug(
+                    f"Firecracker process started with PID: {process.pid}"
+                )
+
+            return process.pid
+
+        except Exception as e:
+            raise ProcessError(f"Failed to start Firecracker: {str(e)}")
+
+    @retry(
+        stop=stop_after_delay(3),
+        wait=wait_fixed(0.5),
+        retry=retry_if_exception_type(ProcessError),
+    )
+    def is_running(self, id: str) -> bool:
+        """Check if Firecracker is running."""
+        try:
+            if os.path.exists(f"{self._config.data_path}/{id}/firecracker.pid"):
+                with open(f"{self._config.data_path}/{id}/firecracker.pid", "r") as f:
+                    pid = int(f.read().strip())
+
+                try:
+                    os.kill(pid, 0)
+                    if self._logger.verbose:
+                        self._logger.debug(f"Firecracker is running with PID: {pid}")
+                    return True
+                except OSError:
+                    if self._logger.verbose:
+                        self._logger.info("Firecracker is not running (stale PID file)")
+                    os.remove(f"{self._config.data_path}/{id}/firecracker.pid")
+                    return False
+            else:
+                if self._logger.verbose:
+                    self._logger.info("Firecracker is not running")
+                return False
+
+        except Exception as e:
+            if self._logger.verbose:
+                self._logger.error(f"Error checking status: {e}")
+            return False
+
+    @retry(
+        stop=stop_after_attempt(5),
+        wait=wait_fixed(1),
+        retry=retry_if_exception_type((ProcessError, OSError)),
+    )
+    def stop(self, id: str) -> bool:
+        """Stop Firecracker with retry mechanism.
+
+        Args:
+            id (str): The ID of the Firecracker VM
+
+        Returns:
+            bool: True if successfully stopped, False otherwise
+
+        Raises:
+            ProcessError: If process fails to stop after retries
+        """
+        try:
+            if os.path.exists(f"{self._config.data_path}/{id}/firecracker.pid"):
+                with open(f"{self._config.data_path}/{id}/firecracker.pid", "r") as f:
+                    original_pid = int(f.read().strip())
+
+                try:
+                    # Try to stop using the PID from file
+                    if self._try_stop_process(original_pid, id):
+                        self._cleanup_files(id)
+                        return True
+                except ProcessError as e:
+                    if self._logger.verbose:
+                        self._logger.warn(
+                            f"Failed to stop Firecracker (1st attempt): {e}"
+                        )
+
+                # If PID-based stop failed, search for actual running process
+                if self._logger.verbose:
+                    self._logger.info(
+                        f"PID {original_pid} not found, searching for running Firecracker process for VM {id}"
+                    )
+
+                actual_pid = self._find_running_process(id)
+                if actual_pid:
+                    if self._logger.verbose:
+                        self._logger.info(
+                            f"Found running Firecracker process {actual_pid} for VM {id}"
+                        )
+                    if self._try_stop_process(actual_pid, id):
+                        self._cleanup_files(id)
+                        return True
+                else:
+                    if self._logger.verbose:
+                        self._logger.info(
+                            f"No running Firecracker process found for VM {id}"
+                        )
+
+                # Clean up files even if no process found
+                self._cleanup_files(id)
+                return True
+            else:
+                # Clean up files even if no process found
+                self._cleanup_files(id)
+
+                if self._logger.verbose:
+                    self._logger.info("Firecracker is not running (no PID file)")
+                return False
+
+        except Exception as e:
+            if self._logger.verbose:
+                self._logger.error(f"Error stopping Firecracker: {e}")
+            raise ProcessError(f"Failed to stop Firecracker {id}: {str(e)}")
+
+    def _try_stop_process(self, pid: int, id: str) -> bool:
+        """Try to stop a specific process by PID.
+
+        Args:
+            pid (int): Process ID to stop
+            id (str): VM ID for logging
+
+        Returns:
+            bool: True if process was successfully stopped
+
+        Raises:
+            ProcessError: If process fails to stop
+        """
+
+        def wait_for_process_death(pid: int, timeout: float = 5.0) -> bool:
+            """Wait for process to die with timeout."""
+            start_time = time.time()
+            while time.time() - start_time < timeout:
+                try:
+                    os.kill(pid, 0)  # Check if process exists
+                    time.sleep(1)  # Wait 1 second before next check
+                except OSError as e:
+                    if e.errno == 3:  # ESRCH - No such process
+                        return True  # Process is dead
+                    else:
+                        raise ProcessError(f"Error checking process {pid}: {e}")
+            return False  # Timeout reached
+
+        try:
+            # First check if process exists
+            os.kill(pid, 0)
+        except OSError as e:
+            if e.errno == 3:  # ESRCH - No such process
+                if self._logger.verbose:
+                    self._logger.info(f"Firecracker process {pid} already terminated")
+                return True
+            else:
+                raise ProcessError(f"Failed to check process {pid}: {e}")
+
+        # Process exists, try graceful shutdown first
+        try:
+            os.kill(pid, 15)  # SIGTERM
+            if self._logger.verbose:
+                self._logger.debug(
+                    f"Sent SIGTERM to process {pid}, waiting for termination..."
+                )
+
+            # Wait for process to die after SIGTERM
+            if wait_for_process_death(pid, timeout=2):
+                if self._logger.verbose:
+                    self._logger.info(
+                        f"Firecracker process {pid} terminated after SIGTERM"
+                    )
+                return True
+            else:
+                if self._logger.verbose:
+                    self._logger.warn(
+                        f"Process {pid} did not terminate after SIGTERM, using SIGKILL"
+                    )
+
+        except OSError as e:
+            if e.errno == 3:  # ESRCH - No such process
+                if self._logger.verbose:
+                    self._logger.info(
+                        f"Firecracker process {pid} terminated after SIGTERM"
+                    )
+                return True
+            else:
+                raise ProcessError(f"Failed to send SIGTERM to process {pid}: {e}")
+
+        # Process still running after SIGTERM, try force kill
+        try:
+            os.kill(pid, 9)  # SIGKILL
+            if self._logger.verbose:
+                self._logger.debug(
+                    f"Sent SIGKILL to process {pid}, waiting for termination..."
+                )
+
+            # Wait for process to die after SIGKILL
+            if wait_for_process_death(pid, timeout=5):
+                if self._logger.verbose:
+                    self._logger.info(
+                        f"Firecracker process {pid} force killed with SIGKILL"
+                    )
+                return True
+            else:
+                raise ProcessError(
+                    f"Firecracker process {pid} still running after SIGKILL timeout"
+                )
+
+        except OSError as e:
+            if e.errno == 3:  # ESRCH - No such process
+                if self._logger.verbose:
+                    self._logger.info(
+                        f"Firecracker process {pid} terminated after SIGKILL"
+                    )
+                return True
+            else:
+                raise ProcessError(f"Failed to kill process {pid}: {e}")
+
+    def _find_running_process(self, id: str) -> int:
+        """Find the actual running Firecracker process for a given VM ID.
+
+        Args:
+            id (str): The VM ID to search for
+
+        Returns:
+            int: Process ID if found, None otherwise
+        """
+        try:
+            socket_path = f"{self._config.data_path}/{id}/firecracker.socket"
+
+            for pid in psutil.pids():
+                try:
+                    proc = psutil.Process(pid)
+                    if proc.name() == "firecracker":
+                        cmdline = proc.cmdline()
+                        if cmdline and len(cmdline) > 1:
+                            # Check if this process uses the same socket path
+                            for i, arg in enumerate(cmdline):
+                                if arg == "--api-sock" and i + 1 < len(cmdline):
+                                    if cmdline[i + 1] == socket_path:
+                                        return pid
+                except (
+                    psutil.NoSuchProcess,
+                    psutil.AccessDenied,
+                    psutil.ZombieProcess,
+                ):
+                    continue
+
+        except Exception as e:
+            if self._logger.verbose:
+                self._logger.warn(f"Error searching for running process: {e}")
+
+        return None
+
+    def _cleanup_files(self, id: str):
+        """Clean up PID and socket files for a VM.
+
+        Args:
+            id (str): The VM ID
+        """
+        # Clean up PID file
+        pid_file = f"{self._config.data_path}/{id}/firecracker.pid"
+        if os.path.exists(pid_file):
+            try:
+                os.remove(pid_file)
+                if self._logger.verbose:
+                    self._logger.debug(f"Removed PID file for VM {id}")
+            except OSError as e:
+                if self._logger.verbose:
+                    self._logger.warn(f"Failed to remove PID file: {e}")
+
+        # Clean up socket file
+        socket_path = f"{self._config.data_path}/{id}/firecracker.socket"
+        if os.path.exists(socket_path):
+            try:
+                os.remove(socket_path)
+                if self._logger.verbose:
+                    self._logger.debug(f"Removed socket file: {socket_path}")
+            except OSError as e:
+                if self._logger.verbose:
+                    self._logger.warn(f"Failed to remove socket file: {e}")
+
+    def get_pid(self, id: str) -> tuple:
+        """Get the PID of the Firecracker process.
+
+        Args:
+            id (str): The ID of the Firecracker VM
+
+        Returns:
+            tuple: (pid, create_time) if process is found and running
+
+        Raises:
+            ProcessError: If the process is not found or not running
+        """
+        try:
+            pid_file = f"{self._config.data_path}/{id}/firecracker.pid"
+            if not os.path.exists(pid_file):
+                raise ProcessError(f"No PID file found for VM {id}")
+
+            with open(pid_file, "r") as f:
+                pid = int(f.read().strip())
+
+            try:
+                process = psutil.Process(pid)
+                if not process.is_running():
+                    os.remove(pid_file)
+                    raise ProcessError(f"Firecracker process {pid} is not running")
+
+                if process.name() != "firecracker":
+                    os.remove(pid_file)
+                    raise ProcessError(f"Process {pid} is not a Firecracker process")
+
+                create_time = datetime.fromtimestamp(process.create_time()).strftime(
+                    "%Y-%m-%d %H:%M:%S"
+                )
+
+                if self._logger.verbose:
+                    self._logger.debug(
+                        f"Found Firecracker process {pid} created at {create_time}"
+                    )
+
+                return pid, create_time
+
+            except psutil.NoSuchProcess:
+                os.remove(pid_file)
+                raise ProcessError(f"Firecracker process {pid} is not running")
+
+            except psutil.AccessDenied:
+                raise ProcessError(f"Access denied to process {pid}")
+
+            except psutil.TimeoutExpired:
+                raise ProcessError(f"Timeout while checking process {pid}")
+
+        except Exception as e:
+            raise ProcessError(f"Failed to get Firecracker PID: {str(e)}")
+
+    def get_pids(self) -> list:
+        """
+        Get all PIDs of the Firecracker processes that have --api-sock parameter.
+
+        Returns:
+            list: List of process IDs (integers)
+        """
+        pid_list = []
+
+        try:
+            for pid in psutil.pids():
+                try:
+                    proc = psutil.Process(pid)
+                    if proc.name() == "firecracker":
+                        cmdline = proc.cmdline()
+                        if cmdline and len(cmdline) > 1 and "--api-sock" in cmdline:
+                            pid_list.append(pid)
+                except (
+                    psutil.NoSuchProcess,
+                    psutil.AccessDenied,
+                    psutil.ZombieProcess,
+                ):
+                    continue
+
+        except Exception as e:
+            raise ProcessError(f"Failed to get Firecracker processes: {str(e)}")
+
+        return pid_list
+
+    @staticmethod
+    def wait_process_running(process: psutil.Process):
+        """Wait for a process to run."""
+        assert process.is_running()

firecracker/scripts.py

@@ -0,0 +1,53 @@
+import os
+from .config import MicroVMConfig
+from .exceptions import ConfigurationError
+
+
+def check_firecracker_binary():
+    """Check if Firecracker binary exists and is executable.
+
+    Raises:
+        ConfigurationError: If binary is not found or not executable
+    """
+    try:
+        config = MicroVMConfig()
+        binary_path = config.binary_path
+
+        if not os.path.exists(binary_path):
+            raise ConfigurationError(f"Firecracker binary not found, please install Firecracker")
+
+        if not os.access(binary_path, os.X_OK):
+            raise ConfigurationError(f"Firecracker binary is not executable at: {binary_path}")
+
+    except Exception as e:
+        raise ConfigurationError(f"Failed to check Firecracker binary: {str(e)}") from e
+
+def create_firecracker_directory():
+    """Create the Firecracker data directory if it doesn't exist.
+
+    Raises:
+        ConfigurationError: If directory creation fails
+    """
+    try:
+        config = MicroVMConfig()
+        data_path = config.data_path
+
+        if not os.path.exists(data_path):
+            os.makedirs(data_path, mode=0o755)
+            print(f"Created Firecracker data directory at: {data_path}")
+
+        snapshot_path = config.snapshot_path
+        if not os.path.exists(snapshot_path):
+            os.makedirs(snapshot_path, mode=0o755)
+            print(f"Created Firecracker snapshot directory at: {snapshot_path}")
+
+    except Exception as e:
+        raise ConfigurationError(f"Failed to create Firecracker data directory: {str(e)}") from e
+
+
+if __name__ == "__main__":
+    if os.geteuid() != 0:
+        raise SystemExit("This script must be run as root.")
+
+    check_firecracker_binary()
+    create_firecracker_directory()

firecracker/utils.py

@@ -0,0 +1,192 @@
+import os
+import random
+import string
+import signal
+import requests
+import subprocess
+import socket
+from faker import Faker
+from tenacity import retry, stop_after_attempt, wait_fixed, retry_if_exception_type
+
+
+def run(cmd, **kwargs):
+    """Execute a shell command with configurable options.
+
+    Provides a convenient wrapper around subprocess.run with sensible defaults
+    for shell command execution.
+
+    Args:
+        cmd (str): Shell command to execute
+        **kwargs: Additional arguments to pass to subprocess.run
+            Defaults if not specified:
+            - shell=True: Enable shell command interpretation
+            - capture_output=True: Capture stdout/stderr
+            - text=True: Return string output instead of bytes
+
+    Returns:
+        subprocess.CompletedProcess: Process completion information including:
+            - returncode: Exit code of the command
+            - stdout: Standard output (if captured)
+            - stderr: Standard error (if captured)
+
+    Note:
+        Default behavior can be overridden by passing explicit kwargs
+    """
+    default_kwargs = {"shell": True, "capture_output": True, "text": True}
+    default_kwargs.update(kwargs)
+
+    return subprocess.run(cmd, **default_kwargs)
+
+
+def safe_kill(pid: int, sig: signal.Signals = signal.SIGTERM) -> bool:
+    """Safely kill a process."""
+    try:
+        os.kill(pid, sig)
+        return True
+    except ProcessLookupError:
+        return True
+    except PermissionError:
+        return False
+
+
+def generate_id() -> str:
+    """Generate a random ID for the MicroVM instance.
+
+    Returns:
+        str: A random identifier (exactly 8 lowercase alphanumeric characters)
+    """
+    chars = string.ascii_lowercase + string.digits
+    generated_id = "".join(random.choice(chars) for _ in range(8))
+    return generated_id
+
+
+def generate_name() -> str:
+    """Generate a random name for the MicroVM instance using Faker.
+
+    Returns:
+        str: A random name
+    """
+    fake = Faker()
+    generated_name = fake.name().replace(" ", "_").lower()
+    return generated_name
+
+
+def generate_mac_address() -> str:
+    """Generate a random MAC address for the MicroVM instance.
+
+    Returns:
+        str: A random MAC address in the format XX:XX:XX:XX:XX:XX
+    """
+    # Generate 6 random bytes
+    mac_bytes = [random.randint(0, 255) for _ in range(6)]
+    # Convert to hex and format with colons
+    mac_address = ":".join([f"{b:02x}" for b in mac_bytes])
+    return mac_address
+
+
+def requires_id(func):
+    """Decorator to check if VMM ID is provided."""
+
+    def wrapper(*args, **kwargs):
+        id = kwargs.get("id") or (len(args) > 1 and args[1])
+        if not id:
+            raise RuntimeError("VMM ID required")
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def validate_hostname(hostname):
+    """Validate hostname according to RFC 1123."""
+    import re
+
+    if not re.match(
+        r"^[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?)*$",
+        hostname,
+    ):
+        raise ValueError(f"Invalid hostname: {hostname}")
+
+
+def validate_ip_address(ip_addr: str) -> bool:
+    """Validate an IP address according to standard format rules.
+
+    Args:
+        ip_addr (str): The IP address to validate
+
+    Returns:
+        bool: True if the IP address is valid
+
+    Raises:
+        Exception: If the IP address is invalid, with a descriptive message
+    """
+    if not ip_addr:
+        raise Exception("IP address cannot be empty")
+
+    try:
+        # Test IP address format
+        socket.inet_aton(ip_addr)
+
+        # Check if the IP has exactly 4 parts
+        ip_parts = ip_addr.split(".")
+        if len(ip_parts) != 4:
+            raise Exception(f"Invalid IP address format: {ip_addr}")
+
+        # Check if any part is outside the valid range
+        for part in ip_parts:
+            if not (0 <= int(part) <= 255):
+                raise Exception(f"IP address contains invalid octet: {part}")
+
+        # Check if it's a reserved address (like .0 ending)
+        if ip_parts[-1] == "0":
+            raise Exception(f"IP address with .0 suffix is reserved: {ip_addr}")
+
+        return True
+
+    except (socket.error, ValueError):
+        raise Exception(f"Invalid IP address: {ip_addr}")
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_fixed(1),
+    retry=retry_if_exception_type(requests.RequestException),
+)
+def _try_get_ip_from_url(url: str, timeout: int = 5) -> str:
+    """Try to get public IP from a specific URL with retry logic.
+
+    Args:
+        url (str): URL to try for getting public IP
+        timeout (int): Request timeout in seconds
+
+    Returns:
+        str: Public IP address
+
+    Raises:
+        requests.RequestException: If all retry attempts fail
+    """
+    response = requests.get(url, timeout=timeout)
+    response.raise_for_status()
+    return response.text.strip()
+
+
+def get_public_ip(timeout: int = 5):
+    """Get the public IP address by trying multiple services.
+
+    Args:
+        timeout (int): Request timeout in seconds
+
+    Returns:
+        str: Public IP address
+
+    Raises:
+        RuntimeError: If all services fail to return a valid IP
+    """
+    URLS = ["https://ifconfig.me", "https://ipinfo.io/ip", "https://api.ipify.org"]
+
+    for url in URLS:
+        try:
+            return _try_get_ip_from_url(url, timeout)
+        except requests.RequestException:
+            continue
+
+    raise RuntimeError("Failed to get public IP")