mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/domain/discovery/conflict_resolver.py

@@ -0,0 +1,267 @@
+"""Conflict Resolver for Discovery.
+
+Resolves conflicts between static configuration and discovered providers,
+as well as conflicts between multiple discovery sources.
+
+Critical Design Decision: Static configuration ALWAYS wins over discovery.
+This ensures explicit operator intent is never overridden by automated discovery.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, Optional, Set
+
+from ...logging_config import get_logger
+from .discovered_provider import DiscoveredProvider
+
+logger = get_logger(__name__)
+
+
+class ConflictResolution(Enum):
+    """Resolution outcome for discovered providers."""
+
+    STATIC_WINS = "static_wins"  # Static config takes precedence
+    DISCOVERY_WINS = "discovery_wins"  # Never used, but defined for clarity
+    SOURCE_PRIORITY = "source_priority"  # Higher priority source wins
+    REGISTERED = "registered"  # New provider registered
+    REJECTED = "rejected"  # Provider rejected
+    UNCHANGED = "unchanged"  # Provider unchanged, just update last_seen
+    UPDATED = "updated"  # Provider config changed, updating
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass
+class ConflictResult:
+    """Result of conflict resolution.
+
+    Attributes:
+        resolution: The type of resolution applied
+        winner: The provider that won (if any)
+        reason: Human-readable explanation
+    """
+
+    resolution: ConflictResolution
+    winner: Optional[DiscoveredProvider]
+    reason: str
+
+    @property
+    def should_register(self) -> bool:
+        """Check if provider should be registered."""
+        return self.resolution in (
+            ConflictResolution.REGISTERED,
+            ConflictResolution.UPDATED,
+            ConflictResolution.SOURCE_PRIORITY,
+        )
+
+    @property
+    def should_update_seen(self) -> bool:
+        """Check if last_seen should be updated."""
+        return self.resolution in (
+            ConflictResolution.UNCHANGED,
+            ConflictResolution.REGISTERED,
+            ConflictResolution.UPDATED,
+        )
+
+
+class ConflictResolver:
+    """Resolves conflicts between static config and discovered providers.
+
+    Resolution Rules:
+        1. Static + Discovery conflict: Static wins. Discovery ignored. Warning logged.
+        2. Multiple sources discover same name: First source wins (priority order).
+        3. Discovery finds new provider: Auto-register if mode=additive.
+        4. Provider disappears from source: If mode=authoritative, deregister after TTL.
+
+    Source Priority (lower = higher priority):
+        - static: 0 (Always wins)
+        - kubernetes: 1
+        - docker: 2
+        - filesystem: 3
+        - entrypoint: 4
+    """
+
+    # Source priority (lower number = higher priority)
+    SOURCE_PRIORITY: Dict[str, int] = {
+        "static": 0,  # Always wins
+        "kubernetes": 1,
+        "docker": 2,
+        "filesystem": 3,
+        "entrypoint": 4,
+    }
+
+    def __init__(self, static_providers: Optional[Set[str]] = None):
+        """Initialize conflict resolver.
+
+        Args:
+            static_providers: Set of provider names from static config
+        """
+        self.static_providers = static_providers or set()
+        self._registered: Dict[str, DiscoveredProvider] = {}
+
+    def add_static_provider(self, name: str) -> None:
+        """Add a provider name to the static providers set.
+
+        Args:
+            name: Provider name from static configuration
+        """
+        self.static_providers.add(name)
+
+    def remove_static_provider(self, name: str) -> None:
+        """Remove a provider name from the static providers set.
+
+        Args:
+            name: Provider name to remove
+        """
+        self.static_providers.discard(name)
+
+    def resolve(self, provider: DiscoveredProvider) -> ConflictResult:
+        """Determine if provider should be registered.
+
+        Args:
+            provider: Discovered provider to resolve
+
+        Returns:
+            ConflictResult with resolution decision
+        """
+        # Rule 1: Static always wins
+        if provider.name in self.static_providers:
+            logger.warning(
+                f"Provider '{provider.name}' conflicts with static config. "
+                f"Static wins. Discovery from {provider.source_type} ignored."
+            )
+            return ConflictResult(
+                resolution=ConflictResolution.STATIC_WINS,
+                winner=None,
+                reason="Static configuration takes precedence",
+            )
+
+        # Rule 2: Check existing registered providers
+        existing = self._registered.get(provider.name)
+        if existing:
+            # Same source, same fingerprint = no change
+            if existing.source_type == provider.source_type and existing.fingerprint == provider.fingerprint:
+                return ConflictResult(
+                    resolution=ConflictResolution.UNCHANGED,
+                    winner=provider.with_updated_seen_time(),
+                    reason="Provider unchanged, updating last_seen",
+                )
+
+            # Same source, different fingerprint = config changed
+            if existing.source_type == provider.source_type:
+                logger.info(
+                    f"Provider '{provider.name}' config changed "
+                    f"(fingerprint {existing.fingerprint} -> {provider.fingerprint})"
+                )
+                return ConflictResult(
+                    resolution=ConflictResolution.UPDATED,
+                    winner=provider,
+                    reason="Provider configuration updated",
+                )
+
+            # Different source = check priority
+            existing_priority = self.SOURCE_PRIORITY.get(existing.source_type, 99)
+            new_priority = self.SOURCE_PRIORITY.get(provider.source_type, 99)
+
+            if new_priority < existing_priority:
+                logger.info(
+                    f"Provider '{provider.name}' from {provider.source_type} "
+                    f"overrides {existing.source_type} (higher priority)"
+                )
+                return ConflictResult(
+                    resolution=ConflictResolution.SOURCE_PRIORITY,
+                    winner=provider,
+                    reason=f"{provider.source_type} has higher priority than {existing.source_type}",
+                )
+            else:
+                logger.debug(
+                    f"Provider '{provider.name}' from {provider.source_type} "
+                    f"rejected (lower priority than {existing.source_type})"
+                )
+                return ConflictResult(
+                    resolution=ConflictResolution.REJECTED,
+                    winner=None,
+                    reason=f"Existing source {existing.source_type} has higher priority",
+                )
+
+        # No conflict - new provider
+        logger.info(f"New provider discovered: {provider.name} from {provider.source_type}")
+        return ConflictResult(
+            resolution=ConflictResolution.REGISTERED,
+            winner=provider,
+            reason="New provider registered",
+        )
+
+    def register(self, provider: DiscoveredProvider) -> None:
+        """Mark provider as registered.
+
+        Args:
+            provider: Provider to register
+        """
+        self._registered[provider.name] = provider
+        logger.debug(f"Registered provider: {provider.name}")
+
+    def update(self, provider: DiscoveredProvider) -> None:
+        """Update registered provider.
+
+        Args:
+            provider: Provider with updated configuration
+        """
+        self._registered[provider.name] = provider
+        logger.debug(f"Updated provider: {provider.name}")
+
+    def deregister(self, name: str) -> Optional[DiscoveredProvider]:
+        """Remove provider from registry.
+
+        Args:
+            name: Provider name to deregister
+
+        Returns:
+            The removed provider, or None if not found
+        """
+        provider = self._registered.pop(name, None)
+        if provider:
+            logger.info(f"Deregistered provider: {name}")
+        return provider
+
+    def get_registered(self, name: str) -> Optional[DiscoveredProvider]:
+        """Get a registered provider by name.
+
+        Args:
+            name: Provider name
+
+        Returns:
+            The registered provider, or None if not found
+        """
+        return self._registered.get(name)
+
+    def get_all_registered(self) -> Dict[str, DiscoveredProvider]:
+        """Get all registered providers.
+
+        Returns:
+            Dictionary of name -> DiscoveredProvider
+        """
+        return dict(self._registered)
+
+    def is_registered(self, name: str) -> bool:
+        """Check if a provider is registered.
+
+        Args:
+            name: Provider name
+
+        Returns:
+            True if registered
+        """
+        return name in self._registered
+
+    def get_source_priority(self, source_type: str) -> int:
+        """Get priority for a source type.
+
+        Args:
+            source_type: Source type name
+
+        Returns:
+            Priority number (lower = higher priority)
+        """
+        return self.SOURCE_PRIORITY.get(source_type, 99)

mcp_hangar/domain/discovery/discovered_provider.py

@@ -0,0 +1,185 @@
+"""Discovered Provider Value Object.
+
+Value object representing a discovered provider with fingerprinting
+and TTL-based lifecycle tracking.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import hashlib
+import json
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class DiscoveredProvider:
+    """Value object representing a discovered provider.
+
+    This immutable value object captures all information about a provider
+    discovered from external sources (Kubernetes, Docker, filesystem, etc.).
+
+    Attributes:
+        name: Unique identifier for the provider
+        source_type: Origin of discovery (kubernetes, docker, filesystem, entrypoint)
+        mode: Connection mode (stdio, sse, http, subprocess)
+        connection_info: Mode-specific connection details
+        metadata: Labels, annotations, and custom data
+        fingerprint: SHA256 hash for change detection
+        discovered_at: First discovery timestamp
+        last_seen_at: Most recent discovery timestamp (for TTL)
+        ttl_seconds: Time-to-live before expiration (default: 90s = 3x refresh interval)
+    """
+
+    name: str
+    source_type: str
+    mode: str
+    connection_info: Dict[str, Any]
+    metadata: Dict[str, Any]
+    fingerprint: str
+    discovered_at: datetime
+    last_seen_at: datetime
+    ttl_seconds: int = 90
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        source_type: str,
+        mode: str,
+        connection_info: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+        ttl_seconds: int = 90,
+    ) -> "DiscoveredProvider":
+        """Factory method with automatic fingerprinting.
+
+        Args:
+            name: Unique identifier for the provider
+            source_type: Origin of discovery
+            mode: Connection mode
+            connection_info: Mode-specific connection details
+            metadata: Optional labels and annotations
+            ttl_seconds: Time-to-live in seconds
+
+        Returns:
+            New DiscoveredProvider instance with computed fingerprint
+        """
+        metadata = metadata or {}
+        fingerprint_data = json.dumps({"connection_info": connection_info, "metadata": metadata}, sort_keys=True)
+        fingerprint = hashlib.sha256(fingerprint_data.encode()).hexdigest()[:16]
+        now = datetime.now(timezone.utc)
+
+        return cls(
+            name=name,
+            source_type=source_type,
+            mode=mode,
+            connection_info=connection_info,
+            metadata=metadata,
+            fingerprint=fingerprint,
+            discovered_at=now,
+            last_seen_at=now,
+            ttl_seconds=ttl_seconds,
+        )
+
+    def is_expired(self) -> bool:
+        """Check if provider has exceeded TTL.
+
+        Returns:
+            True if time since last_seen exceeds ttl_seconds
+        """
+        now = datetime.now(timezone.utc)
+        # Handle both timezone-aware and naive datetimes
+        last_seen = self.last_seen_at
+        if last_seen.tzinfo is None:
+            last_seen = last_seen.replace(tzinfo=timezone.utc)
+        elapsed = (now - last_seen).total_seconds()
+        return elapsed > self.ttl_seconds
+
+    def with_updated_seen_time(self) -> "DiscoveredProvider":
+        """Return new instance with updated last_seen_at.
+
+        Since this is an immutable value object, we create a new instance
+        rather than mutating in place.
+
+        Returns:
+            New DiscoveredProvider with current timestamp as last_seen_at
+        """
+        return DiscoveredProvider(
+            name=self.name,
+            source_type=self.source_type,
+            mode=self.mode,
+            connection_info=self.connection_info,
+            metadata=self.metadata,
+            fingerprint=self.fingerprint,
+            discovered_at=self.discovered_at,
+            last_seen_at=datetime.now(timezone.utc),
+            ttl_seconds=self.ttl_seconds,
+        )
+
+    def has_changed(self, other: "DiscoveredProvider") -> bool:
+        """Check if configuration has changed by comparing fingerprints.
+
+        Args:
+            other: Another DiscoveredProvider to compare
+
+        Returns:
+            True if fingerprints differ (configuration changed)
+        """
+        return self.fingerprint != other.fingerprint
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary representation of the provider
+        """
+        return {
+            "name": self.name,
+            "source_type": self.source_type,
+            "mode": self.mode,
+            "connection_info": self.connection_info,
+            "metadata": self.metadata,
+            "fingerprint": self.fingerprint,
+            "discovered_at": self.discovered_at.isoformat(),
+            "last_seen_at": self.last_seen_at.isoformat(),
+            "ttl_seconds": self.ttl_seconds,
+            "is_expired": self.is_expired(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DiscoveredProvider":
+        """Create from dictionary representation.
+
+        Args:
+            data: Dictionary with provider data
+
+        Returns:
+            DiscoveredProvider instance
+        """
+        discovered_at = data.get("discovered_at")
+        last_seen_at = data.get("last_seen_at")
+
+        if isinstance(discovered_at, str):
+            discovered_at = datetime.fromisoformat(discovered_at)
+        if isinstance(last_seen_at, str):
+            last_seen_at = datetime.fromisoformat(last_seen_at)
+
+        return cls(
+            name=data["name"],
+            source_type=data["source_type"],
+            mode=data["mode"],
+            connection_info=data["connection_info"],
+            metadata=data.get("metadata", {}),
+            fingerprint=data["fingerprint"],
+            discovered_at=discovered_at,
+            last_seen_at=last_seen_at,
+            ttl_seconds=data.get("ttl_seconds", 90),
+        )
+
+    def __str__(self) -> str:
+        return f"DiscoveredProvider({self.name}, source={self.source_type}, mode={self.mode})"
+
+    def __repr__(self) -> str:
+        return (
+            f"DiscoveredProvider(name={self.name!r}, source_type={self.source_type!r}, "
+            f"mode={self.mode!r}, fingerprint={self.fingerprint!r})"
+        )