mcp-mesh 0.7.21__py3-none-any.whl → 0.8.0__py3-none-any.whl

_mcp_mesh/pipeline/api_heartbeat/api_heartbeat_orchestrator.py

@@ -1,243 +0,0 @@
-"""
-API heartbeat orchestrator for managing periodic pipeline execution.
-
-Provides a high-level interface for executing API heartbeat pipelines 
-with proper context management and error handling for FastAPI services.
-"""
-
-import json
-import logging
-from datetime import UTC, datetime
-from typing import Any, Dict, Optional
-
-from .api_heartbeat_pipeline import APIHeartbeatPipeline
-
-logger = logging.getLogger(__name__)
-
-
-class APIHeartbeatOrchestrator:
-    """
-    Orchestrates API heartbeat pipeline execution for periodic registry communication.
-
-    Manages the context preparation, pipeline execution, and result processing
-    for the periodic heartbeat cycle of FastAPI services using @mesh.route decorators.
-    """
-
-    def __init__(self):
-        self.logger = logging.getLogger(f"{__name__}.APIHeartbeatOrchestrator")
-        self.pipeline = APIHeartbeatPipeline()
-        self._heartbeat_count = 0
-
-    async def execute_api_heartbeat(
-        self, service_id: str, context: dict[str, Any]
-    ) -> bool:
-        """
-        Execute a complete API heartbeat cycle with comprehensive error handling.
-
-        Args:
-            service_id: Service identifier for the FastAPI application
-            context: Full pipeline context from API startup
-
-        Returns:
-            bool: True if heartbeat succeeded, False if failed
-        """
-        self._heartbeat_count += 1
-
-        try:
-            # Prepare heartbeat context with validation
-            heartbeat_context = self._prepare_api_heartbeat_context(service_id, context)
-
-            # Validate required context before proceeding
-            if not self._validate_api_heartbeat_context(heartbeat_context):
-                self.logger.error(
-                    f"❌ API heartbeat #{self._heartbeat_count} failed: invalid context"
-                )
-                return False
-
-            # Log heartbeat request details for debugging
-            self._log_api_heartbeat_request(heartbeat_context, self._heartbeat_count)
-
-            # Execute API heartbeat pipeline with timeout protection
-            self.logger.trace(f"💓 Executing API heartbeat #{self._heartbeat_count} for service '{service_id}'")
-
-            # Add timeout to prevent hanging heartbeats (30 seconds max)
-            import asyncio
-
-            try:
-                self.logger.trace("Starting API heartbeat pipeline execution")
-                result = await asyncio.wait_for(
-                    self.pipeline.execute_api_heartbeat_cycle(heartbeat_context),
-                    timeout=30.0,
-                )
-                if result.is_success():
-                    self.logger.trace("✅ API heartbeat pipeline completed successfully")
-                else:
-                    self.logger.error(f"❌ API heartbeat pipeline failed: {result.message}")
-            except TimeoutError:
-                self.logger.error(
-                    f"❌ API heartbeat #{self._heartbeat_count} timed out after 30 seconds"
-                )
-                return False
-            except Exception as e:
-                self.logger.error(f"❌ [DEBUG] Pipeline execution exception: {e}")
-                import traceback
-                self.logger.error(f"❌ [DEBUG] Traceback: {traceback.format_exc()}")
-                return False
-
-            # Process results
-            success = self._process_api_heartbeat_result(
-                result, service_id, self._heartbeat_count
-            )
-
-            # Log periodic status updates
-            if self._heartbeat_count % 10 == 0:
-                elapsed_time = self._heartbeat_count * 5  # Using 5s interval (MeshDefaults.HEALTH_INTERVAL)
-                self.logger.info(
-                    f"💓 API heartbeat #{self._heartbeat_count} for service '{service_id}' - "
-                    f"running for {elapsed_time} seconds"
-                )
-
-            return success
-
-        except Exception as e:
-            # Log detailed error information for debugging
-            import traceback
-
-            self.logger.error(
-                f"❌ API heartbeat #{self._heartbeat_count} failed for service '{service_id}': {e}\n"
-                f"Traceback: {traceback.format_exc()}"
-            )
-            return False
-
-    def _prepare_api_heartbeat_context(
-        self, service_id: str, startup_context: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Prepare context for API heartbeat pipeline execution."""
-
-        # Get FastAPI app and other essential components from startup context
-        fastapi_app = startup_context.get("fastapi_app")
-        display_config = startup_context.get("display_config", {})
-        
-        # Get API service metadata from startup context
-        api_service_metadata = startup_context.get("api_service_metadata", {})
-        
-        # Build heartbeat-specific context
-        heartbeat_context = {
-            "service_id": service_id,
-            "agent_id": service_id,  # For compatibility with registry calls
-            "fastapi_app": fastapi_app,
-            "display_config": display_config,
-            # Include registry and configuration from startup
-            "agent_config": startup_context.get("agent_config", {}),
-            "registration_data": startup_context.get("registration_data", {}),
-            "registry_wrapper": startup_context.get("registry_wrapper"),
-            # CRITICAL: Include API service metadata with route dependencies
-            "api_service_metadata": api_service_metadata,
-        }
-
-        return heartbeat_context
-
-    def _validate_api_heartbeat_context(self, heartbeat_context: dict[str, Any]) -> bool:
-        """Validate that API heartbeat context has all required components."""
-
-        required_fields = ["service_id", "fastapi_app"]
-
-        for field in required_fields:
-            if field not in heartbeat_context or heartbeat_context[field] is None:
-                self.logger.error(
-                    f"❌ API heartbeat context validation failed: missing '{field}'"
-                )
-                return False
-
-        # Additional validation for FastAPI app
-        fastapi_app = heartbeat_context.get("fastapi_app")
-        if not hasattr(fastapi_app, "routes"):
-            self.logger.error(
-                "❌ API heartbeat context validation failed: invalid FastAPI app object"
-            )
-            return False
-
-        return True
-
-    def _log_api_heartbeat_request(
-        self, heartbeat_context: dict[str, Any], heartbeat_count: int
-    ) -> None:
-        """Log API heartbeat request details for debugging."""
-
-        service_id = heartbeat_context.get("service_id", "unknown")
-        fastapi_app = heartbeat_context.get("fastapi_app")
-        display_config = heartbeat_context.get("display_config", {})
-
-        # Extract app information for logging
-        app_info = {}
-        if fastapi_app:
-            app_info = {
-                "title": getattr(fastapi_app, "title", "Unknown API"),
-                "version": getattr(fastapi_app, "version", "1.0.0"),
-                "routes_count": len(getattr(fastapi_app, "routes", [])),
-            }
-
-        # Log heartbeat details
-        self.logger.trace(
-            f"🔍 API Heartbeat #{heartbeat_count} for '{service_id}': "
-            f"app={app_info}, display={display_config}"
-        )
-
-    def _process_api_heartbeat_result(
-        self, result: Any, service_id: str, heartbeat_count: int
-    ) -> bool:
-        """Process API heartbeat pipeline result and log appropriately."""
-
-        if result.is_success():
-            # Check for heartbeat response in result context
-            heartbeat_response = result.context.get("heartbeat_response")
-            heartbeat_success = result.context.get("heartbeat_success", False)
-            
-            self.logger.trace(f"API heartbeat result - success: {heartbeat_success}")
-
-            # Check if heartbeat was skipped due to optimization
-            heartbeat_skipped = result.context.get("heartbeat_skipped", False)
-            skip_reason = result.context.get("skip_reason")
-            
-            if heartbeat_success and heartbeat_response:
-                # Log response details for tracing
-                try:
-                    response_json = json.dumps(
-                        heartbeat_response, indent=2, default=str
-                    )
-                    self.logger.trace(
-                        f"🔍 API heartbeat response #{heartbeat_count}:\n{response_json}"
-                    )
-                except Exception as e:
-                    self.logger.trace(
-                        f"🔍 API heartbeat response #{heartbeat_count}: {heartbeat_response} "
-                        f"(json serialization failed: {e})"
-                    )
-
-                self.logger.debug(
-                    f"🚀 API heartbeat #{heartbeat_count} sent for service '{service_id}'"
-                )
-                return True
-            elif heartbeat_success and heartbeat_skipped:
-                # Heartbeat was skipped for optimization - this is success
-                self.logger.debug(
-                    f"🚀 API heartbeat #{heartbeat_count} skipped for service '{service_id}' - {skip_reason}"
-                )
-                return True
-            else:
-                self.logger.warning(
-                    f"💔 [UPDATED] API heartbeat #{heartbeat_count} failed for service '{service_id}' - "
-                    f"no response or unsuccessful (heartbeat_success={heartbeat_success}, heartbeat_response={heartbeat_response})"
-                )
-                return False
-        else:
-            self.logger.warning(
-                f"💔 [UPDATED-PIPELINE] API heartbeat #{heartbeat_count} pipeline failed for service '{service_id}': {result.message}"
-            )
-            
-            # Log detailed errors
-            if hasattr(result, 'errors') and result.errors:
-                for error in result.errors:
-                    self.logger.warning(f"  - API heartbeat error: {error}")
-                    
-            return False

_mcp_mesh/pipeline/api_heartbeat/api_heartbeat_pipeline.py

@@ -1,311 +0,0 @@
-"""
-API heartbeat pipeline for FastAPI service health monitoring.
-
-Provides structured execution of API service heartbeat operations with proper
-error handling and logging. Runs periodically to maintain registry communication
-and service health status for FastAPI applications using @mesh.route decorators.
-"""
-
-import logging
-from typing import Any
-
-from ...shared.fast_heartbeat_status import FastHeartbeatStatus, FastHeartbeatStatusUtil
-from ..shared.mesh_pipeline import MeshPipeline
-from ..shared.pipeline_types import PipelineStatus
-from .api_dependency_resolution import APIDependencyResolutionStep
-from .api_fast_heartbeat_check import APIFastHeartbeatStep
-from .api_health_check import APIHealthCheckStep
-from .api_heartbeat_send import APIHeartbeatSendStep
-from .api_registry_connection import APIRegistryConnectionStep
-
-logger = logging.getLogger(__name__)
-
-
-class APIHeartbeatPipeline(MeshPipeline):
-    """
-    Specialized pipeline for API service heartbeat operations with fast optimization.
-
-    Executes the core API heartbeat steps in sequence:
-    1. Registry connection preparation
-    2. API health check (validate FastAPI app status)
-    3. Fast heartbeat check (HEAD request)
-    4. Heartbeat sending (conditional POST request)
-    5. Dependency resolution (conditional)
-
-    Steps 4 and 5 only run if fast heartbeat indicates changes are needed.
-    Provides optimization for NO_CHANGES and resilience for error conditions.
-
-    API services now support:
-    - Service availability and health status monitoring
-    - Efficient HEAD->conditional POST pattern (like MCP agents)
-    - Dynamic dependency resolution and injection
-    - Route handler dependency updates from registry responses
-    """
-
-    def __init__(self, name: str = "api-heartbeat-pipeline"):
-        super().__init__(name=name)
-        self._setup_api_heartbeat_steps()
-
-    def _setup_api_heartbeat_steps(self) -> None:
-        """Setup the API heartbeat pipeline steps with fast optimization."""
-        # API heartbeat steps with fast optimization pattern
-        steps = [
-            APIRegistryConnectionStep(),  # Prepare registry communication
-            APIHealthCheckStep(),  # Check FastAPI app health status
-            APIFastHeartbeatStep(),  # Fast heartbeat check (HEAD request)
-            APIHeartbeatSendStep(),  # Conditional heartbeat send (POST request)
-            APIDependencyResolutionStep(),  # Conditional dependency resolution
-        ]
-
-        self.add_steps(steps)
-        self.logger.trace(f"API heartbeat pipeline configured with {len(steps)} steps")
-
-        # Log the pipeline strategy
-        self.logger.info(
-            "🌐 API Heartbeat Pipeline initialized: fast optimization for FastAPI apps"
-        )
-        self.logger.trace(f"📋 Pipeline steps: {[step.name for step in steps]}")
-
-    async def execute_api_heartbeat_cycle(
-        self, heartbeat_context: dict[str, Any]
-    ) -> Any:
-        """
-        Execute a complete API heartbeat cycle with fast optimization and enhanced error handling.
-
-        Args:
-            heartbeat_context: Context containing registry_wrapper, service_id,
-                              health_status, fastapi_app, etc.
-
-        Returns:
-            PipelineResult with execution status and any context updates
-        """
-        self.logger.trace("Starting API heartbeat pipeline execution")
-
-        # Initialize pipeline context with heartbeat-specific data
-        self.context.clear()
-        self.context.update(heartbeat_context)
-
-        try:
-            # Execute the pipeline with conditional logic for fast optimization
-            result = await self._execute_with_conditional_logic()
-
-            if result.is_success():
-                self.logger.trace("✅ API heartbeat pipeline completed successfully")
-            elif result.status == PipelineStatus.PARTIAL:
-                self.logger.warning(
-                    f"⚠️ API heartbeat pipeline completed partially: {result.message}"
-                )
-                # Log which steps failed
-                if result.errors:
-                    for error in result.errors:
-                        self.logger.warning(f"  - Step error: {error}")
-            else:
-                self.logger.error(f"❌ API heartbeat pipeline failed: {result.message}")
-                # Log detailed error information
-                if result.errors:
-                    for error in result.errors:
-                        self.logger.error(f"  - Pipeline error: {error}")
-
-            return result
-
-        except Exception as e:
-            # Log detailed error information for debugging
-            import traceback
-
-            self.logger.error(
-                f"❌ API heartbeat pipeline failed with exception: {e}\n"
-                f"Context keys: {list(self.context.keys())}\n"
-                f"Traceback: {traceback.format_exc()}"
-            )
-
-            # Create failure result with detailed context
-            from ..shared.pipeline_types import PipelineResult
-
-            failure_result = PipelineResult(
-                status=PipelineStatus.FAILED,
-                message=f"API heartbeat pipeline exception: {str(e)[:200]}...",
-                context=self.context,
-            )
-            failure_result.add_error(str(e))
-
-            return failure_result
-
-    async def _execute_with_conditional_logic(self) -> "PipelineResult":
-        """
-        Execute API pipeline with conditional logic based on fast heartbeat status.
-
-        Always executes:
-        - APIRegistryConnectionStep
-        - APIHealthCheckStep
-        - APIFastHeartbeatStep
-
-        Conditionally executes based on fast heartbeat status:
-        - NO_CHANGES: Skip remaining steps (optimization)
-        - TOPOLOGY_CHANGED, AGENT_UNKNOWN: Execute all remaining steps
-        - REGISTRY_ERROR, NETWORK_ERROR: Skip remaining steps (resilience)
-
-        Returns:
-            PipelineResult with execution status and context
-        """
-        from ..shared.pipeline_types import PipelineResult
-
-        overall_result = PipelineResult(
-            message="API heartbeat pipeline execution completed"
-        )
-
-        # Track which steps were executed for logging
-        executed_steps = []
-        skipped_steps = []
-
-        try:
-            # Always execute registry connection, health check, and fast heartbeat steps
-            mandatory_steps = self.steps[
-                :3
-            ]  # APIRegistryConnectionStep, APIHealthCheckStep, APIFastHeartbeatStep
-            conditional_steps = self.steps[
-                3:
-            ]  # APIHeartbeatSendStep, APIDependencyResolutionStep
-
-            # Execute mandatory steps
-            for step in mandatory_steps:
-                self.logger.trace(f"Executing mandatory step: {step.name}")
-
-                step_result = await step.execute(self.context)
-                executed_steps.append(step.name)
-
-                # Merge step context into pipeline context
-                self.context.update(step_result.context)
-
-                # If step fails, handle accordingly
-                if not step_result.is_success():
-                    overall_result.status = PipelineStatus.FAILED
-                    overall_result.message = (
-                        f"Mandatory step '{step.name}' failed: {step_result.message}"
-                    )
-                    overall_result.add_error(
-                        f"Step '{step.name}': {step_result.message}"
-                    )
-
-                    if step.required:
-                        # Stop execution if required step fails
-                        for key, value in self.context.items():
-                            overall_result.add_context(key, value)
-                        return overall_result
-
-            # Check fast heartbeat status for conditional execution
-            fast_heartbeat_status = self.context.get("fast_heartbeat_status")
-
-            if fast_heartbeat_status is None:
-                # Fast heartbeat step failed to set status - fallback to full execution
-                self.logger.warning(
-                    "⚠️ API fast heartbeat status not found - falling back to full execution"
-                )
-                should_execute_remaining = True
-                reason = "fallback (missing status)"
-            elif FastHeartbeatStatusUtil.should_skip_for_optimization(
-                fast_heartbeat_status
-            ):
-                # NO_CHANGES - skip for optimization
-                should_execute_remaining = False
-                reason = "optimization (no changes detected)"
-                self.logger.trace(
-                    f"🚀 API heartbeat: Skipping remaining steps for optimization: {reason}"
-                )
-            elif FastHeartbeatStatusUtil.should_skip_for_resilience(
-                fast_heartbeat_status
-            ):
-                # REGISTRY_ERROR, NETWORK_ERROR - skip for resilience
-                should_execute_remaining = False
-                reason = "resilience (preserve existing state)"
-                self.logger.warning(
-                    f"⚠️ API heartbeat: Skipping remaining steps for resilience: {reason}"
-                )
-            elif FastHeartbeatStatusUtil.requires_full_heartbeat(fast_heartbeat_status):
-                # TOPOLOGY_CHANGED, AGENT_UNKNOWN - execute full pipeline
-                should_execute_remaining = True
-                reason = "changes detected or re-registration needed"
-                self.logger.info(
-                    f"🔄 API heartbeat: Executing remaining steps: {reason}"
-                )
-            else:
-                # Unknown status - fallback to full execution
-                self.logger.warning(
-                    f"⚠️ Unknown API fast heartbeat status '{fast_heartbeat_status}' - falling back to full execution"
-                )
-                should_execute_remaining = True
-                reason = "fallback (unknown status)"
-
-            # Execute or skip conditional steps based on decision
-            if should_execute_remaining:
-                for step in conditional_steps:
-                    self.logger.trace(f"Executing conditional step: {step.name}")
-
-                    step_result = await step.execute(self.context)
-                    executed_steps.append(step.name)
-
-                    # Merge step context into pipeline context
-                    self.context.update(step_result.context)
-
-                    # Handle step failure
-                    if not step_result.is_success():
-                        if step.required:
-                            overall_result.status = PipelineStatus.FAILED
-                            overall_result.message = f"Required step '{step.name}' failed: {step_result.message}"
-                            overall_result.add_error(
-                                f"Step '{step.name}': {step_result.message}"
-                            )
-                            break
-                        else:
-                            # Optional step failed - mark as partial success
-                            if overall_result.status == PipelineStatus.SUCCESS:
-                                overall_result.status = PipelineStatus.PARTIAL
-                            overall_result.add_error(
-                                f"Optional step '{step.name}': {step_result.message}"
-                            )
-                            self.logger.warning(
-                                f"⚠️ Optional step '{step.name}' failed: {step_result.message}"
-                            )
-            else:
-                # Mark skipped steps
-                for step in conditional_steps:
-                    skipped_steps.append(step.name)
-
-                # For skipped heartbeat due to NO_CHANGES, set success context
-                if fast_heartbeat_status == FastHeartbeatStatus.NO_CHANGES:
-                    overall_result.add_context("heartbeat_success", True)
-                    overall_result.add_context("heartbeat_skipped", True)
-                    overall_result.add_context("skip_reason", "no_changes_optimization")
-
-            # Set final result message
-            if executed_steps and skipped_steps:
-                overall_result.message = (
-                    f"API pipeline completed with conditional execution - "
-                    f"executed: {executed_steps}, skipped: {skipped_steps} ({reason})"
-                )
-            elif executed_steps:
-                overall_result.message = (
-                    f"API pipeline completed - executed: {executed_steps} ({reason})"
-                )
-            else:
-                overall_result.message = (
-                    f"API pipeline completed - all steps skipped ({reason})"
-                )
-
-            # Add final context
-            for key, value in self.context.items():
-                overall_result.add_context(key, value)
-
-            return overall_result
-
-        except Exception as e:
-            # Handle unexpected exceptions
-            overall_result.status = PipelineStatus.FAILED
-            overall_result.message = (
-                f"API pipeline execution failed with exception: {e}"
-            )
-            overall_result.add_error(str(e))
-            for key, value in self.context.items():
-                overall_result.add_context(key, value)
-
-            self.logger.error(f"❌ API conditional pipeline execution failed: {e}")
-            return overall_result