clonebox 1.1.4__py3-none-any.whl → 1.1.5__py3-none-any.whl

clonebox/health/probes.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""Health check probes for different protocols."""
+
+import socket
+import subprocess
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Optional
+
+from .models import HealthCheckResult, HealthStatus, ProbeConfig
+
+try:
+    import urllib.request
+    import urllib.error
+except ImportError:
+    urllib = None
+
+
+class HealthProbe(ABC):
+    """Abstract base class for health probes."""
+
+    @abstractmethod
+    def check(self, config: ProbeConfig) -> HealthCheckResult:
+        """Execute health check and return result."""
+        pass
+
+    def _create_result(
+        self,
+        config: ProbeConfig,
+        status: HealthStatus,
+        duration_ms: float,
+        **kwargs,
+    ) -> HealthCheckResult:
+        """Create a health check result."""
+        return HealthCheckResult(
+            probe_name=config.name,
+            status=status,
+            checked_at=datetime.now(),
+            duration_ms=duration_ms,
+            **kwargs,
+        )
+
+
+class HTTPProbe(HealthProbe):
+    """HTTP/HTTPS health probe."""
+
+    def check(self, config: ProbeConfig) -> HealthCheckResult:
+        """Check HTTP endpoint."""
+        if not config.url:
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                0,
+                error="No URL configured",
+            )
+
+        start = time.time()
+        try:
+            req = urllib.request.Request(
+                config.url,
+                method=config.method,
+                headers=config.headers or {},
+            )
+
+            with urllib.request.urlopen(req, timeout=config.timeout_seconds) as response:
+                duration_ms = (time.time() - start) * 1000
+                status_code = response.getcode()
+                body = response.read().decode("utf-8", errors="replace")
+
+                # Check status code
+                if status_code != config.expected_status:
+                    return self._create_result(
+                        config,
+                        HealthStatus.UNHEALTHY,
+                        duration_ms,
+                        message=f"Expected status {config.expected_status}, got {status_code}",
+                        response_code=status_code,
+                        response_body=body[:500],
+                    )
+
+                # Check body content
+                if config.expected_body and config.expected_body not in body:
+                    return self._create_result(
+                        config,
+                        HealthStatus.UNHEALTHY,
+                        duration_ms,
+                        message=f"Expected body content not found",
+                        response_code=status_code,
+                        response_body=body[:500],
+                    )
+
+                # Check JSON response
+                if config.expected_json:
+                    import json
+
+                    try:
+                        json_body = json.loads(body)
+                        for key, expected_value in config.expected_json.items():
+                            if json_body.get(key) != expected_value:
+                                return self._create_result(
+                                    config,
+                                    HealthStatus.UNHEALTHY,
+                                    duration_ms,
+                                    message=f"JSON field '{key}' mismatch",
+                                    response_code=status_code,
+                                    details={"expected": expected_value, "got": json_body.get(key)},
+                                )
+                    except json.JSONDecodeError as e:
+                        return self._create_result(
+                            config,
+                            HealthStatus.UNHEALTHY,
+                            duration_ms,
+                            message="Invalid JSON response",
+                            error=str(e),
+                        )
+
+                return self._create_result(
+                    config,
+                    HealthStatus.HEALTHY,
+                    duration_ms,
+                    message="OK",
+                    response_code=status_code,
+                )
+
+        except urllib.error.HTTPError as e:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                duration_ms,
+                error=f"HTTP error: {e.code}",
+                response_code=e.code,
+            )
+        except urllib.error.URLError as e:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                duration_ms,
+                error=f"Connection error: {e.reason}",
+            )
+        except TimeoutError:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.TIMEOUT,
+                duration_ms,
+                error=f"Timeout after {config.timeout_seconds}s",
+            )
+        except Exception as e:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                duration_ms,
+                error=str(e),
+            )
+
+
+class TCPProbe(HealthProbe):
+    """TCP port connectivity probe."""
+
+    def check(self, config: ProbeConfig) -> HealthCheckResult:
+        """Check TCP port connectivity."""
+        if not config.port:
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                0,
+                error="No port configured",
+            )
+
+        start = time.time()
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(config.timeout_seconds)
+
+            result = sock.connect_ex((config.host, config.port))
+            duration_ms = (time.time() - start) * 1000
+            sock.close()
+
+            if result == 0:
+                return self._create_result(
+                    config,
+                    HealthStatus.HEALTHY,
+                    duration_ms,
+                    message=f"Port {config.port} is open",
+                    details={"host": config.host, "port": config.port},
+                )
+            else:
+                return self._create_result(
+                    config,
+                    HealthStatus.UNHEALTHY,
+                    duration_ms,
+                    error=f"Port {config.port} is closed (code: {result})",
+                    details={"host": config.host, "port": config.port},
+                )
+
+        except socket.timeout:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.TIMEOUT,
+                duration_ms,
+                error=f"Connection timeout to {config.host}:{config.port}",
+            )
+        except Exception as e:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                duration_ms,
+                error=str(e),
+            )
+
+
+class CommandProbe(HealthProbe):
+    """Command execution probe."""
+
+    def check(self, config: ProbeConfig) -> HealthCheckResult:
+        """Execute command and check result."""
+        if not config.command:
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                0,
+                error="No command configured",
+            )
+
+        start = time.time()
+        try:
+            result = subprocess.run(
+                config.command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=config.timeout_seconds,
+            )
+            duration_ms = (time.time() - start) * 1000
+
+            stdout = result.stdout.strip()
+            stderr = result.stderr.strip()
+
+            # Check exit code
+            if result.returncode != config.expected_exit_code:
+                return self._create_result(
+                    config,
+                    HealthStatus.UNHEALTHY,
+                    duration_ms,
+                    message=f"Exit code {result.returncode}, expected {config.expected_exit_code}",
+                    exit_code=result.returncode,
+                    stdout=stdout[:500],
+                    stderr=stderr[:500],
+                )
+
+            # Check expected output
+            if config.expected_output and config.expected_output not in stdout:
+                return self._create_result(
+                    config,
+                    HealthStatus.UNHEALTHY,
+                    duration_ms,
+                    message=f"Expected output not found",
+                    exit_code=result.returncode,
+                    stdout=stdout[:500],
+                    details={"expected": config.expected_output},
+                )
+
+            return self._create_result(
+                config,
+                HealthStatus.HEALTHY,
+                duration_ms,
+                message="OK",
+                exit_code=result.returncode,
+                stdout=stdout[:500] if stdout else None,
+            )
+
+        except subprocess.TimeoutExpired:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.TIMEOUT,
+                duration_ms,
+                error=f"Command timeout after {config.timeout_seconds}s",
+            )
+        except Exception as e:
+            duration_ms = (time.time() - start) * 1000
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                duration_ms,
+                error=str(e),
+            )
+
+
+class ScriptProbe(HealthProbe):
+    """Script execution probe."""
+
+    def check(self, config: ProbeConfig) -> HealthCheckResult:
+        """Execute script and check result."""
+        if not config.script_path:
+            return self._create_result(
+                config,
+                HealthStatus.UNHEALTHY,
+                0,
+                error="No script path configured",
+            )
+
+        # Use CommandProbe with script path
+        cmd_config = ProbeConfig(
+            name=config.name,
+            probe_type=config.probe_type,
+            command=config.script_path,
+            expected_exit_code=config.expected_exit_code,
+            expected_output=config.expected_output,
+            timeout_seconds=config.timeout_seconds,
+        )
+
+        cmd_probe = CommandProbe()
+        return cmd_probe.check(cmd_config)
+
+
+def get_probe(probe_type: str) -> HealthProbe:
+    """Get probe instance by type."""
+    from .models import ProbeType
+
+    probes = {
+        ProbeType.HTTP: HTTPProbe(),
+        ProbeType.TCP: TCPProbe(),
+        ProbeType.COMMAND: CommandProbe(),
+        ProbeType.SCRIPT: ScriptProbe(),
+    }
+
+    if isinstance(probe_type, str):
+        probe_type = ProbeType(probe_type)
+
+    return probes.get(probe_type, CommandProbe())

clonebox/interfaces/disk.py

@@ -0,0 +1,40 @@
+"""Interfaces for CloneBox disk management."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class DiskManager(ABC):
+    """Abstract interface for disk operations."""
+
+    @abstractmethod
+    def create_disk(
+        self,
+        path: Path,
+        size_gb: int,
+        format: str = "qcow2",
+        backing_file: Optional[Path] = None,
+    ) -> Path:
+        """Create a disk image."""
+        pass
+
+    @abstractmethod
+    def resize_disk(self, path: Path, new_size_gb: int) -> None:
+        """Resize a disk image."""
+        pass
+
+    @abstractmethod
+    def get_disk_info(self, path: Path) -> Dict[str, Any]:
+        """Get disk image information."""
+        pass
+
+    @abstractmethod
+    def create_snapshot(self, path: Path, snapshot_name: str) -> Path:
+        """Create disk snapshot."""
+        pass
+
+    @abstractmethod
+    def delete_disk(self, path: Path) -> None:
+        """Delete disk image."""
+        pass

