claude-mpm 4.13.1__py3-none-any.whl → 4.14.0__py3-none-any.whl

claude_mpm/services/local_ops/health_checks/__init__.py

@@ -0,0 +1,28 @@
+"""
+Health Check Implementations for Local Operations
+==================================================
+
+WHY: Provides three-tier health monitoring for local deployments:
+- HTTP health checks for endpoint availability
+- Process health checks for process status
+- Resource health checks for CPU/memory/connections
+
+ARCHITECTURE:
+- HttpHealthCheck: HTTP endpoint availability and response time
+- ProcessHealthCheck: Process existence and status validation
+- ResourceHealthCheck: CPU, memory, and connection monitoring
+"""
+
+from claude_mpm.services.local_ops.health_checks.http_check import HttpHealthCheck
+from claude_mpm.services.local_ops.health_checks.process_check import (
+    ProcessHealthCheck,
+)
+from claude_mpm.services.local_ops.health_checks.resource_check import (
+    ResourceHealthCheck,
+)
+
+__all__ = [
+    "HttpHealthCheck",
+    "ProcessHealthCheck",
+    "ResourceHealthCheck",
+]

claude_mpm/services/local_ops/health_checks/http_check.py

@@ -0,0 +1,223 @@
+"""
+HTTP Health Check for Claude MPM Framework
+===========================================
+
+WHY: Provides HTTP endpoint health monitoring with response time measurement,
+status code validation, and timeout handling.
+
+DESIGN DECISION: Uses requests library with configurable timeout and retry logic.
+Supports custom headers and SSL/TLS validation.
+
+ARCHITECTURE:
+- Synchronous HTTP GET requests
+- Response time measurement with time.perf_counter()
+- Status code validation (2xx/3xx = healthy)
+- Timeout and connection error handling
+- Retry logic with exponential backoff
+
+USAGE:
+    http_check = HttpHealthCheck(process_manager)
+    result = http_check.check(
+        deployment_id="my-app",
+        endpoint="http://localhost:3000/health",
+        timeout=5.0
+    )
+"""
+
+import time
+
+import requests
+from requests.exceptions import ConnectionError, RequestException, Timeout
+
+from claude_mpm.services.core.base import SyncBaseService
+from claude_mpm.services.core.interfaces.health import IHealthCheck
+from claude_mpm.services.core.interfaces.process import ILocalProcessManager
+from claude_mpm.services.core.models.health import HealthCheckResult, HealthStatus
+
+
+class HttpHealthCheck(SyncBaseService, IHealthCheck):
+    """
+    HTTP endpoint health check implementation.
+
+    WHY: Validates that deployed services are accessible via HTTP and
+    responding within acceptable timeframes.
+
+    Thread Safety: Stateless, safe for concurrent execution.
+    """
+
+    def __init__(
+        self,
+        process_manager: ILocalProcessManager,
+        default_timeout: float = 5.0,
+        max_retries: int = 2,
+    ):
+        """
+        Initialize HTTP health check.
+
+        Args:
+            process_manager: Process manager for deployment lookup
+            default_timeout: Default timeout in seconds
+            max_retries: Maximum number of retry attempts
+        """
+        super().__init__("HttpHealthCheck")
+        self.process_manager = process_manager
+        self.default_timeout = default_timeout
+        self.max_retries = max_retries
+
+    def initialize(self) -> bool:
+        """
+        Initialize the health check.
+
+        Returns:
+            True if initialization successful
+        """
+        self._initialized = True
+        self.log_info("HTTP health check initialized")
+        return True
+
+    def shutdown(self) -> None:
+        """Shutdown health check (no resources to clean up)."""
+        self._shutdown = True
+
+    def get_check_type(self) -> str:
+        """Get the check type identifier."""
+        return "http"
+
+    def check(self, deployment_id: str, **kwargs) -> HealthCheckResult:
+        """
+        Execute HTTP health check for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            **kwargs: Optional parameters:
+                - endpoint: HTTP endpoint URL (required)
+                - timeout: Request timeout in seconds (default: 5.0)
+                - headers: Custom HTTP headers
+                - verify_ssl: Verify SSL certificates (default: True)
+                - expected_status: Expected status code (default: 200)
+
+        Returns:
+            HealthCheckResult with check status and details
+
+        Raises:
+            ValueError: If deployment_id not found or endpoint not provided
+        """
+        # Validate deployment exists
+        deployment = self.process_manager.state_manager.get_deployment(deployment_id)
+        if not deployment:
+            raise ValueError(f"Deployment not found: {deployment_id}")
+
+        # Get endpoint from kwargs
+        endpoint = kwargs.get("endpoint")
+        if not endpoint:
+            # Try to construct from deployment port
+            if deployment.port:
+                endpoint = f"http://localhost:{deployment.port}/health"
+            else:
+                return HealthCheckResult(
+                    status=HealthStatus.UNKNOWN,
+                    check_type=self.get_check_type(),
+                    message="No HTTP endpoint configured for deployment",
+                    details={"deployment_id": deployment_id},
+                )
+
+        # Get optional parameters
+        timeout = kwargs.get("timeout", self.default_timeout)
+        headers = kwargs.get("headers", {})
+        verify_ssl = kwargs.get("verify_ssl", True)
+        expected_status = kwargs.get("expected_status", 200)
+
+        # Perform HTTP check with retries
+        for attempt in range(self.max_retries + 1):
+            try:
+                start_time = time.perf_counter()
+                response = requests.get(
+                    endpoint, timeout=timeout, headers=headers, verify=verify_ssl
+                )
+                response_time = time.perf_counter() - start_time
+
+                # Check status code
+                if response.status_code == expected_status or (
+                    200 <= response.status_code < 400
+                ):
+                    return HealthCheckResult(
+                        status=HealthStatus.HEALTHY,
+                        check_type=self.get_check_type(),
+                        message="HTTP endpoint responding normally",
+                        details={
+                            "endpoint": endpoint,
+                            "status_code": response.status_code,
+                            "response_time_ms": round(response_time * 1000, 2),
+                            "attempt": attempt + 1,
+                        },
+                    )
+                return HealthCheckResult(
+                    status=HealthStatus.DEGRADED,
+                    check_type=self.get_check_type(),
+                    message="HTTP endpoint returned unexpected status code",
+                    details={
+                        "endpoint": endpoint,
+                        "status_code": response.status_code,
+                        "expected_status": expected_status,
+                        "response_time_ms": round(response_time * 1000, 2),
+                    },
+                )
+
+            except Timeout:
+                if attempt < self.max_retries:
+                    self.log_debug(
+                        f"HTTP check timeout for {deployment_id}, "
+                        f"retrying (attempt {attempt + 1}/{self.max_retries})"
+                    )
+                    time.sleep(0.5 * (2**attempt))  # Exponential backoff
+                    continue
+
+                return HealthCheckResult(
+                    status=HealthStatus.DEGRADED,
+                    check_type=self.get_check_type(),
+                    message=f"HTTP endpoint timeout after {self.max_retries + 1} attempts",
+                    details={
+                        "endpoint": endpoint,
+                        "timeout_seconds": timeout,
+                        "attempts": self.max_retries + 1,
+                    },
+                )
+
+            except ConnectionError as e:
+                if attempt < self.max_retries:
+                    self.log_debug(
+                        f"HTTP connection error for {deployment_id}, "
+                        f"retrying (attempt {attempt + 1}/{self.max_retries})"
+                    )
+                    time.sleep(0.5 * (2**attempt))  # Exponential backoff
+                    continue
+
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    check_type=self.get_check_type(),
+                    message="Cannot connect to HTTP endpoint",
+                    details={
+                        "endpoint": endpoint,
+                        "error": str(e),
+                        "attempts": self.max_retries + 1,
+                    },
+                )
+
+            except RequestException as e:
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    check_type=self.get_check_type(),
+                    message="HTTP request failed",
+                    details={"endpoint": endpoint, "error": str(e)},
+                )
+
+        # Should not reach here, but return unknown as fallback
+        return HealthCheckResult(
+            status=HealthStatus.UNKNOWN,
+            check_type=self.get_check_type(),
+            message="HTTP check completed with unknown result",
+            details={"endpoint": endpoint},
+        )
+
+
+__all__ = ["HttpHealthCheck"]

