mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/application/commands/handlers.py

@@ -0,0 +1,189 @@
+"""Command handlers implementation."""
+
+import time
+from typing import Any, Dict, List
+
+from ...domain.contracts.provider_runtime import ProviderRuntime
+from ...domain.exceptions import ProviderNotFoundError
+from ...domain.repository import IProviderRepository
+from ...infrastructure.command_bus import CommandBus, CommandHandler
+from ...infrastructure.event_bus import EventBus
+from ...logging_config import get_logger
+from ...metrics import observe_tool_call, record_error, record_provider_start, record_provider_stop
+from .commands import (
+    HealthCheckCommand,
+    InvokeToolCommand,
+    ShutdownIdleProvidersCommand,
+    StartProviderCommand,
+    StopProviderCommand,
+)
+
+logger = get_logger(__name__)
+
+
+class BaseProviderHandler(CommandHandler):
+    """Base class for handlers that work with providers."""
+
+    def __init__(self, repository: IProviderRepository, event_bus: EventBus):
+        self._repository = repository
+        self._event_bus = event_bus
+
+    def _get_provider(self, provider_id: str) -> ProviderRuntime:
+        """Get provider or raise domain ProviderNotFoundError."""
+        provider = self._repository.get(provider_id)
+        if provider is None:
+            raise ProviderNotFoundError(provider_id)
+        return provider
+
+    def _publish_events(self, provider: ProviderRuntime) -> None:
+        """Publish collected events from provider (no duck typing)."""
+        for event in provider.collect_events():
+            try:
+                self._event_bus.publish(event)
+            except (RuntimeError, ValueError, TypeError) as e:
+                logger.error(
+                    "event_publish_failed",
+                    event_type=type(event).__name__,
+                    error=str(e),
+                    exc_info=True,
+                )
+
+
+class StartProviderHandler(BaseProviderHandler):
+    """Handler for StartProviderCommand."""
+
+    def handle(self, command: StartProviderCommand) -> Dict[str, Any]:
+        """
+        Start a provider.
+
+        Returns:
+            Dict with provider state and tools
+        """
+        provider = self._get_provider(command.provider_id)
+        try:
+            provider.ensure_ready()
+            record_provider_start(command.provider_id, success=True)
+        except Exception as e:
+            record_provider_start(command.provider_id, success=False)
+            record_error("provider", type(e).__name__)
+            raise
+        finally:
+            self._publish_events(provider)
+
+        return {
+            "provider": command.provider_id,
+            "state": provider.state.value,
+            "tools": provider.get_tool_names(),
+        }
+
+
+class StopProviderHandler(BaseProviderHandler):
+    """Handler for StopProviderCommand."""
+
+    def handle(self, command: StopProviderCommand) -> Dict[str, Any]:
+        """
+        Stop a provider.
+
+        Returns:
+            Confirmation dict
+        """
+        provider = self._get_provider(command.provider_id)
+        provider.shutdown()
+        record_provider_stop(command.provider_id, reason=command.reason or "manual")
+        self._publish_events(provider)
+
+        return {"stopped": command.provider_id, "reason": command.reason}
+
+
+class InvokeToolHandler(BaseProviderHandler):
+    """Handler for InvokeToolCommand."""
+
+    def handle(self, command: InvokeToolCommand) -> Dict[str, Any]:
+        """
+        Invoke a tool on a provider.
+
+        Returns:
+            Tool result
+        """
+        provider = self._get_provider(command.provider_id)
+
+        start_time = time.perf_counter()
+        error_type = None
+        success = False
+
+        try:
+            result = provider.invoke_tool(command.tool_name, command.arguments, command.timeout)
+            success = True
+            return result
+
+        except Exception as e:
+            error_type = type(e).__name__
+            raise
+
+        finally:
+            duration = time.perf_counter() - start_time
+            observe_tool_call(
+                provider=command.provider_id,
+                tool=command.tool_name,
+                duration=duration,
+                success=success,
+                error_type=error_type,
+            )
+            self._publish_events(provider)
+
+
+class HealthCheckHandler(BaseProviderHandler):
+    """Handler for HealthCheckCommand."""
+
+    def handle(self, command: HealthCheckCommand) -> bool:
+        """
+        Perform health check on a provider.
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        provider = self._get_provider(command.provider_id)
+        result = provider.health_check()
+        self._publish_events(provider)
+
+        return result
+
+
+class ShutdownIdleProvidersHandler(BaseProviderHandler):
+    """Handler for ShutdownIdleProvidersCommand."""
+
+    def handle(self, command: ShutdownIdleProvidersCommand) -> List[str]:
+        """
+        Shutdown all idle providers.
+
+        Returns:
+            List of provider IDs that were shutdown
+        """
+        shutdown_ids = []
+        for provider_id, provider in self._repository.get_all().items():
+            if provider.maybe_shutdown_idle():
+                shutdown_ids.append(provider_id)
+                self._publish_events(provider)
+
+        return shutdown_ids
+
+
+def register_all_handlers(command_bus: CommandBus, repository: IProviderRepository, event_bus: EventBus) -> None:
+    """
+    Register all command handlers with the command bus.
+
+    Args:
+        command_bus: The command bus to register handlers with
+        repository: Provider repository
+        event_bus: Event bus for publishing events
+    """
+    command_bus.register(StartProviderCommand, StartProviderHandler(repository, event_bus))
+    command_bus.register(StopProviderCommand, StopProviderHandler(repository, event_bus))
+    command_bus.register(InvokeToolCommand, InvokeToolHandler(repository, event_bus))
+    command_bus.register(HealthCheckCommand, HealthCheckHandler(repository, event_bus))
+    command_bus.register(
+        ShutdownIdleProvidersCommand,
+        ShutdownIdleProvidersHandler(repository, event_bus),
+    )
+
+    logger.info("command_handlers_registered")

mcp_hangar/application/discovery/__init__.py

@@ -0,0 +1,21 @@
+"""Discovery application module.
+
+This module contains application layer components for provider discovery,
+including the orchestrator, security validation, and metrics.
+"""
+
+from .discovery_metrics import DiscoveryMetrics
+from .discovery_orchestrator import DiscoveryConfig, DiscoveryOrchestrator
+from .lifecycle_manager import DiscoveryLifecycleManager
+from .security_validator import SecurityConfig, SecurityValidator, ValidationReport, ValidationResult
+
+__all__ = [
+    "DiscoveryOrchestrator",
+    "DiscoveryConfig",
+    "SecurityValidator",
+    "SecurityConfig",
+    "ValidationResult",
+    "ValidationReport",
+    "DiscoveryMetrics",
+    "DiscoveryLifecycleManager",
+]

mcp_hangar/application/discovery/discovery_metrics.py

@@ -0,0 +1,283 @@
+"""Discovery Metrics.
+
+Prometheus metrics for provider discovery observability.
+Tracks discovery cycles, registrations, conflicts, and validation times.
+"""
+
+from functools import wraps
+import time
+from typing import Callable
+
+from ...logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Optional prometheus dependency
+try:
+    from prometheus_client import Counter, Gauge, Histogram
+
+    PROMETHEUS_AVAILABLE = True
+except ImportError:
+    PROMETHEUS_AVAILABLE = False
+    # Note: No logging here - module is imported before setup_logging() is called
+
+
+class DiscoveryMetrics:
+    """Prometheus metrics for provider discovery.
+
+    Metrics:
+        - mcp_hangar_discovery_providers_total: Gauge of providers per source/status
+        - mcp_hangar_discovery_registrations_total: Counter of registrations
+        - mcp_hangar_discovery_deregistrations_total: Counter of deregistrations
+        - mcp_hangar_discovery_errors_total: Counter of errors
+        - mcp_hangar_discovery_conflicts_total: Counter of conflicts
+        - mcp_hangar_discovery_quarantine_total: Counter of quarantined providers
+        - mcp_hangar_discovery_latency_seconds: Histogram of discovery cycle duration
+        - mcp_hangar_discovery_validation_duration_seconds: Histogram of validation time
+    """
+
+    def __init__(self, prefix: str = "mcp_hangar_discovery"):
+        """Initialize discovery metrics.
+
+        Args:
+            prefix: Metric name prefix
+        """
+        self.prefix = prefix
+        self._enabled = PROMETHEUS_AVAILABLE
+
+        if not self._enabled:
+            logger.warning("Prometheus metrics disabled (prometheus_client not installed)")
+            return
+
+        # Gauges
+        self.providers_total = Gauge(
+            f"{prefix}_providers_total",
+            "Number of discovered providers",
+            ["source", "status"],
+        )
+
+        # Counters
+        self.registrations_total = Counter(
+            f"{prefix}_registrations_total",
+            "Total provider registrations from discovery",
+            ["source"],
+        )
+
+        self.deregistrations_total = Counter(
+            f"{prefix}_deregistrations_total",
+            "Total provider deregistrations",
+            ["source", "reason"],
+        )
+
+        self.errors_total = Counter(f"{prefix}_errors_total", "Total discovery errors", ["source", "error_type"])
+
+        self.conflicts_total = Counter(f"{prefix}_conflicts_total", "Total discovery conflicts", ["type"])
+
+        self.quarantine_total = Counter(f"{prefix}_quarantine_total", "Total quarantined providers", ["reason"])
+
+        self.validation_failures_total = Counter(
+            f"{prefix}_validation_failures_total",
+            "Total validation failures",
+            ["source", "validation_type"],
+        )
+
+        # Histograms
+        self.latency_seconds = Histogram(
+            f"{prefix}_latency_seconds",
+            "Discovery cycle duration",
+            ["source"],
+            buckets=[0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0],
+        )
+
+        self.validation_duration_seconds = Histogram(
+            f"{prefix}_validation_duration_seconds",
+            "Provider validation duration",
+            ["source"],
+            buckets=[0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0],
+        )
+
+        self.cycle_duration_seconds = Histogram(
+            f"{prefix}_cycle_duration_seconds",
+            "Full discovery cycle duration",
+            buckets=[0.1, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0],
+        )
+
+    def set_providers_count(self, source: str, status: str, count: int) -> None:
+        """Set provider count for a source/status combination.
+
+        Args:
+            source: Discovery source type
+            status: Provider status (discovered, registered, etc.)
+            count: Number of providers
+        """
+        if self._enabled:
+            self.providers_total.labels(source=source, status=status).set(count)
+
+    def inc_registrations(self, source: str) -> None:
+        """Increment registration counter.
+
+        Args:
+            source: Discovery source type
+        """
+        if self._enabled:
+            self.registrations_total.labels(source=source).inc()
+
+    def inc_deregistrations(self, source: str, reason: str) -> None:
+        """Increment deregistration counter.
+
+        Args:
+            source: Discovery source type
+            reason: Reason for deregistration
+        """
+        if self._enabled:
+            self.deregistrations_total.labels(source=source, reason=reason).inc()
+
+    def inc_errors(self, source: str, error_type: str) -> None:
+        """Increment error counter.
+
+        Args:
+            source: Discovery source type
+            error_type: Type of error
+        """
+        if self._enabled:
+            self.errors_total.labels(source=source, error_type=error_type).inc()
+
+    def inc_conflicts(self, conflict_type: str) -> None:
+        """Increment conflict counter.
+
+        Args:
+            conflict_type: Type of conflict
+        """
+        if self._enabled:
+            self.conflicts_total.labels(type=conflict_type).inc()
+
+    def inc_quarantine(self, reason: str) -> None:
+        """Increment quarantine counter.
+
+        Args:
+            reason: Reason for quarantine
+        """
+        if self._enabled:
+            self.quarantine_total.labels(reason=reason).inc()
+
+    def inc_validation_failures(self, source: str, validation_type: str) -> None:
+        """Increment validation failure counter.
+
+        Args:
+            source: Discovery source type
+            validation_type: Type of validation that failed
+        """
+        if self._enabled:
+            self.validation_failures_total.labels(source=source, validation_type=validation_type).inc()
+
+    def observe_latency(self, source: str, duration_seconds: float) -> None:
+        """Record discovery latency.
+
+        Args:
+            source: Discovery source type
+            duration_seconds: Duration in seconds
+        """
+        if self._enabled:
+            self.latency_seconds.labels(source=source).observe(duration_seconds)
+
+    def observe_validation_duration(self, source: str, duration_seconds: float) -> None:
+        """Record validation duration.
+
+        Args:
+            source: Discovery source type
+            duration_seconds: Duration in seconds
+        """
+        if self._enabled:
+            self.validation_duration_seconds.labels(source=source).observe(duration_seconds)
+
+    def observe_cycle_duration(self, duration_seconds: float) -> None:
+        """Record full discovery cycle duration.
+
+        Args:
+            duration_seconds: Duration in seconds
+        """
+        if self._enabled:
+            self.cycle_duration_seconds.observe(duration_seconds)
+
+
+# Global metrics instance
+_metrics: DiscoveryMetrics = None
+
+
+def get_discovery_metrics() -> DiscoveryMetrics:
+    """Get or create global discovery metrics instance.
+
+    Returns:
+        DiscoveryMetrics instance
+    """
+    global _metrics
+    if _metrics is None:
+        _metrics = DiscoveryMetrics()
+    return _metrics
+
+
+def observe_discovery(source_type: str):
+    """Decorator to observe discovery cycle metrics.
+
+    Args:
+        source_type: Discovery source type for labeling
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            metrics = get_discovery_metrics()
+            start = time.perf_counter()
+
+            try:
+                result = await func(*args, **kwargs)
+
+                # Update provider count if result is a list
+                if isinstance(result, list):
+                    metrics.set_providers_count(source=source_type, status="discovered", count=len(result))
+
+                return result
+
+            except Exception as e:
+                metrics.inc_errors(source=source_type, error_type=type(e).__name__)
+                raise
+
+            finally:
+                duration = time.perf_counter() - start
+                metrics.observe_latency(source=source_type, duration_seconds=duration)
+
+        return wrapper
+
+    return decorator
+
+
+def observe_validation(source_type: str):
+    """Decorator to observe validation metrics.
+
+    Args:
+        source_type: Discovery source type for labeling
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            metrics = get_discovery_metrics()
+            start = time.perf_counter()
+
+            try:
+                result = await func(*args, **kwargs)
+                return result
+
+            finally:
+                duration = time.perf_counter() - start
+                metrics.observe_validation_duration(source=source_type, duration_seconds=duration)
+
+        return wrapper
+
+    return decorator