clonebox/interfaces/hypervisor.py

@@ -0,0 +1,89 @@
+"""Interfaces for CloneBox hypervisor backends."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class VMInfo:
+    """VM information returned by hypervisor."""
+
+    name: str
+    state: str
+    uuid: str
+    memory_mb: int
+    vcpus: int
+    ip_addresses: List[str]
+    created_at: Optional[str] = None
+    metadata: Dict[str, Any] = None
+
+
+class HypervisorBackend(ABC):
+    """Abstract interface for hypervisor operations."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Backend name (e.g., 'libvirt', 'podman')."""
+        pass
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish connection to hypervisor."""
+        pass
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close connection."""
+        pass
+
+    @abstractmethod
+    def define_vm(self, config: Any) -> str:
+        """Define a new VM. Returns VM UUID or name."""
+        pass
+
+    @abstractmethod
+    def undefine_vm(self, name: str) -> None:
+        """Remove VM definition."""
+        pass
+
+    @abstractmethod
+    def start_vm(self, name: str) -> None:
+        """Start a VM."""
+        pass
+
+    @abstractmethod
+    def stop_vm(self, name: str, force: bool = False) -> None:
+        """Stop a VM."""
+        pass
+
+    @abstractmethod
+    def get_vm_info(self, name: str) -> Optional[VMInfo]:
+        """Get VM information."""
+        pass
+
+    @abstractmethod
+    def list_vms(self) -> List[VMInfo]:
+        """List all VMs."""
+        pass
+
+    @abstractmethod
+    def vm_exists(self, name: str) -> bool:
+        """Check if VM exists."""
+        pass
+
+    @abstractmethod
+    def is_running(self, name: str) -> bool:
+        """Check if VM is running."""
+        pass
+
+    @abstractmethod
+    def execute_command(
+        self,
+        name: str,
+        command: str,
+        timeout: int = 30,
+    ) -> Optional[str]:
+        """Execute command in VM."""
+        pass