claude_mpm/services/local_ops/health_checks/process_check.py

@@ -0,0 +1,235 @@
+"""
+Process Health Check for Claude MPM Framework
+==============================================
+
+WHY: Provides process-level health monitoring including existence validation,
+status checking (running/zombie/stopped), and exit code detection.
+
+DESIGN DECISION: Uses psutil for cross-platform process monitoring. Validates
+process existence, status, and parent-child relationships.
+
+ARCHITECTURE:
+- Process existence verification with psutil.Process(pid)
+- Process status checking (running, zombie, stopped, sleeping)
+- Exit code detection for dead processes
+- Parent-child relationship validation
+- Process responsiveness checking (not hung)
+
+USAGE:
+    process_check = ProcessHealthCheck(process_manager)
+    result = process_check.check(deployment_id="my-app")
+"""
+
+import psutil
+
+from claude_mpm.services.core.base import SyncBaseService
+from claude_mpm.services.core.interfaces.health import IHealthCheck
+from claude_mpm.services.core.interfaces.process import ILocalProcessManager
+from claude_mpm.services.core.models.health import HealthCheckResult, HealthStatus
+
+
+class ProcessHealthCheck(SyncBaseService, IHealthCheck):
+    """
+    Process status health check implementation.
+
+    WHY: Validates that the process is running properly and not in a
+    degraded state (zombie, stopped, etc.).
+
+    Thread Safety: Stateless, safe for concurrent execution.
+    """
+
+    def __init__(self, process_manager: ILocalProcessManager):
+        """
+        Initialize process health check.
+
+        Args:
+            process_manager: Process manager for deployment lookup
+        """
+        super().__init__("ProcessHealthCheck")
+        self.process_manager = process_manager
+
+    def initialize(self) -> bool:
+        """
+        Initialize the health check.
+
+        Returns:
+            True if initialization successful
+        """
+        self._initialized = True
+        self.log_info("Process health check initialized")
+        return True
+
+    def shutdown(self) -> None:
+        """Shutdown health check (no resources to clean up)."""
+        self._shutdown = True
+
+    def get_check_type(self) -> str:
+        """Get the check type identifier."""
+        return "process"
+
+    def check(self, deployment_id: str, **kwargs) -> HealthCheckResult:
+        """
+        Execute process health check for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            **kwargs: Optional parameters:
+                - check_responsiveness: Check if process is responsive (default: True)
+
+        Returns:
+            HealthCheckResult with check status and details
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+        # Validate deployment exists
+        deployment = self.process_manager.state_manager.get_deployment(deployment_id)
+        if not deployment:
+            raise ValueError(f"Deployment not found: {deployment_id}")
+
+        check_responsiveness = kwargs.get("check_responsiveness", True)
+
+        try:
+            process = psutil.Process(deployment.process_id)
+
+            # Check if process exists and is running
+            if not process.is_running():
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    check_type=self.get_check_type(),
+                    message="Process is not running",
+                    details={
+                        "pid": deployment.process_id,
+                        "deployment_id": deployment_id,
+                    },
+                )
+
+            # Get process status
+            process_status = process.status()
+
+            # Check for zombie process
+            if process_status == psutil.STATUS_ZOMBIE:
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    check_type=self.get_check_type(),
+                    message="Process is a zombie",
+                    details={
+                        "pid": deployment.process_id,
+                        "status": process_status,
+                        "deployment_id": deployment_id,
+                    },
+                )
+
+            # Check for stopped process
+            if process_status in (psutil.STATUS_STOPPED, psutil.STATUS_DEAD):
+                return HealthCheckResult(
+                    status=HealthStatus.UNHEALTHY,
+                    check_type=self.get_check_type(),
+                    message=f"Process is {process_status}",
+                    details={
+                        "pid": deployment.process_id,
+                        "status": process_status,
+                        "deployment_id": deployment_id,
+                    },
+                )
+
+            # Check responsiveness (CPU activity)
+            if check_responsiveness:
+                try:
+                    cpu_percent = process.cpu_percent(interval=0.1)
+                    # Process should have some CPU activity or be idle/sleeping
+                    # A process with 0% CPU for extended periods might be hung
+                    is_responsive = cpu_percent > 0 or process_status in (
+                        psutil.STATUS_SLEEPING,
+                        psutil.STATUS_IDLE,
+                    )
+
+                    if not is_responsive:
+                        return HealthCheckResult(
+                            status=HealthStatus.DEGRADED,
+                            check_type=self.get_check_type(),
+                            message="Process may be unresponsive",
+                            details={
+                                "pid": deployment.process_id,
+                                "status": process_status,
+                                "cpu_percent": cpu_percent,
+                                "deployment_id": deployment_id,
+                            },
+                        )
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    # Process disappeared or we lost access during check
+                    return HealthCheckResult(
+                        status=HealthStatus.UNHEALTHY,
+                        check_type=self.get_check_type(),
+                        message="Process disappeared during check",
+                        details={
+                            "pid": deployment.process_id,
+                            "deployment_id": deployment_id,
+                        },
+                    )
+
+            # Process is healthy
+            # Get additional process info for details
+            try:
+                process_info = {
+                    "pid": deployment.process_id,
+                    "status": process_status,
+                    "deployment_id": deployment_id,
+                    "name": process.name(),
+                    "num_threads": process.num_threads(),
+                }
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                process_info = {
+                    "pid": deployment.process_id,
+                    "status": process_status,
+                    "deployment_id": deployment_id,
+                }
+
+            return HealthCheckResult(
+                status=HealthStatus.HEALTHY,
+                check_type=self.get_check_type(),
+                message="Process is running normally",
+                details=process_info,
+            )
+
+        except psutil.NoSuchProcess:
+            # Process does not exist
+            return HealthCheckResult(
+                status=HealthStatus.UNHEALTHY,
+                check_type=self.get_check_type(),
+                message="Process no longer exists",
+                details={
+                    "pid": deployment.process_id,
+                    "deployment_id": deployment_id,
+                },
+            )
+
+        except psutil.AccessDenied as e:
+            # Cannot access process information
+            return HealthCheckResult(
+                status=HealthStatus.UNKNOWN,
+                check_type=self.get_check_type(),
+                message="Cannot access process information",
+                details={
+                    "pid": deployment.process_id,
+                    "deployment_id": deployment_id,
+                    "error": str(e),
+                },
+            )
+
+        except Exception as e:
+            # Unexpected error
+            self.log_error(f"Unexpected error in process health check: {e}")
+            return HealthCheckResult(
+                status=HealthStatus.UNKNOWN,
+                check_type=self.get_check_type(),
+                message="Health check failed with error",
+                details={
+                    "pid": deployment.process_id,
+                    "deployment_id": deployment_id,
+                    "error": str(e),
+                },
+            )
+
+
+__all__ = ["ProcessHealthCheck"]