supervaizer 0.9.8__py3-none-any.whl → 0.10.1__py3-none-any.whl

supervaizer/deploy/health.py

@@ -0,0 +1,404 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+"""
+Health Check Utilities
+
+This module provides enhanced health verification functionality with retry logic,
+exponential backoff, and detailed health reporting for deployment verification.
+"""
+
+import asyncio
+import time
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+from enum import Enum
+
+import httpx
+from rich.console import Console
+
+from supervaizer.common import log
+
+console = Console()
+
+
+class HealthStatus(Enum):
+    """Health check status enumeration."""
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    TIMEOUT = "timeout"
+    ERROR = "error"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a health check operation."""
+
+    status: HealthStatus
+    response_time: float
+    status_code: Optional[int] = None
+    error_message: Optional[str] = None
+    endpoint: Optional[str] = None
+    timestamp: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.timestamp == 0.0:
+            self.timestamp = time.time()
+
+
+@dataclass
+class HealthCheckConfig:
+    """Configuration for health check operations."""
+
+    timeout: int = 60
+    max_retries: int = 5
+    base_delay: float = 1.0
+    max_delay: float = 30.0
+    backoff_multiplier: float = 2.0
+    success_threshold: int = 1  # Number of successful checks required
+    endpoints: Optional[List[str]] = None
+
+    def __post_init__(self) -> None:
+        if self.endpoints is None:
+            self.endpoints = ["/.well-known/health"]
+
+
+class HealthVerifier:
+    """Enhanced health verification with retry logic and exponential backoff."""
+
+    def __init__(self, config: Optional[HealthCheckConfig] = None):
+        """Initialize the health verifier with configuration."""
+        self.config = config or HealthCheckConfig()
+
+    def verify_health(
+        self,
+        service_url: str,
+        api_key: Optional[str] = None,
+        config: Optional[HealthCheckConfig] = None,
+    ) -> HealthCheckResult:
+        """
+        Verify service health with retry logic and exponential backoff.
+
+        Args:
+            service_url: Base URL of the service
+            api_key: Optional API key for authenticated endpoints
+            config: Optional configuration override
+
+        Returns:
+            HealthCheckResult with detailed status information
+        """
+        config = config or self.config
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+
+        last_error = None
+        successful_checks = 0
+        total_attempts = 0
+
+        for attempt in range(config.max_retries):
+            total_attempts += 1
+            start_time = time.time()
+
+            try:
+                # Check all configured endpoints
+                if not config.endpoints:
+                    last_error = "No endpoints configured"
+                    continue
+                all_healthy = True
+                for endpoint in config.endpoints:
+                    endpoint_url = f"{service_url.rstrip('/')}{endpoint}"
+
+                    with httpx.Client(timeout=config.timeout) as client:
+                        response = client.get(endpoint_url, headers=headers)
+
+                        if response.status_code != 200:
+                            all_healthy = False
+                            last_error = (
+                                f"Endpoint {endpoint} returned {response.status_code}"
+                            )
+                            break
+
+                if all_healthy:
+                    successful_checks += 1
+                    if successful_checks >= config.success_threshold:
+                        response_time = time.time() - start_time
+                        return HealthCheckResult(
+                            status=HealthStatus.HEALTHY,
+                            response_time=response_time,
+                            status_code=200,
+                            endpoint=config.endpoints[0] if config.endpoints else None,
+                        )
+                else:
+                    last_error = last_error or "One or more endpoints failed"
+
+            except httpx.TimeoutException:
+                last_error = f"Request timeout after {config.timeout}s"
+            except httpx.RequestError as e:
+                last_error = f"Request error: {str(e)}"
+            except Exception as e:
+                last_error = f"Unexpected error: {str(e)}"
+
+            # Calculate delay for next attempt
+            if attempt < config.max_retries - 1:
+                delay = min(
+                    config.base_delay * (config.backoff_multiplier**attempt),
+                    config.max_delay,
+                )
+                log.debug(
+                    f"Health check attempt {attempt + 1} failed, retrying in {delay:.1f}s"
+                )
+                time.sleep(delay)
+
+        # All attempts failed
+        return HealthCheckResult(
+            status=HealthStatus.UNHEALTHY,
+            response_time=0.0,
+            error_message=last_error,
+            endpoint=config.endpoints[0] if config.endpoints else None,
+        )
+
+    def verify_health_async(
+        self,
+        service_url: str,
+        api_key: Optional[str] = None,
+        config: Optional[HealthCheckConfig] = None,
+    ) -> HealthCheckResult:
+        """
+        Async version of health verification.
+
+        Args:
+            service_url: Base URL of the service
+            api_key: Optional API key for authenticated endpoints
+            config: Optional configuration override
+
+        Returns:
+            HealthCheckResult with detailed status information
+        """
+        return asyncio.run(self._verify_health_async(service_url, api_key, config))
+
+    async def _verify_health_async(
+        self,
+        service_url: str,
+        api_key: Optional[str] = None,
+        config: Optional[HealthCheckConfig] = None,
+    ) -> HealthCheckResult:
+        """Internal async health verification implementation."""
+        config = config or self.config
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+
+        last_error = None
+        successful_checks = 0
+
+        async with httpx.AsyncClient(timeout=config.timeout) as client:
+            for attempt in range(config.max_retries):
+                start_time = time.time()
+
+                try:
+                    # Check all configured endpoints
+                    if not config.endpoints:
+                        last_error = "No endpoints configured"
+                        continue
+                    all_healthy = True
+                    for endpoint in config.endpoints:
+                        endpoint_url = f"{service_url.rstrip('/')}{endpoint}"
+
+                        response = await client.get(endpoint_url, headers=headers)
+
+                        if response.status_code != 200:
+                            all_healthy = False
+                            last_error = (
+                                f"Endpoint {endpoint} returned {response.status_code}"
+                            )
+                            break
+
+                    if all_healthy:
+                        successful_checks += 1
+                        if successful_checks >= config.success_threshold:
+                            response_time = time.time() - start_time
+                            return HealthCheckResult(
+                                status=HealthStatus.HEALTHY,
+                                response_time=response_time,
+                                status_code=200,
+                                endpoint=config.endpoints[0]
+                                if config.endpoints
+                                else None,
+                            )
+                    else:
+                        last_error = last_error or "One or more endpoints failed"
+
+                except httpx.TimeoutException:
+                    last_error = f"Request timeout after {config.timeout}s"
+                except httpx.RequestError as e:
+                    last_error = f"Request error: {str(e)}"
+                except Exception as e:
+                    last_error = f"Unexpected error: {str(e)}"
+
+                # Calculate delay for next attempt
+                if attempt < config.max_retries - 1:
+                    delay = min(
+                        config.base_delay * (config.backoff_multiplier**attempt),
+                        config.max_delay,
+                    )
+                    log.debug(
+                        f"Health check attempt {attempt + 1} failed, retrying in {delay:.1f}s"
+                    )
+                    await asyncio.sleep(delay)
+
+        # All attempts failed
+        return HealthCheckResult(
+            status=HealthStatus.UNHEALTHY,
+            response_time=0.0,
+            error_message=last_error,
+            endpoint=config.endpoints[0] if config.endpoints else None,
+        )
+
+    def verify_multiple_endpoints(
+        self,
+        service_url: str,
+        endpoints: List[str],
+        api_key: Optional[str] = None,
+        config: Optional[HealthCheckConfig] = None,
+    ) -> Dict[str, HealthCheckResult]:
+        """
+        Verify multiple endpoints and return individual results.
+
+        Args:
+            service_url: Base URL of the service
+            endpoints: List of endpoints to check
+            api_key: Optional API key for authenticated endpoints
+            config: Optional configuration override
+
+        Returns:
+            Dictionary mapping endpoints to their health check results
+        """
+        config = config or self.config
+        config.endpoints = endpoints
+
+        results = {}
+        for endpoint in endpoints:
+            single_endpoint_config = HealthCheckConfig(
+                timeout=config.timeout,
+                max_retries=config.max_retries,
+                base_delay=config.base_delay,
+                max_delay=config.max_delay,
+                backoff_multiplier=config.backoff_multiplier,
+                success_threshold=config.success_threshold,
+                endpoints=[endpoint],
+            )
+
+            results[endpoint] = self.verify_health(
+                service_url, api_key, single_endpoint_config
+            )
+
+        return results
+
+    def get_health_summary(
+        self, results: Dict[str, HealthCheckResult]
+    ) -> Dict[str, Any]:
+        """
+        Generate a summary of health check results.
+
+        Args:
+            results: Dictionary of health check results
+
+        Returns:
+            Summary dictionary with overall status and statistics
+        """
+        total_checks = len(results)
+        healthy_checks = sum(
+            1 for r in results.values() if r.status == HealthStatus.HEALTHY
+        )
+        unhealthy_checks = total_checks - healthy_checks
+
+        avg_response_time = 0.0
+        if healthy_checks > 0:
+            response_times = [
+                r.response_time
+                for r in results.values()
+                if r.status == HealthStatus.HEALTHY
+            ]
+            avg_response_time = sum(response_times) / len(response_times)
+
+        overall_status = (
+            HealthStatus.HEALTHY if unhealthy_checks == 0 else HealthStatus.UNHEALTHY
+        )
+
+        return {
+            "overall_status": overall_status,
+            "total_endpoints": total_checks,
+            "healthy_endpoints": healthy_checks,
+            "unhealthy_endpoints": unhealthy_checks,
+            "success_rate": healthy_checks / total_checks if total_checks > 0 else 0.0,
+            "average_response_time": avg_response_time,
+            "timestamp": time.time(),
+            "details": results,
+        }
+
+
+def verify_service_health(
+    service_url: str,
+    api_key: Optional[str] = None,
+    timeout: int = 60,
+    max_retries: int = 5,
+) -> bool:
+    """
+    Simple health verification function for backward compatibility.
+
+    Args:
+        service_url: Base URL of the service
+        api_key: Optional API key for authenticated endpoints
+        timeout: Request timeout in seconds
+        max_retries: Maximum number of retry attempts
+
+    Returns:
+        True if service is healthy, False otherwise
+    """
+    config = HealthCheckConfig(timeout=timeout, max_retries=max_retries)
+
+    verifier = HealthVerifier(config)
+    result = verifier.verify_health(service_url, api_key)
+
+    return result.status == HealthStatus.HEALTHY
+
+
+def display_health_results(results: Dict[str, HealthCheckResult]) -> None:
+    """
+    Display health check results in a formatted table.
+
+    Args:
+        results: Dictionary of health check results
+    """
+    from rich.table import Table
+
+    table = Table(title="Health Check Results")
+    table.add_column("Endpoint", style="cyan")
+    table.add_column("Status", style="magenta")
+    table.add_column("Response Time", style="green")
+    table.add_column("Status Code", style="blue")
+    table.add_column("Error", style="red")
+
+    for endpoint, result in results.items():
+        status_style = "green" if result.status == HealthStatus.HEALTHY else "red"
+        response_time = (
+            f"{result.response_time:.3f}s" if result.response_time > 0 else "N/A"
+        )
+        status_code = str(result.status_code) if result.status_code else "N/A"
+        error = result.error_message or "None"
+
+        table.add_row(
+            endpoint,
+            f"[{status_style}]{result.status.value}[/]",
+            response_time,
+            status_code,
+            error,
+        )
+
+    console.print(table)

supervaizer/deploy/state.py

@@ -0,0 +1,210 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+"""
+Deployment State Management
+
+This module handles deployment state persistence and management.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from supervaizer.common import log
+
+
+class DeploymentState(BaseModel):
+    """Deployment state model."""
+
+    # Versioning
+    version: int = Field(2, description="State file format version")
+
+    # Service identification
+    service_name: str = Field(..., description="Name of the deployed service")
+    platform: str = Field(
+        ..., description="Target platform (cloud-run|aws-app-runner|do-app-platform)"
+    )
+    environment: str = Field(..., description="Environment (dev|staging|prod)")
+    region: str = Field(..., description="Provider region")
+    project_id: Optional[str] = Field(
+        None, description="GCP project / AWS account / DO project"
+    )
+
+    # Deployment details
+    image_tag: str = Field(..., description="Docker image tag")
+    image_digest: Optional[str] = Field(None, description="Docker image digest")
+    service_url: Optional[str] = Field(None, description="Public service URL")
+    revision: Optional[str] = Field(None, description="Service revision/version")
+
+    # Timestamps
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Deployment creation time",
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Last update time",
+    )
+
+    # Status
+    status: str = Field("unknown", description="Deployment status")
+    health_status: str = Field("unknown", description="Health check status")
+
+    # Configuration
+    port: int = Field(8000, description="Application port")
+    api_key_generated: bool = Field(False, description="Whether API key was generated")
+    rsa_key_generated: bool = Field(False, description="Whether RSA key was generated")
+
+    # Provider-specific data
+    provider_data: Dict[str, Any] = Field(
+        default_factory=dict, description="Platform-specific data"
+    )
+
+
+class StateManager:
+    """Manages deployment state persistence."""
+
+    def __init__(self, deployment_dir: Path) -> None:
+        """Initialize state manager."""
+        self.deployment_dir = deployment_dir
+        self.state_file = deployment_dir / "state.json"
+        self._ensure_deployment_dir()
+
+    def _ensure_deployment_dir(self) -> None:
+        """Ensure deployment directory exists."""
+        self.deployment_dir.mkdir(exist_ok=True)
+
+        # Create logs subdirectory
+        logs_dir = self.deployment_dir / "logs"
+        logs_dir.mkdir(exist_ok=True)
+
+        log.info(f"Deployment directory: {self.deployment_dir}")
+
+    def load_state(self) -> Optional[DeploymentState]:
+        """Load deployment state from file."""
+        if not self.state_file.exists():
+            return None
+
+        try:
+            with open(self.state_file, "r") as f:
+                data = json.load(f)
+
+            # Handle migration
+            data = self.migrate_state(data)
+
+            # Handle datetime deserialization
+            if "created_at" in data:
+                data["created_at"] = datetime.fromisoformat(data["created_at"])
+            if "updated_at" in data:
+                data["updated_at"] = datetime.fromisoformat(data["updated_at"])
+
+            state = DeploymentState(**data)
+            if not self.validate_state(state):
+                return None
+            return state
+
+        except ValueError as e:
+            if "Unsupported state version" in str(e):
+                raise  # Re-raise the specific error for unsupported versions
+            log.error(f"Failed to load or validate deployment state: {e}")
+            return None
+        except (json.JSONDecodeError, KeyError, TypeError) as e:
+            log.error(f"Failed to load or validate deployment state: {e}")
+            return None
+
+    def save_state(self, state: DeploymentState) -> None:
+        """Save deployment state to file."""
+        try:
+            # Update timestamp
+            state.updated_at = datetime.now(timezone.utc)
+
+            # Convert to dict and handle datetime serialization
+            data = state.model_dump()
+            data["created_at"] = state.created_at.isoformat()
+            data["updated_at"] = state.updated_at.isoformat()
+
+            with open(self.state_file, "w") as f:
+                json.dump(data, f, indent=2)
+
+            log.info(f"Saved deployment state to {self.state_file}")
+
+        except (OSError, ValueError) as e:
+            log.error(f"Failed to save deployment state: {e}")
+            raise RuntimeError(f"Failed to save deployment state: {e}") from e
+
+    def update_state(self, **kwargs: Any) -> DeploymentState:
+        """Update deployment state with new values."""
+        current_state = self.load_state()
+
+        if current_state is None:
+            # Create new state if none exists
+            current_state = DeploymentState(**kwargs)
+        else:
+            # Update existing state
+            for key, value in kwargs.items():
+                if hasattr(current_state, key):
+                    setattr(current_state, key, value)
+
+        self.save_state(current_state)
+        return current_state
+
+    def delete_state(self) -> None:
+        """Delete deployment state file."""
+        if self.state_file.exists():
+            self.state_file.unlink()
+            log.info(f"Deleted deployment state file: {self.state_file}")
+
+    def get_service_key(self, service_name: str, environment: str) -> str:
+        """Generate a unique key for the service."""
+        return f"{service_name}-{environment}"
+
+    def validate_state(self, state: DeploymentState) -> bool:
+        """Validate deployment state."""
+        required_fields = ["service_name", "platform", "environment", "image_tag"]
+
+        for field in required_fields:
+            if not getattr(state, field):
+                log.error(f"Missing required field in state: {field}")
+                return False
+
+        # Validate platform
+        valid_platforms = ["cloud-run", "aws-app-runner", "do-app-platform"]
+        if state.platform not in valid_platforms:
+            log.error(f"Invalid platform: {state.platform}")
+            return False
+
+        # Validate environment
+        valid_environments = ["dev", "staging", "prod"]
+        if state.environment not in valid_environments:
+            log.error(f"Invalid environment: {state.environment}")
+            return False
+
+        return True
+
+    def migrate_state(self, state_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Migrate state data from older versions."""
+        version = state_data.get("version", 1)
+        if version > 2:
+            raise ValueError(f"Unsupported state version: {version}")
+
+        migrated_data = state_data.copy()
+
+        if version < 2:
+            log.info("Migrating state from v1 to v2")
+            # Example migration: add new fields with defaults
+            if "api_key_generated" not in migrated_data:
+                migrated_data["api_key_generated"] = False
+            if "rsa_key_generated" not in migrated_data:
+                migrated_data["rsa_key_generated"] = False
+            if "provider_data" not in migrated_data:
+                migrated_data["provider_data"] = {}
+            migrated_data["version"] = 2
+
+        return migrated_data

supervaizer/deploy/templates/Dockerfile.template

@@ -0,0 +1,44 @@
+# Supervaizer Deployment Dockerfile
+FROM ghcr.io/astral-sh/uv:python{{PYTHON_VERSION}}-bookworm AS base
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy only files that affect dependency resolution
+COPY pyproject.toml ./
+# Sync dependencies (uv sync will resolve and install dependencies)
+RUN uv --version &&python --version
+RUN uv sync --no-dev --no-install-project
+# COPY {{CONTROLLER_FILE}} ./
+
+
+
+# Copy entrypoint script
+COPY .deployment/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Now bring in the rest of the source (maximizes cache hits for deps)
+COPY . .
+
+# COPY .deployment/debug_env.py ./debug_env.py
+# Set environment variables
+{{ENV_VARS}}
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/bash supervaizer && \
+    chown -R supervaizer:supervaizer /app && \
+    chown supervaizer:supervaizer /entrypoint.sh
+USER supervaizer
+
+# Expose port
+EXPOSE {{APP_PORT}}
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:{{APP_PORT}}/.well-known/health || exit 1
+
+# Set entrypoint
+ENTRYPOINT ["/entrypoint.sh"]