clonebox/interfaces/network.py

@@ -0,0 +1,33 @@
+"""Interfaces for CloneBox network management."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+
+class NetworkManager(ABC):
+    """Abstract interface for network operations."""
+
+    @abstractmethod
+    def create_network(self, name: str, config: Dict[str, Any]) -> None:
+        """Create a virtual network."""
+        pass
+
+    @abstractmethod
+    def delete_network(self, name: str) -> None:
+        """Delete a virtual network."""
+        pass
+
+    @abstractmethod
+    def network_exists(self, name: str) -> bool:
+        """Check if network exists."""
+        pass
+
+    @abstractmethod
+    def is_network_active(self, name: str) -> bool:
+        """Check if network is active."""
+        pass
+
+    @abstractmethod
+    def get_vm_ip(self, vm_name: str) -> Optional[str]:
+        """Get VM's IP address."""
+        pass

clonebox/interfaces/process.py

@@ -0,0 +1,46 @@
+"""Abstract interface for process execution."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ProcessResult:
+    """Result of process execution."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def success(self) -> bool:
+        return self.returncode == 0
+
+
+class ProcessRunner(ABC):
+    """Abstract interface for process execution."""
+
+    @abstractmethod
+    def run(
+        self,
+        command: List[str],
+        capture_output: bool = True,
+        timeout: Optional[int] = None,
+        check: bool = True,
+        cwd: Optional[Path] = None,
+        env: Optional[Dict[str, str]] = None,
+    ) -> ProcessResult:
+        """Run a command."""
+        pass
+
+    @abstractmethod
+    def run_shell(
+        self,
+        command: str,
+        capture_output: bool = True,
+        timeout: Optional[int] = None,
+    ) -> ProcessResult:
+        """Run a shell command."""
+        pass

