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

clonebox/health/models.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Data models for health check system."""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class HealthStatus(Enum):
+    """Health check status."""
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    DEGRADED = "degraded"
+    UNKNOWN = "unknown"
+    TIMEOUT = "timeout"
+
+
+class ProbeType(Enum):
+    """Type of health probe."""
+
+    HTTP = "http"
+    TCP = "tcp"
+    COMMAND = "command"
+    SCRIPT = "script"
+
+
+@dataclass
+class ProbeConfig:
+    """Configuration for a health probe."""
+
+    name: str
+    probe_type: ProbeType
+    enabled: bool = True
+
+    # Timing
+    timeout_seconds: float = 5.0
+    interval_seconds: float = 30.0
+    retries: int = 3
+    retry_delay_seconds: float = 1.0
+
+    # HTTP probe
+    url: Optional[str] = None
+    method: str = "GET"
+    expected_status: int = 200
+    expected_body: Optional[str] = None
+    expected_json: Optional[Dict[str, Any]] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    # TCP probe
+    host: str = "localhost"
+    port: Optional[int] = None
+
+    # Command probe
+    command: Optional[str] = None
+    expected_output: Optional[str] = None
+    expected_exit_code: int = 0
+
+    # Script probe
+    script_path: Optional[str] = None
+
+    # Thresholds
+    failure_threshold: int = 3  # Consecutive failures before unhealthy
+    success_threshold: int = 1  # Consecutive successes before healthy
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "type": self.probe_type.value,
+            "enabled": self.enabled,
+            "timeout": self.timeout_seconds,
+            "interval": self.interval_seconds,
+            "retries": self.retries,
+            "url": self.url,
+            "method": self.method,
+            "expected_status": self.expected_status,
+            "expected_body": self.expected_body,
+            "expected_json": self.expected_json,
+            "headers": self.headers,
+            "host": self.host,
+            "port": self.port,
+            "command": self.command,
+            "expected_output": self.expected_output,
+            "expected_exit_code": self.expected_exit_code,
+            "script_path": self.script_path,
+            "failure_threshold": self.failure_threshold,
+            "success_threshold": self.success_threshold,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ProbeConfig":
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            probe_type=ProbeType(data.get("type", "command")),
+            enabled=data.get("enabled", True),
+            timeout_seconds=data.get("timeout", 5.0),
+            interval_seconds=data.get("interval", 30.0),
+            retries=data.get("retries", 3),
+            url=data.get("url"),
+            method=data.get("method", "GET"),
+            expected_status=data.get("expected_status", 200),
+            expected_body=data.get("expected_body"),
+            expected_json=data.get("expected_json"),
+            headers=data.get("headers", {}),
+            host=data.get("host", "localhost"),
+            port=data.get("port"),
+            command=data.get("command") or data.get("exec"),
+            expected_output=data.get("expected_output"),
+            expected_exit_code=data.get("expected_exit_code", data.get("exit_code", 0)),
+            script_path=data.get("script_path") or data.get("path"),
+            failure_threshold=data.get("failure_threshold", 3),
+            success_threshold=data.get("success_threshold", 1),
+        )
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a health check."""
+
+    probe_name: str
+    status: HealthStatus
+    checked_at: datetime
+    duration_ms: float
+
+    message: Optional[str] = None
+    error: Optional[str] = None
+    details: Dict[str, Any] = field(default_factory=dict)
+
+    # Response info (for HTTP)
+    response_code: Optional[int] = None
+    response_body: Optional[str] = None
+
+    # Command info
+    exit_code: Optional[int] = None
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "probe_name": self.probe_name,
+            "status": self.status.value,
+            "checked_at": self.checked_at.isoformat(),
+            "duration_ms": self.duration_ms,
+            "message": self.message,
+            "error": self.error,
+            "details": self.details,
+            "response_code": self.response_code,
+            "exit_code": self.exit_code,
+        }
+
+    @property
+    def is_healthy(self) -> bool:
+        """Check if result indicates healthy status."""
+        return self.status == HealthStatus.HEALTHY
+
+
+@dataclass
+class VMHealthState:
+    """Aggregated health state for a VM."""
+
+    vm_name: str
+    overall_status: HealthStatus
+    last_check: datetime
+    check_results: List[HealthCheckResult] = field(default_factory=list)
+
+    # Counters
+    consecutive_failures: int = 0
+    consecutive_successes: int = 0
+    total_checks: int = 0
+    total_failures: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "vm_name": self.vm_name,
+            "overall_status": self.overall_status.value,
+            "last_check": self.last_check.isoformat(),
+            "check_results": [r.to_dict() for r in self.check_results],
+            "consecutive_failures": self.consecutive_failures,
+            "consecutive_successes": self.consecutive_successes,
+            "total_checks": self.total_checks,
+            "total_failures": self.total_failures,
+        }
+
+    @property
+    def failure_rate(self) -> float:
+        """Calculate failure rate percentage."""
+        if self.total_checks == 0:
+            return 0.0
+        return (self.total_failures / self.total_checks) * 100

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