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

firecracker/__init__.py

@@ -0,0 +1,23 @@
+from .microvm import MicroVM
+from .api import Api
+from .logger import Logger
+from . import scripts
+
+try:
+    scripts.check_firecracker_binary()
+    scripts.create_firecracker_directory()
+except scripts.ConfigurationError as e:
+    print(f"Warning: {e}")
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "MicroVM",
+    "Api",
+    "Logger",
+    "scripts",
+    "__version__",
+]

firecracker/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0.3.post0'
+__version_tuple__ = version_tuple = (1, 0, 3, 'post0')
+
+__commit_id__ = commit_id = 'g79b65ab4e'

firecracker/api.py

@@ -0,0 +1,183 @@
+import requests
+import urllib.parse
+from http import HTTPStatus
+from .exceptions import APIError
+from requests_unixsocket import UnixAdapter
+
+DEFAULT_SCHEME = "http://"
+DEFAULT_TIMEOUT = 5
+
+
+class Session(requests.Session):
+    """An HTTP over UNIX sockets Session with optimized connection pooling"""
+
+    def __init__(self, timeout=DEFAULT_TIMEOUT):
+        """Create a Session object.
+
+        Args:
+            timeout (int): Request timeout in seconds
+        """
+        super().__init__()
+        adapter = UnixAdapter(
+            pool_connections=20, pool_maxsize=20, max_retries=3, pool_block=True
+        )
+        self.mount(DEFAULT_SCHEME, adapter)
+
+
+class Resource:
+    """An abstraction over a REST path"""
+
+    def __init__(self, api, resource, id_field=None):
+        """Initialize a REST resource.
+
+        Args:
+            api (Api): The API client instance
+            resource (str): The resource path
+            id_field (str, optional): The field name used for resource ID
+        """
+        self._api = api
+        self.resource = resource
+        self.id_field = id_field
+
+    def get(self, timeout=None):
+        """Make a GET request.
+
+        Args:
+            timeout (int, optional): Request timeout in seconds
+
+        Returns:
+            requests.Response: The HTTP response
+
+        Raises:
+            APIError: If request fails or returns an error response
+        """
+        try:
+            url = self._api.endpoint + self.resource
+            request_timeout = (
+                timeout if timeout is not None else self._api.get_timeout()
+            )
+            with self._api.session.get(url, timeout=request_timeout) as res:
+                if res.status_code != HTTPStatus.OK:
+                    json = res.json()
+                    if "fault_message" in json:
+                        raise APIError(f"API fault: {json['fault_message']}")
+                    elif "error" in json:
+                        raise APIError(f"API error: {json['error']}")
+                    raise APIError(f"Unexpected response: {res.content}")
+
+                return res
+
+        except requests.RequestException as e:
+            raise APIError(f"GET request failed: {str(e)}") from e
+        except ValueError as e:
+            raise APIError(f"Invalid JSON response: {str(e)}") from e
+
+    def put(self, **kwargs):
+        """Make a PUT request.
+
+        Args:
+            **kwargs: Key-value pairs for the request body
+
+        Returns:
+            requests.Response: The HTTP response
+        """
+        path = self.resource
+        if self.id_field is not None:
+            path += "/" + kwargs[self.id_field]
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, **kwargs):
+        """Make a PATCH request.
+
+        Args:
+            **kwargs: Key-value pairs for the request body
+
+        Returns:
+            requests.Response: The HTTP response
+        """
+        path = self.resource
+        if self.id_field is not None:
+            path += "/" + kwargs[self.id_field]
+        return self.request("PATCH", path, **kwargs)
+
+    def request(self, method, path, timeout=None, **kwargs):
+        """Make an HTTP request to the Firecracker API.
+
+        Args:
+            method (str): HTTP method (GET, PUT, POST, DELETE, etc.)
+            path (str): API endpoint path
+            timeout (int, optional): Request timeout in seconds
+            **kwargs: Additional arguments to be sent as JSON in request body
+
+        Returns:
+            requests.Response: The HTTP response from the API
+
+        Raises:
+            APIError: If request fails or returns an error response
+        """
+        try:
+            kwargs = {key: val for key, val in kwargs.items() if val is not None}
+            url = self._api.endpoint + path
+            request_timeout = (
+                timeout if timeout is not None else self._api.get_timeout()
+            )
+            with self._api.session.request(
+                method, url, json=kwargs, timeout=request_timeout
+            ) as res:
+                if res.status_code != HTTPStatus.NO_CONTENT:
+                    json = res.json()
+                    if "fault_message" in json:
+                        raise APIError(f"API fault: {json['fault_message']}")
+                    elif "error" in json:
+                        raise APIError(f"API error: {json['error']}")
+                    raise APIError(f"Unexpected response: {res.content}")
+                return res
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}") from e
+        except ValueError as e:
+            raise APIError(f"Invalid JSON response: {str(e)}") from e
+
+
+class Api:
+    """A simple HTTP client for Firecracker API"""
+
+    def __init__(self, socket_file, timeout=DEFAULT_TIMEOUT):
+        """Initialize API client.
+
+        Args:
+            socket_file (str): Path to Firecracker API socket
+            timeout (int): Request timeout in seconds (default: 5)
+        """
+        self.socket = socket_file
+        self.timeout = timeout
+        url_encoded_path = urllib.parse.quote_plus(socket_file)
+        self.endpoint = DEFAULT_SCHEME + url_encoded_path
+        self.session = Session(timeout=timeout)
+
+        self.describe = Resource(self, "/")
+        self.vm = Resource(self, "/vm")
+        self.vm_config = Resource(self, "/vm/config")
+        self.actions = Resource(self, "/actions")
+        self.boot = Resource(self, "/boot-source")
+        self.drive = Resource(self, "/drives", "drive_id")
+        self.version = Resource(self, "/version")
+        self.logger = Resource(self, "/logger")
+        self.machine_config = Resource(self, "/machine-config")
+        self.network = Resource(self, "/network-interfaces", "iface_id")
+        self.mmds = Resource(self, "/mmds")
+        self.mmds_config = Resource(self, "/mmds/config")
+        self.create_snapshot = Resource(self, "/snapshot/create")
+        self.load_snapshot = Resource(self, "/snapshot/load")
+        self.vsock = Resource(self, "/vsock")
+
+    def get_timeout(self):
+        """Get timeout for API requests.
+
+        Returns:
+            int: Timeout value in seconds
+        """
+        return getattr(self, "timeout", DEFAULT_TIMEOUT)
+
+    def close(self):
+        """Close the session to release resources."""
+        self.session.close()

firecracker/config.py

@@ -0,0 +1,30 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class MicroVMConfig:
+    """Configuration defaults for Firecracker microVMs."""
+    data_path: str = "/var/lib/firecracker"
+    binary_path: str = "/usr/local/bin/firecracker"
+    snapshot_path: str = "/var/lib/firecracker/snapshots"
+    kernel_file: str = None
+    rootfs_size: str = "5G"
+    initrd_file: str = None
+    init_file: str = "/sbin/init"
+    base_rootfs: str = None
+    overlayfs: bool = False
+    overlayfs_file: str = None
+    ip_addr: str = "172.16.0.2"
+    mmds_enabled: bool = False
+    mmds_ip: str = "169.254.169.254"
+    user_data: str = None
+    vcpu: int = 1
+    memory: int = 512
+    verbose: bool = False
+    ssh_user: str = "root"
+    expose_ports: bool = False
+    host_port: int = None
+    dest_port: int = None
+    vsock_enabled: bool = False
+    vsock_guest_cid: int = 3

firecracker/exceptions.py

@@ -0,0 +1,33 @@
+"""Custom exceptions for the Firecracker library."""
+
+
+class FirecrackerError(Exception):
+    """Base exception for all Firecracker errors."""
+    def __init__(self, message: str, *args, **kwargs):
+        self.message = message
+        super().__init__(message, *args)
+
+
+class NetworkError(FirecrackerError):
+    """Network-related errors."""
+    pass
+
+
+class ConfigurationError(FirecrackerError):
+    """Configuration-related errors."""
+    pass
+
+
+class VMMError(FirecrackerError):
+    """VMM operation errors."""
+    pass
+
+
+class APIError(FirecrackerError):
+    """API-related errors."""
+    pass
+
+
+class ProcessError(FirecrackerError):
+    """Process management errors."""
+    pass

firecracker/logger.py

@@ -0,0 +1,98 @@
+import logging
+
+
+class Logger:
+    """Custom logger class for MicroVM operations."""
+    COLORS = {
+        "INFO": "\033[0m",
+        "ERROR": "\033[91m",
+        "WARNING": "\033[93m",
+        "DEBUG": "\033[94m",
+    }
+    RESET = "\033[0m"
+
+    LEVEL_MAP = {
+        "DEBUG": logging.DEBUG,
+        "INFO": logging.INFO,
+        "WARN": logging.WARNING,
+        "ERROR": logging.ERROR,
+    }
+
+    def __init__(self, level: str = "INFO", verbose: bool = False):
+        """Initialize the logger with custom configuration.
+
+        Args:
+            level (str): Initial log level (INFO, ERROR, WARN, DEBUG)
+            verbose (bool): Enable verbose (DEBUG) logging
+        """
+        self.logger = logging.getLogger('microvm')
+        self.logger.propagate = False
+        self.verbose = verbose
+
+        for handler in self.logger.handlers[:]:
+            self.logger.removeHandler(handler)
+
+        console_handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "\r[%(asctime)s.%(msecs)03d] [%(colored_levelname)s] %(message)s",
+            "%Y-%m-%dT%H:%M:%S"
+        )
+        console_handler.addFilter(self._add_colored_levelname)
+        console_handler.setFormatter(formatter)
+        self.logger.addHandler(console_handler)
+
+        self.set_level(level)
+
+    def _add_colored_levelname(self, record):
+        """Add colored levelname to the log record."""
+        level = record.levelname
+        if level == "INFO" and getattr(record, "success", False):
+            level = "SUCCESS"
+        color = self.COLORS.get(level, self.COLORS["INFO"])
+        record.colored_levelname = f"{color}{level}{self.RESET}"
+        return True
+
+    def set_level(self, level: str):
+        """Set the logging level.
+
+        Args:
+            level (str): Log level to set (INFO, ERROR, WARNING, DEBUG)
+        """
+        level = level.upper()
+        logging_level = self.LEVEL_MAP.get(level, logging.INFO)
+        self.logger.setLevel(logging_level)
+        self.current_level = level
+
+    def __call__(self, level: str, message: str):
+        """Log a message at the specified level.
+
+        Args:
+            level (str): Level to log at (INFO, ERROR, WARNING, DEBUG)
+            message (str): Message to log
+        """
+        level = level.upper()
+        if level not in self.LEVEL_MAP:
+            level = "INFO"  # Default to INFO for unknown levels
+
+        msg_level = self.LEVEL_MAP[level]
+        current_level = self.LEVEL_MAP[self.current_level]
+
+        if msg_level >= current_level:
+            log_method = getattr(self.logger, level.lower())
+            log_method(message)
+
+    def info(self, message: str):
+        """Log an info message."""
+        self("INFO", message)
+
+    def error(self, message: str):
+        """Log an error message."""
+        self("ERROR", message)
+
+    def warn(self, message: str):
+        """Log a warning message."""
+        self("WARN", message)
+
+    def debug(self, message: str):
+        """Log a debug message."""
+        self("DEBUG", message)