mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/infrastructure/discovery/kubernetes_source.py

@@ -0,0 +1,247 @@
+"""Kubernetes Discovery Source.
+
+Discovers MCP providers from Kubernetes pods/services using annotations.
+Supports both in-cluster and out-of-cluster configuration.
+
+Annotation Prefix: mcp.hangar.io/*
+
+Example Pod Annotations:
+    mcp.hangar.io/enabled: "true"
+    mcp.hangar.io/name: "my-provider"
+    mcp.hangar.io/mode: "http"
+    mcp.hangar.io/port: "8080"
+    mcp.hangar.io/group: "data-team"
+    mcp.hangar.io/health-path: "/health"
+"""
+
+from typing import List, Optional
+
+from mcp_hangar.domain.discovery.discovered_provider import DiscoveredProvider
+from mcp_hangar.domain.discovery.discovery_source import DiscoveryMode, DiscoverySource
+
+from ...logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Optional Kubernetes dependency
+try:
+    from kubernetes import client, config
+    from kubernetes.client.rest import ApiException
+
+    KUBERNETES_AVAILABLE = True
+except ImportError:
+    KUBERNETES_AVAILABLE = False
+    ApiException = Exception  # Fallback for type hints
+    client = None
+    config = None
+    logger.debug("kubernetes package not installed, KubernetesDiscoverySource unavailable")
+
+
+class KubernetesDiscoverySource(DiscoverySource):
+    """Discover MCP providers from Kubernetes pods/services.
+
+    Uses pod annotations to discover and configure MCP providers.
+    Supports namespace filtering and label selectors.
+
+    Attributes:
+        ANNOTATION_PREFIX: Prefix for all MCP annotations
+    """
+
+    ANNOTATION_PREFIX = "mcp.hangar.io/"
+
+    def __init__(
+        self,
+        mode: DiscoveryMode = DiscoveryMode.AUTHORITATIVE,
+        namespaces: Optional[List[str]] = None,
+        label_selector: Optional[str] = None,
+        in_cluster: bool = True,
+        kubeconfig_path: Optional[str] = None,
+        default_ttl: int = 90,
+    ):
+        """Initialize Kubernetes discovery source.
+
+        Args:
+            mode: Discovery mode (default: authoritative for K8s)
+            namespaces: List of namespaces to watch (None = all)
+            label_selector: Kubernetes label selector
+            in_cluster: Whether running inside cluster
+            kubeconfig_path: Path to kubeconfig (for out-of-cluster)
+            default_ttl: Default TTL for discovered providers
+        """
+        super().__init__(mode)
+
+        if not KUBERNETES_AVAILABLE:
+            raise ImportError(
+                "kubernetes package is required for KubernetesDiscoverySource. Install with: pip install kubernetes"
+            )
+
+        self.namespaces = namespaces or []
+        self.label_selector = label_selector
+        self.in_cluster = in_cluster
+        self.kubeconfig_path = kubeconfig_path
+        self.default_ttl = default_ttl
+
+        self._v1: Optional[client.CoreV1Api] = None
+        self._initialized = False
+
+    def _ensure_initialized(self) -> None:
+        """Ensure Kubernetes client is initialized."""
+        if self._initialized:
+            return
+
+        try:
+            if self.in_cluster:
+                config.load_incluster_config()
+            else:
+                config.load_kube_config(config_file=self.kubeconfig_path)
+
+            self._v1 = client.CoreV1Api()
+            self._initialized = True
+            logger.info(
+                f"Kubernetes discovery initialized "
+                f"(in_cluster={self.in_cluster}, namespaces={self.namespaces or 'all'})"
+            )
+        except Exception as e:
+            logger.error(f"Failed to initialize Kubernetes client: {e}")
+            raise
+
+    @property
+    def source_type(self) -> str:
+        return "kubernetes"
+
+    async def discover(self) -> List[DiscoveredProvider]:
+        """Discover providers from pod annotations.
+
+        Returns:
+            List of discovered providers
+        """
+        self._ensure_initialized()
+        providers = []
+
+        namespaces = self.namespaces or await self._get_all_namespaces()
+
+        for namespace in namespaces:
+            try:
+                pods = self._v1.list_namespaced_pod(namespace=namespace, label_selector=self.label_selector)
+
+                for pod in pods.items:
+                    provider = self._parse_pod(pod, namespace)
+                    if provider:
+                        providers.append(provider)
+                        await self.on_provider_discovered(provider)
+
+            except ApiException as e:
+                logger.warning(f"Failed to list pods in {namespace}: {e.reason}")
+            except Exception as e:
+                logger.error(f"Error discovering in namespace {namespace}: {e}")
+
+        logger.debug(f"Kubernetes discovery found {len(providers)} providers")
+        return providers
+
+    def _parse_pod(self, pod, namespace: str) -> Optional[DiscoveredProvider]:
+        """Parse pod annotations into DiscoveredProvider.
+
+        Args:
+            pod: Kubernetes pod object
+            namespace: Pod namespace
+
+        Returns:
+            DiscoveredProvider or None if not MCP-enabled
+        """
+        annotations = pod.metadata.annotations or {}
+
+        # Check if MCP discovery is enabled
+        enabled = annotations.get(f"{self.ANNOTATION_PREFIX}enabled", "false")
+        if enabled.lower() != "true":
+            return None
+
+        # Extract provider config
+        name = annotations.get(f"{self.ANNOTATION_PREFIX}name", pod.metadata.name)
+        mode = annotations.get(f"{self.ANNOTATION_PREFIX}mode", "http")
+        port = annotations.get(f"{self.ANNOTATION_PREFIX}port", "8080")
+        group = annotations.get(f"{self.ANNOTATION_PREFIX}group")
+        health_path = annotations.get(f"{self.ANNOTATION_PREFIX}health-path", "/health")
+        ttl = int(annotations.get(f"{self.ANNOTATION_PREFIX}ttl", str(self.default_ttl)))
+
+        # Get pod IP
+        pod_ip = pod.status.pod_ip if pod.status else None
+        if not pod_ip:
+            logger.debug(f"Pod {pod.metadata.name} has no IP, skipping")
+            return None
+
+        # Check pod phase
+        phase = pod.status.phase if pod.status else "Unknown"
+        if phase != "Running":
+            logger.debug(f"Pod {pod.metadata.name} not running (phase={phase}), skipping")
+            return None
+
+        # Build connection info
+        connection_info = {
+            "host": pod_ip,
+            "port": int(port),
+            "health_path": health_path,
+        }
+
+        # Handle subprocess mode
+        if mode == "subprocess" or mode == "stdio":
+            command = annotations.get(f"{self.ANNOTATION_PREFIX}command")
+            if command:
+                connection_info["command"] = command.split()
+
+        metadata = {
+            "namespace": namespace,
+            "pod_name": pod.metadata.name,
+            "pod_uid": pod.metadata.uid,
+            "group": group,
+            "labels": pod.metadata.labels or {},
+            "annotations": {k: v for k, v in annotations.items() if k.startswith(self.ANNOTATION_PREFIX)},
+            "node_name": pod.spec.node_name if pod.spec else None,
+            "phase": phase,
+        }
+
+        return DiscoveredProvider.create(
+            name=name,
+            source_type=self.source_type,
+            mode=mode,
+            connection_info=connection_info,
+            metadata=metadata,
+            ttl_seconds=ttl,
+        )
+
+    async def health_check(self) -> bool:
+        """Check Kubernetes API availability.
+
+        Returns:
+            True if API is accessible
+        """
+        try:
+            self._ensure_initialized()
+            self._v1.get_api_resources()
+            return True
+        except Exception as e:
+            logger.warning(f"Kubernetes health check failed: {e}")
+            return False
+
+    async def _get_all_namespaces(self) -> List[str]:
+        """Get all namespace names.
+
+        Returns:
+            List of namespace names
+        """
+        try:
+            namespaces = self._v1.list_namespace()
+            return [ns.metadata.name for ns in namespaces.items]
+        except ApiException as e:
+            logger.error(f"Failed to list namespaces: {e.reason}")
+            return []
+
+    async def start(self) -> None:
+        """Start the Kubernetes discovery source."""
+        self._ensure_initialized()
+        logger.info("Kubernetes discovery source started")
+
+    async def stop(self) -> None:
+        """Stop the Kubernetes discovery source."""
+        self._initialized = False
+        self._v1 = None
+        logger.info("Kubernetes discovery source stopped")

