mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/infrastructure/persistence/event_serializer.py

@@ -0,0 +1,280 @@
+"""Event serialization for persistence.
+
+Handles conversion of domain events to/from JSON for storage in event store.
+"""
+
+from datetime import datetime
+import inspect
+import json
+from typing import Any
+
+from mcp_hangar.domain.events import (
+    DiscoveryCycleCompleted,
+    DiscoverySourceHealthChanged,
+    DomainEvent,
+    HealthCheckFailed,
+    HealthCheckPassed,
+    ProviderApproved,
+    ProviderDegraded,
+    ProviderDiscovered,
+    ProviderDiscoveryConfigChanged,
+    ProviderDiscoveryLost,
+    ProviderIdleDetected,
+    ProviderQuarantined,
+    ProviderStarted,
+    ProviderStateChanged,
+    ProviderStopped,
+    ToolInvocationCompleted,
+    ToolInvocationFailed,
+    ToolInvocationRequested,
+)
+from mcp_hangar.logging_config import get_logger
+
+from .event_upcaster import UpcasterChain
+
+logger = get_logger(__name__)
+
+# Registry of event types for deserialization
+EVENT_TYPE_MAP: dict[str, type[DomainEvent]] = {
+    # Provider Lifecycle
+    "ProviderStarted": ProviderStarted,
+    "ProviderStopped": ProviderStopped,
+    "ProviderDegraded": ProviderDegraded,
+    "ProviderStateChanged": ProviderStateChanged,
+    "ProviderIdleDetected": ProviderIdleDetected,
+    # Tool Invocation
+    "ToolInvocationRequested": ToolInvocationRequested,
+    "ToolInvocationCompleted": ToolInvocationCompleted,
+    "ToolInvocationFailed": ToolInvocationFailed,
+    # Health Check
+    "HealthCheckPassed": HealthCheckPassed,
+    "HealthCheckFailed": HealthCheckFailed,
+    # Discovery
+    "ProviderDiscovered": ProviderDiscovered,
+    "ProviderDiscoveryLost": ProviderDiscoveryLost,
+    "ProviderDiscoveryConfigChanged": ProviderDiscoveryConfigChanged,
+    "ProviderQuarantined": ProviderQuarantined,
+    "ProviderApproved": ProviderApproved,
+    "DiscoveryCycleCompleted": DiscoveryCycleCompleted,
+    "DiscoverySourceHealthChanged": DiscoverySourceHealthChanged,
+}
+
+EVENT_VERSION_MAP: dict[str, int] = {
+    # Provider Lifecycle
+    "ProviderStarted": 1,
+    "ProviderStopped": 1,
+    "ProviderDegraded": 1,
+    "ProviderStateChanged": 1,
+    "ProviderIdleDetected": 1,
+    # Tool Invocation
+    "ToolInvocationRequested": 1,
+    "ToolInvocationCompleted": 1,
+    "ToolInvocationFailed": 1,
+    # Health Check
+    "HealthCheckPassed": 1,
+    "HealthCheckFailed": 1,
+    # Discovery
+    "ProviderDiscovered": 1,
+    "ProviderDiscoveryLost": 1,
+    "ProviderDiscoveryConfigChanged": 1,
+    "ProviderQuarantined": 1,
+    "ProviderApproved": 1,
+    "DiscoveryCycleCompleted": 1,
+    "DiscoverySourceHealthChanged": 1,
+}
+
+
+def get_current_version(event_type: str) -> int:
+    """Get current schema version for an event type.
+
+    Args:
+        event_type: Domain event type name.
+
+    Returns:
+        Current schema version. Defaults to 1.
+    """
+
+    return EVENT_VERSION_MAP.get(event_type, 1)
+
+
+class EventSerializationError(Exception):
+    """Raised when event serialization or deserialization fails."""
+
+    def __init__(self, event_type: str, message: str):
+        self.event_type = event_type
+        super().__init__(f"Failed to serialize/deserialize {event_type}: {message}")
+
+
+class EventSerializer:
+    """Serializes domain events to/from JSON.
+
+    Thread-safe: stateless, can be shared across threads.
+    """
+
+    def __init__(self, upcaster_chain: UpcasterChain | None = None) -> None:
+        """Create an EventSerializer.
+
+        Args:
+            upcaster_chain: Optional upcaster chain used during deserialization.
+                If not provided, an empty chain is used.
+        """
+
+        self._upcaster_chain = upcaster_chain or UpcasterChain()
+
+    def serialize(self, event: DomainEvent) -> tuple[str, str]:
+        """Serialize a domain event to (event_type, json_data).
+
+        Args:
+            event: The domain event to serialize.
+
+        Returns:
+            Tuple of (event_type_name, json_string).
+
+        Raises:
+            EventSerializationError: If serialization fails.
+        """
+        event_type = type(event).__name__
+
+        try:
+            version = get_current_version(event_type)
+            data = {"_version": version, **self._to_dict(event)}
+            json_data = json.dumps(data, default=self._json_encoder, ensure_ascii=False)
+            return event_type, json_data
+        except Exception as e:
+            logger.error(
+                "event_serialization_failed",
+                event_type=event_type,
+                error=str(e),
+            )
+            raise EventSerializationError(event_type, str(e)) from e
+
+    def deserialize(self, event_type: str, data: str) -> DomainEvent:
+        """Deserialize a domain event from JSON.
+
+        Args:
+            event_type: The event type name.
+            data: JSON string containing event data.
+
+        Returns:
+            Reconstructed domain event.
+
+        Raises:
+            EventSerializationError: If deserialization fails.
+        """
+        event_class = EVENT_TYPE_MAP.get(event_type)
+        if not event_class:
+            raise EventSerializationError(
+                event_type,
+                f"Unknown event type. Known types: {list(EVENT_TYPE_MAP.keys())}",
+            )
+
+        try:
+            payload = json.loads(data)
+
+            version = payload.pop("_version", 1)
+            current_version = get_current_version(event_type)
+
+            if version < current_version:
+                version, payload = self._upcaster_chain.upcast(
+                    event_type,
+                    version,
+                    payload,
+                    current_version=current_version,
+                )
+
+            # Ensure we don't pass version through to dataclass ctor
+            payload.pop("_version", None)
+
+            return self._from_dict(event_class, payload)
+        except json.JSONDecodeError as e:
+            raise EventSerializationError(event_type, f"Invalid JSON: {e}") from e
+        except Exception as e:
+            logger.error(
+                "event_deserialization_failed",
+                event_type=event_type,
+                error=str(e),
+            )
+            raise EventSerializationError(event_type, str(e)) from e
+
+    def _to_dict(self, event: DomainEvent) -> dict[str, Any]:
+        """Convert event to dictionary, excluding private attributes."""
+        return {key: value for key, value in vars(event).items() if not key.startswith("_")}
+
+    def _from_dict(self, cls: type[DomainEvent], data: dict[str, Any]) -> DomainEvent:
+        """Reconstruct event from dictionary.
+
+        Handles the special case of DomainEvent base class initialization
+        by pre-setting event_id and occurred_at if present in data.
+        """
+        # Extract base class fields
+        event_id = data.pop("event_id", None)
+        occurred_at = data.pop("occurred_at", None)
+
+        ctor_kwargs = self._filter_constructor_kwargs(cls, data)
+
+        # Create instance with remaining data.
+        # Event dataclasses have different constructor signatures; we instantiate dynamically from payload.
+        instance = cls(**ctor_kwargs)  # type: ignore[call-arg]
+
+        # Restore original values if present
+        if event_id is not None:
+            instance.event_id = event_id
+        if occurred_at is not None:
+            instance.occurred_at = occurred_at
+
+        return instance
+
+    def _filter_constructor_kwargs(self, cls: type[DomainEvent], data: dict[str, Any]) -> dict[str, Any]:
+        """Filter payload keys to those accepted by the event constructor.
+
+        This allows forward-compatible payloads with extra fields introduced in newer schema versions.
+
+        Args:
+            cls: Event class.
+            data: Payload dict.
+
+        Returns:
+            Dict containing only keys that are valid __init__ parameters.
+        """
+
+        try:
+            sig = inspect.signature(cls)
+        except (TypeError, ValueError):
+            # Fallback: best-effort passthrough.
+            return data
+
+        params = list(sig.parameters.values())
+        accepted: set[str] = {
+            p.name
+            for p in params
+            if p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+        }
+
+        # If constructor takes **kwargs, avoid filtering.
+        if any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params):
+            return data
+
+        return {k: v for k, v in data.items() if k in accepted}
+
+    def _json_encoder(self, obj: Any) -> Any:
+        """Custom JSON encoder for non-standard types."""
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+        if hasattr(obj, "__dict__"):
+            return obj.__dict__
+        raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def register_event_type(event_class: type[DomainEvent]) -> None:
+    """Register a custom event type for deserialization.
+
+    Use this to register event types from other modules (e.g., provider_group events).
+
+    Args:
+        event_class: The event class to register.
+    """
+    event_type = event_class.__name__
+    EVENT_TYPE_MAP[event_type] = event_class
+    logger.debug("event_type_registered", event_type=event_type)

