mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/application/event_handlers/audit_handler.py

@@ -0,0 +1,203 @@
+"""Audit event handler for compliance and debugging."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from ...domain.events import DomainEvent
+from ...logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class AuditRecord:
+    """Represents an audit log entry."""
+
+    event_id: str
+    event_type: str
+    occurred_at: datetime
+    provider_id: Optional[str]
+    data: Dict[str, Any]
+    recorded_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert audit record to dictionary."""
+        return {
+            "event_id": self.event_id,
+            "event_type": self.event_type,
+            "occurred_at": (
+                self.occurred_at.isoformat() if isinstance(self.occurred_at, datetime) else str(self.occurred_at)
+            ),
+            "provider_id": self.provider_id,
+            "data": self.data,
+            "recorded_at": self.recorded_at.isoformat(),
+        }
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict())
+
+
+class AuditStore(ABC):
+    """Abstract interface for audit log storage."""
+
+    @abstractmethod
+    def record(self, audit_record: AuditRecord) -> None:
+        """Store an audit record."""
+        pass
+
+    @abstractmethod
+    def query(
+        self,
+        provider_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        since: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> List[AuditRecord]:
+        """Query audit records."""
+        pass
+
+
+class InMemoryAuditStore(AuditStore):
+    """In-memory audit store for testing and development."""
+
+    def __init__(self, max_records: int = 10000):
+        self._records: List[AuditRecord] = []
+        self._max_records = max_records
+
+    def record(self, audit_record: AuditRecord) -> None:
+        """Store an audit record."""
+        self._records.append(audit_record)
+        # Trim old records if over limit
+        if len(self._records) > self._max_records:
+            self._records = self._records[-self._max_records :]
+
+    def query(
+        self,
+        provider_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        since: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> List[AuditRecord]:
+        """Query audit records with optional filters."""
+        results = []
+        for record in reversed(self._records):  # Most recent first
+            if len(results) >= limit:
+                break
+
+            # Apply filters
+            if provider_id and record.provider_id != provider_id:
+                continue
+            if event_type and record.event_type != event_type:
+                continue
+            if since and record.recorded_at < since:
+                continue
+
+            results.append(record)
+
+        return results
+
+    def clear(self) -> None:
+        """Clear all records (for testing)."""
+        self._records.clear()
+
+    @property
+    def count(self) -> int:
+        """Get number of stored records."""
+        return len(self._records)
+
+
+class LogAuditStore(AuditStore):
+    """Audit store that writes to structured logs."""
+
+    def __init__(self, logger_name: str = "audit"):
+        self._logger = logging.getLogger(logger_name)
+
+    def record(self, audit_record: AuditRecord) -> None:
+        """Log the audit record."""
+        self._logger.info(audit_record.to_json())
+
+    def query(
+        self,
+        provider_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        since: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> List[AuditRecord]:
+        """Query is not supported for log store."""
+        raise NotImplementedError("Log audit store does not support queries")
+
+
+class AuditEventHandler:
+    """
+    Event handler that records all events for audit trail.
+
+    Records every domain event with full details for:
+    - Compliance requirements
+    - Debugging and troubleshooting
+    - Historical analysis
+    """
+
+    def __init__(
+        self,
+        store: Optional[AuditStore] = None,
+        include_event_types: Optional[List[str]] = None,
+        exclude_event_types: Optional[List[str]] = None,
+    ):
+        """
+        Initialize the audit handler.
+
+        Args:
+            store: Audit store to use (defaults to in-memory)
+            include_event_types: Only record these event types (None = all)
+            exclude_event_types: Exclude these event types
+        """
+        self._store = store or InMemoryAuditStore()
+        self._include = set(include_event_types) if include_event_types else None
+        self._exclude = set(exclude_event_types) if exclude_event_types else set()
+
+    def handle(self, event: DomainEvent) -> None:
+        """Handle a domain event by recording it."""
+        event_type = type(event).__name__
+
+        # Check filters
+        if self._include is not None and event_type not in self._include:
+            return
+        if event_type in self._exclude:
+            return
+
+        # Extract provider_id if available
+        provider_id = getattr(event, "provider_id", None)
+
+        # Create audit record
+        record = AuditRecord(
+            event_id=event.event_id,
+            event_type=event_type,
+            occurred_at=event.occurred_at,
+            provider_id=provider_id,
+            data=event.to_dict(),
+        )
+
+        try:
+            self._store.record(record)
+        except Exception as e:
+            logger.error(f"Failed to record audit event: {e}")
+
+    @property
+    def store(self) -> AuditStore:
+        """Get the audit store."""
+        return self._store
+
+    def query(
+        self,
+        provider_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        since: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> List[AuditRecord]:
+        """Query audit records."""
+        return self._store.query(provider_id=provider_id, event_type=event_type, since=since, limit=limit)

mcp_hangar/application/event_handlers/knowledge_base_handler.py

@@ -0,0 +1,120 @@
+"""Knowledge base event handler.
+
+Persists domain events to knowledge base (PostgreSQL, SQLite, etc.).
+"""
+
+from typing import Callable, Dict, Type
+
+from ...domain.events import (
+    DomainEvent,
+    ProviderStarted,
+    ProviderStateChanged,
+    ProviderStopped,
+    ToolInvocationCompleted,
+    ToolInvocationFailed,
+)
+from ...infrastructure.async_executor import submit_async
+from ...logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class KnowledgeBaseEventHandler:
+    """Event handler that persists events to knowledge base.
+
+    Uses strategy pattern to map event types to persistence handlers,
+    following Open/Closed Principle - new event types can be added
+    without modifying existing code.
+    """
+
+    def __init__(self):
+        """Initialize handler with event type mappings."""
+        # Strategy mapping: event type -> persistence handler
+        # Using Any for handlers to avoid complex generic types
+        self._handlers: Dict[Type[DomainEvent], Callable] = {
+            ProviderStateChanged: self._persist_state_change,
+            ProviderStarted: self._persist_provider_started,
+            ProviderStopped: self._persist_provider_stopped,
+            ToolInvocationCompleted: self._persist_tool_completed,
+            ToolInvocationFailed: self._persist_tool_failed,
+        }
+
+    def handle(self, event: DomainEvent) -> None:
+        """Handle a domain event by persisting to knowledge base.
+
+        Args:
+            event: Domain event to persist
+        """
+        from ...infrastructure.knowledge_base import is_available
+
+        if not is_available():
+            return
+
+        # Find handler for this event type
+        handler = self._handlers.get(type(event))
+        if handler is None:
+            return
+
+        # Submit async persistence using executor (fire-and-forget)
+        submit_async(
+            handler(event),
+            on_error=lambda e: logger.debug("kb_persist_error", error=str(e), event_type=type(event).__name__),
+        )
+
+    async def _persist_state_change(self, event: ProviderStateChanged) -> None:
+        """Persist provider state change event."""
+        from ...infrastructure.knowledge_base import record_state_change
+
+        await record_state_change(
+            provider_id=event.provider_id,
+            old_state=event.old_state,
+            new_state=event.new_state,
+            reason=None,
+        )
+
+    async def _persist_provider_started(self, event: ProviderStarted) -> None:
+        """Persist provider started event as metric."""
+        from ...infrastructure.knowledge_base import record_metric
+
+        await record_metric(
+            provider_id=event.provider_id,
+            metric_name="startup_duration_ms",
+            metric_value=event.startup_duration_ms,
+            labels={"mode": event.mode, "tools_count": event.tools_count},
+        )
+
+    async def _persist_provider_stopped(self, event: ProviderStopped) -> None:
+        """Persist provider stopped event."""
+        from ...infrastructure.knowledge_base import record_state_change
+
+        await record_state_change(
+            provider_id=event.provider_id,
+            old_state="ready",
+            new_state="stopped",
+            reason=event.reason,
+        )
+
+    async def _persist_tool_completed(self, event: ToolInvocationCompleted) -> None:
+        """Persist successful tool invocation."""
+        from ...infrastructure.knowledge_base import audit_log
+
+        await audit_log(
+            event_type="tool_completed",
+            provider=event.provider_id,
+            tool=event.tool_name,
+            duration_ms=int(event.duration_ms),
+            success=True,
+        )
+
+    async def _persist_tool_failed(self, event: ToolInvocationFailed) -> None:
+        """Persist failed tool invocation."""
+        from ...infrastructure.knowledge_base import audit_log
+
+        await audit_log(
+            event_type="tool_failed",
+            provider=event.provider_id,
+            tool=event.tool_name,
+            duration_ms=int(event.duration_ms) if hasattr(event, "duration_ms") else None,
+            success=False,
+            error_message=event.error[:500] if hasattr(event, "error") else None,
+        )

mcp_hangar/application/event_handlers/logging_handler.py

@@ -0,0 +1,69 @@
+"""Logging event handler - logs all domain events."""
+
+import logging
+
+from mcp_hangar.domain.events import (
+    DomainEvent,
+    HealthCheckFailed,
+    ProviderDegraded,
+    ProviderStarted,
+    ProviderStopped,
+    ToolInvocationCompleted,
+    ToolInvocationFailed,
+    ToolInvocationRequested,
+)
+from mcp_hangar.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class LoggingEventHandler:
+    """
+    Event handler that logs all domain events in structured format.
+
+    This demonstrates the event-driven pattern and provides audit trail.
+    """
+
+    def __init__(self, log_level: int = logging.INFO):
+        """
+        Initialize the logging handler.
+
+        Args:
+            log_level: Logging level for events (default: INFO)
+        """
+        self.log_level = log_level
+
+    def handle(self, event: DomainEvent) -> None:
+        """
+        Handle a domain event by logging it.
+
+        Args:
+            event: The domain event to log
+        """
+        event_type = event.__class__.__name__
+        event_data = event.to_dict()
+        # Remove event_type from data if present to avoid duplication
+        event_data.pop("event_type", None)
+
+        # Different events get different log levels
+        if isinstance(event, (ProviderDegraded, ToolInvocationFailed, HealthCheckFailed)):
+            logger.warning("domain_event", event_type=event_type, **event_data)
+        elif isinstance(event, (ProviderStarted, ProviderStopped)):
+            logger.info("domain_event", event_type=event_type, **event_data)
+        elif isinstance(event, (ToolInvocationRequested, ToolInvocationCompleted)):
+            logger.debug("domain_event", event_type=event_type, **event_data)
+        else:
+            logger.info("domain_event", event_type=event_type, **event_data)
+
+    def _format_event(self, event: DomainEvent) -> str:
+        """
+        Format an event for logging (deprecated - kept for compatibility).
+
+        Args:
+            event: The event to format
+
+        Returns:
+            Formatted log message
+        """
+        event_type = event.__class__.__name__
+        return f"[EVENT:{event_type}] {event.to_dict()}"

mcp_hangar/application/event_handlers/metrics_handler.py

@@ -0,0 +1,152 @@
+"""Metrics event handler - collects metrics from domain events."""
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+import time
+from typing import Dict, List
+
+from mcp_hangar.domain.events import (
+    DomainEvent,
+    HealthCheckFailed,
+    HealthCheckPassed,
+    ProviderDegraded,
+    ProviderStarted,
+    ToolInvocationCompleted,
+    ToolInvocationFailed,
+)
+
+
+@dataclass
+class ProviderMetrics:
+    """Metrics for a single provider."""
+
+    provider_id: str
+    total_invocations: int = 0
+    successful_invocations: int = 0
+    failed_invocations: int = 0
+    total_duration_ms: float = 0.0
+    health_checks_passed: int = 0
+    health_checks_failed: int = 0
+    degradation_count: int = 0
+    invocation_latencies: List[float] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate percentage."""
+        if self.total_invocations == 0:
+            return 100.0
+        return (self.successful_invocations / self.total_invocations) * 100
+
+    @property
+    def average_latency_ms(self) -> float:
+        """Calculate average latency in milliseconds."""
+        if self.total_invocations == 0:
+            return 0.0
+        return self.total_duration_ms / self.total_invocations
+
+    @property
+    def p95_latency_ms(self) -> float:
+        """Calculate p95 latency in milliseconds."""
+        if not self.invocation_latencies:
+            return 0.0
+        sorted_latencies = sorted(self.invocation_latencies)
+        index = int(len(sorted_latencies) * 0.95)
+        return sorted_latencies[index] if index < len(sorted_latencies) else sorted_latencies[-1]
+
+
+class MetricsEventHandler:
+    """
+    Event handler that collects metrics from domain events.
+
+    This demonstrates how events can feed into observability systems.
+    In production, this might send to Prometheus, DataDog, etc.
+    """
+
+    def __init__(self):
+        """Initialize the metrics handler."""
+        self._metrics: Dict[str, ProviderMetrics] = defaultdict(lambda: ProviderMetrics(""))
+        self._started_at = time.time()
+
+    def handle(self, event: DomainEvent) -> None:
+        """
+        Handle a domain event by updating metrics.
+
+        Args:
+            event: The domain event to process
+        """
+        if isinstance(event, ProviderStarted):
+            self._handle_provider_started(event)
+        elif isinstance(event, ToolInvocationCompleted):
+            self._handle_tool_completed(event)
+        elif isinstance(event, ToolInvocationFailed):
+            self._handle_tool_failed(event)
+        elif isinstance(event, HealthCheckPassed):
+            self._handle_health_passed(event)
+        elif isinstance(event, HealthCheckFailed):
+            self._handle_health_failed(event)
+        elif isinstance(event, ProviderDegraded):
+            self._handle_provider_degraded(event)
+
+    def _handle_provider_started(self, event: ProviderStarted) -> None:
+        """Handle provider started event."""
+        metrics = self._metrics[event.provider_id]
+        metrics.provider_id = event.provider_id
+
+    def _handle_tool_completed(self, event: ToolInvocationCompleted) -> None:
+        """Handle tool invocation completed event."""
+        metrics = self._metrics[event.provider_id]
+        metrics.total_invocations += 1
+        metrics.successful_invocations += 1
+        metrics.total_duration_ms += event.duration_ms
+        metrics.invocation_latencies.append(event.duration_ms)
+
+        # Keep only last 1000 latencies for memory efficiency
+        if len(metrics.invocation_latencies) > 1000:
+            metrics.invocation_latencies = metrics.invocation_latencies[-1000:]
+
+    def _handle_tool_failed(self, event: ToolInvocationFailed) -> None:
+        """Handle tool invocation failed event."""
+        metrics = self._metrics[event.provider_id]
+        metrics.total_invocations += 1
+        metrics.failed_invocations += 1
+
+    def _handle_health_passed(self, event: HealthCheckPassed) -> None:
+        """Handle health check passed event."""
+        metrics = self._metrics[event.provider_id]
+        metrics.health_checks_passed += 1
+
+    def _handle_health_failed(self, event: HealthCheckFailed) -> None:
+        """Handle health check failed event."""
+        metrics = self._metrics[event.provider_id]
+        metrics.health_checks_failed += 1
+
+    def _handle_provider_degraded(self, event: ProviderDegraded) -> None:
+        """Handle provider degraded event."""
+        metrics = self._metrics[event.provider_id]
+        metrics.degradation_count += 1
+
+    def get_metrics(self, provider_id: str) -> ProviderMetrics | None:
+        """
+        Get metrics for a specific provider.
+
+        Args:
+            provider_id: The provider ID
+
+        Returns:
+            ProviderMetrics if available, None otherwise
+        """
+        return self._metrics.get(provider_id)
+
+    def get_all_metrics(self) -> Dict[str, ProviderMetrics]:
+        """
+        Get metrics for all providers.
+
+        Returns:
+            Dictionary of provider_id -> ProviderMetrics
+        """
+        return dict(self._metrics)
+
+    def reset(self) -> None:
+        """Reset all metrics (mainly for testing)."""
+        self._metrics.clear()
+        self._started_at = time.time()