mcp_hangar/infrastructure/event_bus.py

@@ -0,0 +1,260 @@
+"""Event bus for publish/subscribe pattern.
+
+The event bus allows decoupled communication between components via domain events.
+Supports optional event persistence via IEventStore.
+"""
+
+import threading
+from typing import Callable, Dict, List, Type
+
+from mcp_hangar.domain.contracts.event_store import IEventStore, NullEventStore
+from mcp_hangar.domain.events import DomainEvent
+from mcp_hangar.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class EventHandler:
+    """Base class for event handlers."""
+
+    def handle(self, event: DomainEvent) -> None:
+        """Handle a domain event."""
+        raise NotImplementedError
+
+
+class EventBus:
+    """
+    Thread-safe event bus for publishing and subscribing to domain events.
+
+    Supports multiple subscribers per event type.
+    Handlers are called synchronously in order of subscription.
+    Optionally persists events via IEventStore before publishing.
+    """
+
+    def __init__(self, event_store: IEventStore | None = None):
+        """Initialize event bus.
+
+        Args:
+            event_store: Optional event store for persistence.
+                If None, events are not persisted.
+        """
+        self._handlers: Dict[Type[DomainEvent], List[Callable[[DomainEvent], None]]] = {}
+        self._lock = threading.Lock()
+        self._error_handlers: List[Callable[[Exception, DomainEvent], None]] = []
+        self._event_store = event_store or NullEventStore()
+
+    @property
+    def event_store(self) -> IEventStore:
+        """Get the event store instance."""
+        return self._event_store
+
+    def set_event_store(self, event_store: IEventStore) -> None:
+        """Set the event store (for late binding during bootstrap).
+
+        Args:
+            event_store: Event store implementation.
+        """
+        self._event_store = event_store
+        logger.info("event_store_configured", store_type=type(event_store).__name__)
+
+    def subscribe(self, event_type: Type[DomainEvent], handler: Callable[[DomainEvent], None]) -> None:
+        """
+        Subscribe to a specific event type.
+
+        Args:
+            event_type: The type of event to subscribe to
+            handler: Callable that takes the event as parameter
+        """
+        with self._lock:
+            if event_type not in self._handlers:
+                self._handlers[event_type] = []
+            self._handlers[event_type].append(handler)
+
+        logger.debug(f"Subscribed handler to {event_type.__name__}")
+
+    def subscribe_to_all(self, handler: Callable[[DomainEvent], None]) -> None:
+        """
+        Subscribe to all event types.
+
+        Args:
+            handler: Callable that takes any event as parameter
+        """
+        with self._lock:
+            if DomainEvent not in self._handlers:
+                self._handlers[DomainEvent] = []
+            self._handlers[DomainEvent].append(handler)
+
+        logger.debug("Subscribed handler to all events")
+
+    def unsubscribe(self, event_type: Type[DomainEvent], handler: Callable[[DomainEvent], None]) -> None:
+        """
+        Unsubscribe a handler from an event type.
+
+        Args:
+            event_type: The type of event
+            handler: The handler to remove
+        """
+        with self._lock:
+            if event_type in self._handlers:
+                self._handlers[event_type].remove(handler)
+
+    def publish(self, event: DomainEvent) -> None:
+        """
+        Publish an event to all subscribed handlers.
+
+        Handlers are called synchronously in subscription order.
+        If a handler fails, the exception is logged and remaining handlers
+        are still called.
+
+        Note: This method does NOT persist events. Use publish_to_stream()
+        for event persistence.
+
+        Args:
+            event: The domain event to publish
+        """
+        with self._lock:
+            # Get handlers for this specific event type
+            specific_handlers = self._handlers.get(type(event), [])
+            # Get handlers subscribed to all events
+            all_handlers = self._handlers.get(DomainEvent, [])
+            handlers = specific_handlers + all_handlers
+
+        logger.debug(
+            "event_publishing",
+            event_type=event.__class__.__name__,
+            handlers_count=len(handlers),
+        )
+
+        # Call handlers outside the lock
+        for handler in handlers:
+            try:
+                handler(event)
+            except Exception as e:
+                logger.exception(
+                    "event_handler_error",
+                    event_type=event.__class__.__name__,
+                    error=str(e),
+                )
+                # Call error handlers
+                for error_handler in self._error_handlers:
+                    try:
+                        error_handler(e, event)
+                    except Exception as eh:
+                        logger.exception(
+                            "event_error_handler_failed",
+                            event_type=event.__class__.__name__,
+                            error=str(eh),
+                        )
+
+    def publish_to_stream(
+        self,
+        stream_id: str,
+        events: list[DomainEvent],
+        expected_version: int = -1,
+    ) -> int:
+        """
+        Persist events to a stream and then publish to handlers.
+
+        This method provides full Event Sourcing support:
+        1. Persists events to the event store (with optimistic concurrency)
+        2. Publishes events to subscribed handlers
+
+        Args:
+            stream_id: Stream identifier (e.g., "provider:math")
+            events: List of events to persist and publish
+            expected_version: Expected stream version for concurrency check.
+                Use -1 for new streams.
+
+        Returns:
+            New stream version after append.
+
+        Raises:
+            ConcurrencyError: If version mismatch in event store.
+        """
+        if not events:
+            return expected_version
+
+        # Persist first (fail fast if concurrency error)
+        new_version = self._event_store.append(stream_id, events, expected_version)
+
+        logger.debug(
+            "events_persisted",
+            stream_id=stream_id,
+            events_count=len(events),
+            new_version=new_version,
+        )
+
+        # Then publish to handlers
+        for event in events:
+            self.publish(event)
+
+        return new_version
+
+    def publish_aggregate_events(
+        self,
+        aggregate_type: str,
+        aggregate_id: str,
+        events: list[DomainEvent],
+        expected_version: int = -1,
+    ) -> int:
+        """
+        Convenience method for publishing aggregate events.
+
+        Constructs stream_id from aggregate type and ID.
+
+        Args:
+            aggregate_type: Type of aggregate (e.g., "provider", "provider_group")
+            aggregate_id: Unique identifier of the aggregate
+            events: Events collected from aggregate
+            expected_version: Expected version for concurrency
+
+        Returns:
+            New stream version.
+        """
+        stream_id = f"{aggregate_type}:{aggregate_id}"
+        return self.publish_to_stream(stream_id, events, expected_version)
+
+    def on_error(self, handler: Callable[[Exception, DomainEvent], None]) -> None:
+        """
+        Register a handler for errors that occur during event handling.
+
+        Args:
+            handler: Callable that takes (exception, event)
+        """
+        self._error_handlers.append(handler)
+
+    def clear(self) -> None:
+        """Clear all subscriptions (mainly for testing)."""
+        with self._lock:
+            self._handlers.clear()
+            self._error_handlers.clear()
+
+
+# Global event bus instance
+_global_event_bus: EventBus | None = None
+_global_bus_lock = threading.Lock()
+
+
+def get_event_bus() -> EventBus:
+    """
+    Get the global event bus instance (singleton pattern).
+
+    Returns:
+        The global EventBus instance
+    """
+    global _global_event_bus
+
+    if _global_event_bus is None:
+        with _global_bus_lock:
+            if _global_event_bus is None:
+                _global_event_bus = EventBus()
+
+    return _global_event_bus
+
+
+def reset_event_bus() -> None:
+    """Reset the global event bus (mainly for testing)."""
+    global _global_event_bus
+
+    with _global_bus_lock:
+        _global_event_bus = None