clonebox/logging.py

@@ -0,0 +1,125 @@
+"""
+Structured logging for CloneBox using structlog.
+"""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import structlog
+
+
+def configure_logging(
+    level: str = "INFO",
+    json_output: bool = False,
+    log_file: Optional[Path] = None,
+    console_output: bool = True,
+) -> None:
+    """
+    Configure structured logging for CloneBox.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR)
+        json_output: If True, output JSON format (good for log aggregation)
+        log_file: Optional file path for log output
+        console_output: If True, also output to console
+    """
+
+    # Shared processors for all outputs
+    shared_processors = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+    if json_output:
+        # JSON output for production/aggregation
+        renderer = structlog.processors.JSONRenderer()
+    else:
+        # Human-readable output for development
+        renderer = structlog.dev.ConsoleRenderer(
+            colors=True,
+            exception_formatter=structlog.dev.plain_traceback,
+        )
+
+    structlog.configure(
+        processors=shared_processors
+        + [
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    # Configure standard logging
+    handlers = []
+
+    if console_output:
+        console_handler = logging.StreamHandler(sys.stderr)
+        console_handler.setFormatter(
+            structlog.stdlib.ProcessorFormatter(
+                processor=renderer,
+                foreign_pre_chain=shared_processors,
+            )
+        )
+        handlers.append(console_handler)
+
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(
+            structlog.stdlib.ProcessorFormatter(
+                processor=structlog.processors.JSONRenderer(),  # Always JSON for files
+                foreign_pre_chain=shared_processors,
+            )
+        )
+        handlers.append(file_handler)
+
+    logging.basicConfig(
+        format="%(message)s",
+        level=getattr(logging, level.upper()),
+        handlers=handlers,
+    )
+
+
+def get_logger(name: str = "clonebox") -> structlog.stdlib.BoundLogger:
+    """Get a structured logger instance."""
+    return structlog.get_logger(name)
+
+
+# Context managers for operation tracking
+from contextlib import contextmanager
+
+
+@contextmanager
+def log_operation(logger: structlog.stdlib.BoundLogger, operation: str, **kwargs):
+    """
+    Context manager for logging operation start/end.
+
+    Usage:
+        with log_operation(log, "create_vm", vm_name="my-vm"):
+            # do stuff
+    """
+    log = logger.bind(operation=operation, **kwargs)
+    start_time = datetime.now()
+    log.info(f"{operation}.started")
+
+    try:
+        yield log
+        duration_ms = (datetime.now() - start_time).total_seconds() * 1000
+        log.info(f"{operation}.completed", duration_ms=round(duration_ms, 2))
+    except Exception as e:
+        duration_ms = (datetime.now() - start_time).total_seconds() * 1000
+        log.error(
+            f"{operation}.failed",
+            error=str(e),
+            error_type=type(e).__name__,
+            duration_ms=round(duration_ms, 2),
+        )
+        raise

clonebox/monitor.py

@@ -217,9 +217,7 @@ class ResourceMonitor:
     def _check_engine(self, engine: str) -> bool:
         """Check if container engine is available."""
         try:
-            result = subprocess.run(
-                [engine, "--version"], capture_output=True, timeout=5
-            )
+            result = subprocess.run([engine, "--version"], capture_output=True, timeout=5)
             return result.returncode == 0
         except Exception:
             return False

clonebox/p2p.py

@@ -14,8 +14,10 @@ class P2PManager:
 
     def __init__(self, ssh_options: Optional[list] = None):
         self.ssh_options = ssh_options or [
-            "-o", "StrictHostKeyChecking=no",
-            "-o", "UserKnownHostsFile=/dev/null",
+            "-o",
+            "StrictHostKeyChecking=no",
+            "-o",
+            "UserKnownHostsFile=/dev/null",
         ]
 
     def _run_ssh(self, host: str, command: str) -> subprocess.CompletedProcess: