rapidctl 0.1.0__py3-none-any.whl

rapidctl/bootstrap/client.py

@@ -0,0 +1,104 @@
+from typing import Optional, Dict, Any
+import re
+from urllib.parse import urlparse
+import os.path
+import rapidctl.cli.tasks
+from pathlib import Path
+import json
+import time
+
+from rapidctl.bootstrap.state import StateManager
+
+class CtlClient:
+    """
+    Class that defines and validates the required data that requires definition
+    on the CTL client side of the stack.
+
+    Once actions using this class are complete the CTL client should be ready
+    to connect to the container layer and start command provisioning.
+    """
+    def __init__(self, state_manager: Optional[StateManager] = None):
+        self.container_repo: Optional[str] = None
+        self.baseline_version: str = "1.0.0"
+        self.client_version: str = "0.0.1"
+        self.image_id: Optional[str] = None
+        self.command_path: str = "/opt/rapidctl/cmd/"
+        self.cli: Optional[Any] = None
+        
+        # Pluggable state manager
+        self.state_manager = state_manager or StateManager()
+        
+        # Load persisted version state if available
+        self._load_persisted_version()
+    
+    def check_for_updates(self) -> Optional[str]:
+        """Check if a newer container version exists locally."""
+        import rapidctl.cli.actions as actions
+        
+        if not self.cli:
+            self.connect()
+            
+        try:
+            newer = actions.find_newer_version(self.cli, self.container_repo, self.baseline_version)
+            return newer
+        except Exception:
+            return None
+
+
+
+    def _load_persisted_version(self) -> None:
+        """Attempt to load a pinned version from disk."""
+        if self.container_repo:
+            pinned = self.state_manager.get_state(f"version_{self.container_repo}")
+            if pinned:
+                self.baseline_version = pinned
+    
+    @property
+    def container_version(self):
+        """
+         Function to provide an view of the container image tag
+
+         Returns:
+            str: Aggregrated version of the container repo path and version
+        """
+        return self._container_validator("%s:%s" % (self.container_repo, self.baseline_version))
+
+    def set_version(self, version: str) -> None:
+        """Update the baseline version with validation."""
+        # Validate that the version string is safe
+        safe_version = re.sub(r'[^a-zA-Z0-9._-]', '', version)
+        if safe_version:
+            self.baseline_version = safe_version
+
+    def get_version(self) -> str:
+        """Return the current baseline version."""
+        return self.baseline_version
+
+    def persist_version(self) -> None:
+        """Persist the current baseline version to disk."""
+        if self.container_repo:
+            self.state_manager.set_state(f"version_{self.container_repo}", self.baseline_version)
+
+    def connect(self):
+        """
+        Connect to Podman and return the active session.
+        """
+        if self.cli is None:
+            from rapidctl.cli import PodmanCLI
+            self.cli = PodmanCLI()
+            self.cli._connect_to_podman()
+        return self.cli
+
+    def _container_validator(self, container_image):
+        """
+         Sanitize a container image URL/name to prevent command injection and ensure valid format.
+    
+        Args:
+            container_image (str): The container image URL or name to sanitize
+        
+        Returns:
+            str: Sanitized container image string or None if invalid
+        """
+        import rapidctl.cli.tasks as tasks
+        return tasks.sanitize_container_image(container_image)
+

rapidctl/bootstrap/connectors/__init__.py

@@ -0,0 +1,46 @@
+"""
+Connectors module for platform-specific container runtime connections.
+
+This module provides platform-specific connectors for different operating systems
+to detect and connect to container runtimes like Podman.
+"""
+
+import os
+import platform
+from typing import Optional
+
+
+def get_connector():
+    """
+    Get the appropriate connector for the current platform.
+    
+    Returns:
+        Connector instance for the current platform
+        
+    Raises:
+        NotImplementedError: If the current platform is not supported
+    """
+    system = platform.system()
+    
+    if system == "Darwin":
+        from rapidctl.bootstrap.connectors.osx import get_connector as get_osx_connector
+        return get_osx_connector()
+    elif system == "Linux":
+        from rapidctl.bootstrap.connectors.linux import get_connector as get_linux_connector
+        return get_linux_connector()
+    elif system == "Windows":
+        # TODO: Implement Windows connector
+        raise NotImplementedError(f"Windows connector not yet implemented")
+    else:
+        raise NotImplementedError(f"Unsupported platform: {system}")
+
+
+def detect_socket() -> Optional[str]:
+    """
+    Detect the container runtime socket for the current platform.
+    
+    Returns:
+        str: Socket URI or None if not found
+    """
+    connector = get_connector()
+    return connector.detect_socket()

rapidctl/bootstrap/connectors/base.py

@@ -0,0 +1,72 @@
+import os
+import shutil
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+
+class BaseConnector(ABC):
+    """
+    Abstract base class for platform-specific Podman connectors.
+    Defines the standard interface and common functionality shared
+    across the operating systems.
+    """
+
+    def __init__(self):
+        self.socket_path: Optional[str] = None
+
+    @abstractmethod
+    def detect_socket(self) -> Optional[str]:
+        """
+        Detect the Podman socket location for the current platform.
+        
+        Returns:
+            str: URI to the Podman socket or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def setup(self) -> bool:
+        """
+        Platform-specific setup routine, checking requirements and
+        providing guidance or auto-starting Podman if needed.
+        
+        Returns:
+            bool: True if Podman is ready and socket is found, False otherwise
+        """
+        pass
+
+    def is_podman_installed(self) -> bool:
+        """
+        Check if Podman is installed on the system.
+        
+        Returns:
+            bool: True if Podman executable is found in PATH, False otherwise
+        """
+        return shutil.which("podman") is not None
+
+    def _validate_socket(self, socket_uri: str) -> bool:
+        """
+        Validate that a socket path exists and is accessible.
+        
+        Args:
+            socket_uri: Socket URI (e.g., 'unix:///path/to/socket')
+            
+        Returns:
+            bool: True if socket is valid and accessible
+        """
+        if socket_uri.startswith("unix://"):
+            socket_path = socket_uri[7:]
+        else:
+            socket_path = socket_uri
+            
+        path = Path(socket_path)
+        
+        if not path.exists():
+            return False
+            
+        # Standard check: must be a socket and accessible
+        if path.is_socket():
+            return os.access(path, os.R_OK | os.W_OK)
+            
+        return False

rapidctl/bootstrap/connectors/linux.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Linux Connector for Podman
+
+Handles Linux-specific requirements for connecting to Podman:
+- Detects the Podman socket location (rootless and rootful)
+- Validates socket accessibility
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from rapidctl.bootstrap.connectors.base import BaseConnector
+
+
+class LinuxConnector(BaseConnector):
+    """Connector for Podman on Linux systems."""
+    
+    def __init__(self):
+        super().__init__()
+        
+    def detect_socket(self) -> Optional[str]:
+        """
+        Detect the Podman socket location on Linux.
+        
+        Checks:
+        1. Environment variable PODMAN_SOCKET
+        2. Rootless socket (XDG_RUNTIME_DIR/podman/podman.sock)
+        3. Rootful socket (/run/podman/podman.sock)
+        4. User-specific socket fallback (/run/user/UID/podman/podman.sock)
+        """
+        try:
+            # Fast path: return existing valid socket
+            if self.socket_path and self._validate_socket(self.socket_path):
+                return self.socket_path
+
+            # 1. Check environment variable
+            env_socket = os.environ.get("PODMAN_SOCKET")
+            if env_socket:
+                if self._validate_socket(env_socket):
+                    self.socket_path = env_socket
+                    return env_socket
+
+            # 2. Check XDG_RUNTIME_DIR (Standard for rootless)
+            xdg_runtime = os.environ.get("XDG_RUNTIME_DIR")
+            if xdg_runtime:
+                path = Path(xdg_runtime) / "podman/podman.sock"
+                try:
+                    if self._validate_socket(f"unix://{path}"):
+                        self.socket_path = f"unix://{path}"
+                        return self.socket_path
+                except PermissionError:
+                    pass
+
+            # 3. Check for specific UID-based path as fallback if XDG_RUNTIME_DIR is not set
+            try:
+                uid = os.getuid()
+                uid_path = Path(f"/run/user/{uid}/podman/podman.sock")
+                if uid_path.exists():
+                    if self._validate_socket(f"unix://{uid_path}"):
+                        self.socket_path = f"unix://{uid_path}"
+                        return self.socket_path
+            except PermissionError:
+                pass
+
+            # 4. Check rootful socket (requires permissions)
+            try:
+                rootful_path = Path("/run/podman/podman.sock")
+                if rootful_path.exists():
+                    if self._validate_socket(f"unix://{rootful_path}"):
+                        self.socket_path = f"unix://{rootful_path}"
+                        return self.socket_path
+            except PermissionError:
+                pass
+
+        except Exception:
+            # Catch-all for any other unexpected issues during detection
+            pass
+
+        return None
+    
+    def _validate_socket(self, socket_uri: str) -> bool:
+        """Validate that a socket path exists and is accessible."""
+        return super()._validate_socket(socket_uri)
+
+    def setup(self) -> bool:
+        """Basic setup for Linux."""
+        if not self.is_podman_installed():
+            return False
+            
+        return self.detect_socket() is not None
+
+
+def get_connector() -> LinuxConnector:
+    """Factory function."""
+    return LinuxConnector()

rapidctl/bootstrap/connectors/osx.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+OSX Connector for Podman
+
+This connector handles macOS-specific requirements for connecting to Podman:
+- Detects the Podman socket location
+- Validates socket accessibility
+- Sets up any OS-specific requirements
+"""
+
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+from rapidctl.bootstrap.connectors.base import BaseConnector
+
+
+class OSXConnector(BaseConnector):
+    """Connector for Podman on macOS systems."""
+    
+    def __init__(self):
+        super().__init__()
+        self.podman_machine_name: Optional[str] = None
+        
+    def detect_socket(self) -> Optional[str]:
+        """
+        Detect the Podman socket location on macOS.
+        
+        Checks multiple common locations in order of preference:
+        1. Environment variable PODMAN_SOCKET
+        2. User's podman machine socket (~/.local/share/containers/podman/machine/podman.sock)
+        3. System docker.sock (often symlinked to podman on macOS)
+        4. Podman machine-specific sockets
+        
+        Returns:
+            str: URI to the Podman socket (e.g., 'unix:///path/to/socket') or None if not found
+        """
+        # Fast path: return existing valid socket
+        if self.socket_path and self._validate_socket(self.socket_path):
+            return self.socket_path
+        # Check environment variable first
+        env_socket = os.environ.get("PODMAN_SOCKET")
+        if env_socket:
+            if self._validate_socket(env_socket):
+                self.socket_path = env_socket
+                return env_socket
+        
+        # Common socket locations on macOS
+        socket_candidates = [
+            # Podman machine default socket (symlink)
+            Path.home() / ".local/share/containers/podman/machine/podman.sock",
+            # System docker.sock (may be symlinked to podman)
+            Path("/var/run/docker.sock"),
+            # Podman Desktop socket
+            Path.home() / ".local/share/containers/podman/podman.sock",
+        ]
+        
+        # Check each candidate
+        for socket_path in socket_candidates:
+            if socket_path.exists():
+                socket_uri = f"unix://{socket_path}"
+                if self._validate_socket(socket_uri):
+                    self.socket_path = socket_uri
+                    return socket_uri
+        
+        # Try to find machine-specific sockets
+        machine_dir = Path.home() / ".local/share/containers/podman/machine"
+        if machine_dir.exists():
+            for machine_path in machine_dir.iterdir():
+                if machine_path.is_dir():
+                    socket_path = machine_path / "podman.sock"
+                    if socket_path.exists():
+                        socket_uri = f"unix://{socket_path}"
+                        if self._validate_socket(socket_uri):
+                            self.podman_machine_name = machine_path.name
+                            self.socket_path = socket_uri
+                            return socket_uri
+        
+        return None
+    
+    def _validate_socket(self, socket_uri: str) -> bool:
+        """
+        Validate that a socket path exists and is accessible.
+        
+        Args:
+            socket_uri: Socket URI (e.g., 'unix:///path/to/socket')
+            
+        Returns:
+            bool: True if socket is valid and accessible
+        """
+        # Call the base implementation first
+        if super()._validate_socket(socket_uri):
+            return True
+            
+        # The base implementation does not allow symlinks.
+        # Check if the fallback is a valid symlink to a socket.
+        if socket_uri.startswith("unix://"):
+            socket_path = socket_uri[7:]
+        else:
+            socket_path = socket_uri
+            
+        path = Path(socket_path)
+        if path.exists() and path.is_symlink():
+            return os.access(path, os.R_OK | os.W_OK)
+            
+        return False
+    
+    def ensure_podman_running(self) -> bool:
+        """
+        Check if Podman machine is running, and provide guidance if not.
+        
+        Returns:
+            bool: True if Podman is running, False otherwise
+        """
+        # Fast path: If socket is valid and accessible, Podman is effectively running
+        if self.socket_path and self._validate_socket(self.socket_path):
+            return True
+            
+        try:
+            # Check if podman command is available
+            result = subprocess.run(
+                ["podman", "machine", "list", "--format", "json"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            
+            if result.returncode == 0:
+                # Parse output to check if any machine is running
+                import json
+                machines = json.loads(result.stdout)
+                running_machines = [m for m in machines if m.get("Running", False)]
+                
+                if running_machines:
+                    self.podman_machine_name = running_machines[0].get("Name")
+                    return True
+                    
+        except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
+            pass
+            
+        return False
+    
+    def get_connection_info(self) -> dict:
+        """
+        Get connection information for Podman on macOS.
+        
+        Returns:
+            dict: Connection information including socket path and machine name
+        """
+        if not self.socket_path:
+            self.detect_socket()
+            
+        return {
+            "socket_path": self.socket_path,
+            "machine_name": self.podman_machine_name,
+            "platform": "darwin",
+            "connector": "osx"
+        }
+    
+    def setup(self) -> bool:
+        """
+        Set up the OSX connector and validate Podman availability.
+        
+        This method:
+        1. Checks if Podman is installed
+        2. Validates Podman is running and prompts to start if not
+        3. Detects the Podman socket
+        
+        Returns:
+            bool: True if setup successful, False otherwise
+        """
+        # 1. Check if podman is installed
+        if not self.is_podman_installed():
+            print("Podman is not installed. Please install it (e.g., using 'brew install podman').")
+            return False
+            
+        # 2. Check if Podman is running
+        if not self.ensure_podman_running():
+            # Prompt the user to start the machine
+            try:
+                import sys
+                sys.stdout.flush()
+                response = input("Podman machine is not running. Would you like to start it? [Y/n] ")
+                if response.lower() in ('', 'y', 'yes'):
+                    print("Starting Podman machine (this may take a moment)...")
+                    try:
+                        # Call podman machine start
+                        subprocess.run(
+                            ["podman", "machine", "start"],
+                            check=True,
+                            capture_output=True,
+                            text=True
+                        )
+                        # Wait a moment for the socket to be fully ready
+                        time.sleep(2)
+                        
+                        # Re-verify it's running after start
+                        if not self.ensure_podman_running():
+                            print("Warning: Podman machine started but status could not be verified.")
+                    except subprocess.CalledProcessError as e:
+                        print(f"Failed to start Podman machine: {e.stderr or e.output}")
+                        return False
+                else:
+                    print("Podman machine must be running to use this tool.")
+                    return False
+            except (KeyboardInterrupt, EOFError):
+                print("\nOperation cancelled.")
+                return False
+
+        # 3. Detect socket
+        socket = self.detect_socket()
+        if not socket:
+            print("Could not detect Podman socket automatically.")
+            return False
+            
+        return True
+
+
+def get_connector() -> OSXConnector:
+    """
+    Factory function to get an OSX connector instance.
+    
+    Returns:
+        OSXConnector: Configured OSX connector
+    """
+    connector = OSXConnector()
+    return connector

rapidctl/bootstrap/state.py

@@ -0,0 +1,107 @@
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+class StateManager:
+    """
+    Manages persistent state and cache data for rapidctl.
+    Pluggable by design: defaults to ~/.rapidctl/state.json, but can be
+    overridden for testing or multiple profiles.
+    """
+
+    def __init__(self, state_file: Optional[Path] = None):
+        """
+        Initialize the state manager.
+        
+        Args:
+            state_file: Path to the JSON state file. Defaults to ~/.rapidctl/state.json
+        """
+        self.state_file: Path = state_file or Path.home() / ".rapidctl" / "state.json"
+
+    def get_state(self, key: str) -> Any:
+        """
+        Get a value from the state file.
+        
+        Args:
+            key: The state key
+            
+        Returns:
+            Any: The stored value, or None if not found or on error
+        """
+        if not self.state_file.exists():
+            return None
+        
+        try:
+            with open(self.state_file, 'r') as f:
+                state = json.load(f)
+                return state.get(key)
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning(f"Failed to read state from {self.state_file}: {e}")
+            return None
+
+    def set_state(self, key: str, value: Any) -> None:
+        """
+        Set a value in the state file.
+        
+        Args:
+            key: The state key
+            value: The data to store (must be JSON serializable)
+        """
+        self.state_file.parent.mkdir(parents=True, exist_ok=True)
+        state = {}
+        
+        if self.state_file.exists():
+            try:
+                with open(self.state_file, 'r') as f:
+                    state = json.load(f)
+            except (json.JSONDecodeError, OSError) as e:
+                logger.warning(f"Failed to load existing state file, overwriting: {e}")
+                # We intentionally don't fail here and just overwrite with empty state dict
+                pass
+        
+        state[key] = value
+        
+        try:
+            with open(self.state_file, 'w') as f:
+                json.dump(state, f, indent=4)
+        except OSError as e:
+            logger.warning(f"Failed to write state to {self.state_file}: {e}")
+
+    def get_cache(self, key: str) -> Any:
+        """
+        Get a cached value if it has not expired.
+        
+        Args:
+            key: The cache key
+            
+        Returns:
+            Any: The cached data, or None if missing or expired
+        """
+        cache_data = self.get_state(f"cache_{key}")
+        if cache_data and isinstance(cache_data, dict):
+            timestamp = cache_data.get("timestamp", 0)
+            ttl = cache_data.get("ttl", 300) # Default 5 mins
+            
+            if time.time() - timestamp < ttl:
+                return cache_data.get("data")
+        return None
+
+    def set_cache(self, key: str, data: Any, ttl: int = 300) -> None:
+        """
+        Set a cached value with a time-to-live.
+        
+        Args:
+            key: The cache key
+            data: The data to cache
+            ttl: Time to live in seconds (default: 300)
+        """
+        cache_data = {
+            "timestamp": time.time(),
+            "ttl": ttl,
+            "data": data
+        }
+        self.set_state(f"cache_{key}", cache_data)