mcp_hangar/infrastructure/persistence/event_upcaster.py

@@ -0,0 +1,166 @@
+"""Event upcasting for schema evolution.
+
+Upcasting happens at read time. Persisted events may have older schema versions.
+This module provides:
+- IEventUpcaster: a pure transformer from one schema version to the next
+- UpcasterChain: resolves and applies a sequence of upcasters to reach the current schema version
+
+Design goals:
+- Pure functions (no I/O, no time dependence)
+- Fail fast with context
+- Backward compatible: missing version is treated as v1
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from mcp_hangar.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class UpcastingError(RuntimeError):
+    """Raised when upcasting cannot be completed."""
+
+    def __init__(
+        self,
+        *,
+        event_type: str,
+        from_version: int,
+        message: str,
+    ) -> None:
+        self.event_type = event_type
+        self.from_version = from_version
+        super().__init__(f"Upcasting failed for {event_type} from v{from_version}: {message}")
+
+
+class IEventUpcaster(ABC):
+    """Transforms event data from one schema version to the next."""
+
+    @property
+    @abstractmethod
+    def event_type(self) -> str:
+        """Event type this upcaster handles (e.g., 'ProviderStarted')."""
+
+    @property
+    @abstractmethod
+    def from_version(self) -> int:
+        """Source schema version."""
+
+    @property
+    @abstractmethod
+    def to_version(self) -> int:
+        """Target schema version."""
+
+    @abstractmethod
+    def upcast(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Transform event data from from_version to to_version.
+
+        Args:
+            data: Event payload at from_version schema.
+
+        Returns:
+            Event payload at to_version schema.
+        """
+
+
+class UpcasterChain:
+    """Chains upcasters to transform events through multiple versions."""
+
+    def __init__(self) -> None:
+        # Structure: {event_type: {from_version: upcaster}}
+        self._upcasters: dict[str, dict[int, IEventUpcaster]] = {}
+
+    def register(self, upcaster: IEventUpcaster) -> None:
+        """Register an upcaster.
+
+        Args:
+            upcaster: Upcaster instance.
+
+        Raises:
+            ValueError: If the upcaster is invalid or conflicts with an existing registration.
+        """
+        if upcaster.to_version <= upcaster.from_version:
+            raise ValueError(
+                f"Invalid upcaster {type(upcaster).__name__}: to_version must be > from_version "
+                f"(got {upcaster.from_version} -> {upcaster.to_version})",
+            )
+
+        by_type = self._upcasters.setdefault(upcaster.event_type, {})
+        existing = by_type.get(upcaster.from_version)
+        if existing is not None:
+            raise ValueError(
+                f"Upcaster conflict for {upcaster.event_type} from v{upcaster.from_version}: "
+                f"{type(existing).__name__} already registered",
+            )
+
+        by_type[upcaster.from_version] = upcaster
+        logger.debug(
+            "event_upcaster_registered",
+            event_type=upcaster.event_type,
+            from_version=upcaster.from_version,
+            to_version=upcaster.to_version,
+            upcaster=type(upcaster).__name__,
+        )
+
+    def upcast(
+        self, event_type: str, version: int, data: dict[str, Any], *, current_version: int
+    ) -> tuple[int, dict[str, Any]]:
+        """Apply all necessary upcasters to reach current version.
+
+        Args:
+            event_type: Domain event type name.
+            version: Payload schema version.
+            data: Parsed payload dictionary.
+            current_version: Current (target) schema version.
+
+        Returns:
+            Tuple of (final_version, transformed_data).
+
+        Raises:
+            UpcastingError: If an upcast step is missing or fails.
+        """
+        if version >= current_version:
+            return version, data
+
+        event_upcasters = self._upcasters.get(event_type)
+        if not event_upcasters:
+            # No upcasters registered for this type; passthrough.
+            return version, data
+
+        working_version = version
+        working_data = data
+
+        # Apply step-by-step: v1 -> v2 -> ...
+        while working_version < current_version:
+            step = event_upcasters.get(working_version)
+            if step is None:
+                raise UpcastingError(
+                    event_type=event_type,
+                    from_version=working_version,
+                    message=f"Missing upcaster to reach v{current_version}",
+                )
+
+            if step.to_version != working_version + 1:
+                raise UpcastingError(
+                    event_type=event_type,
+                    from_version=working_version,
+                    message=(
+                        f"Upcasters must advance one version at a time (got v{step.from_version} -> v{step.to_version})"
+                    ),
+                )
+
+            try:
+                working_data = step.upcast(working_data)
+            except Exception as e:
+                raise UpcastingError(
+                    event_type=event_type,
+                    from_version=working_version,
+                    message=f"Upcaster {type(step).__name__} failed: {e}",
+                ) from e
+
+            working_version = step.to_version
+
+        return working_version, working_data

mcp_hangar/infrastructure/persistence/in_memory_event_store.py

@@ -0,0 +1,150 @@
+"""In-memory Event Store implementation.
+
+Useful for testing and development. Events are lost on restart.
+"""
+
+from dataclasses import dataclass, field
+import threading
+from typing import Iterator
+
+from mcp_hangar.domain.contracts.event_store import ConcurrencyError, IEventStore
+from mcp_hangar.domain.events import DomainEvent
+from mcp_hangar.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class StoredEvent:
+    """Event wrapper with metadata."""
+
+    global_position: int
+    stream_id: str
+    stream_version: int
+    event: DomainEvent
+
+
+@dataclass
+class Stream:
+    """Stream state tracking."""
+
+    stream_id: str
+    version: int = -1
+    events: list[StoredEvent] = field(default_factory=list)
+
+
+class InMemoryEventStore(IEventStore):
+    """In-memory event store for testing and development.
+
+    Thread-safe but not persistent. All data is lost on restart.
+    """
+
+    def __init__(self):
+        """Initialize empty event store."""
+        self._streams: dict[str, Stream] = {}
+        self._all_events: list[StoredEvent] = []
+        self._lock = threading.Lock()
+        self._global_position = 0
+
+        logger.info("in_memory_event_store_initialized")
+
+    def append(
+        self,
+        stream_id: str,
+        events: list[DomainEvent],
+        expected_version: int,
+    ) -> int:
+        """Append events with optimistic concurrency."""
+        if not events:
+            return expected_version
+
+        with self._lock:
+            # Get or create stream
+            stream = self._streams.get(stream_id)
+            if stream is None:
+                stream = Stream(stream_id=stream_id)
+                self._streams[stream_id] = stream
+
+            # Check version
+            if stream.version != expected_version:
+                raise ConcurrencyError(stream_id, expected_version, stream.version)
+
+            # Append events
+            for event in events:
+                self._global_position += 1
+                stream.version += 1
+
+                stored = StoredEvent(
+                    global_position=self._global_position,
+                    stream_id=stream_id,
+                    stream_version=stream.version,
+                    event=event,
+                )
+                stream.events.append(stored)
+                self._all_events.append(stored)
+
+            logger.debug(
+                "events_appended",
+                stream_id=stream_id,
+                events_count=len(events),
+                new_version=stream.version,
+            )
+
+            return stream.version
+
+    def read_stream(
+        self,
+        stream_id: str,
+        from_version: int = 0,
+    ) -> list[DomainEvent]:
+        """Read events from stream."""
+        with self._lock:
+            stream = self._streams.get(stream_id)
+            if stream is None:
+                return []
+
+            return [stored.event for stored in stream.events if stored.stream_version >= from_version]
+
+    def read_all(
+        self,
+        from_position: int = 0,
+        limit: int = 1000,
+    ) -> Iterator[tuple[int, str, DomainEvent]]:
+        """Read all events globally."""
+        with self._lock:
+            events = [e for e in self._all_events if e.global_position > from_position][:limit]
+
+        for stored in events:
+            yield stored.global_position, stored.stream_id, stored.event
+
+    def get_stream_version(self, stream_id: str) -> int:
+        """Get current stream version."""
+        with self._lock:
+            stream = self._streams.get(stream_id)
+            return stream.version if stream else -1
+
+    def clear(self) -> None:
+        """Clear all events (for testing)."""
+        with self._lock:
+            self._streams.clear()
+            self._all_events.clear()
+            self._global_position = 0
+
+        logger.info("event_store_cleared")
+
+    def get_event_count(self) -> int:
+        """Get total event count."""
+        with self._lock:
+            return len(self._all_events)
+
+    def get_stream_count(self) -> int:
+        """Get total stream count."""
+        with self._lock:
+            return len(self._streams)
+
+    def list_streams(self, prefix: str = "") -> list[str]:
+        """List all stream IDs, optionally filtered by prefix."""
+        with self._lock:
+            if prefix:
+                return [sid for sid in self._streams.keys() if sid.startswith(prefix)]
+            return list(self._streams.keys())