claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/event_bus/relay.py

@@ -0,0 +1,326 @@
+"""Socket.IO Relay - Consumes events from EventBus and relays to Socket.IO.
+
+WHY separate relay component:
+- Single point of Socket.IO connection management
+- Isolates Socket.IO failures from event producers
+- Enables graceful degradation when Socket.IO unavailable
+- Simplifies testing by mocking just the relay
+- Supports batching and retry logic in one place
+"""
+
+import os
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+# Socket.IO imports
+try:
+    import socketio
+
+    SOCKETIO_AVAILABLE = True
+except ImportError:
+    SOCKETIO_AVAILABLE = False
+    socketio = None
+
+import contextlib
+
+# Configure logger
+from claude_mpm.core.logging_utils import get_logger
+
+from .event_bus import EventBus
+
+logger = get_logger(__name__)
+
+
+class SocketIORelay:
+    """Relay events from EventBus to Socket.IO clients.
+
+    WHY relay pattern:
+    - Decouples event production from Socket.IO emission
+    - Handles connection failures without affecting producers
+    - Provides single point for Socket.IO configuration
+    - Enables event batching and optimization
+    - Simplifies debugging with centralized logging
+    """
+
+    def __init__(self, port: Optional[int] = None):
+        """Initialize the Socket.IO relay.
+
+        Args:
+            port: Socket.IO server port (defaults to env var or 8765)
+        """
+        self.port = port or int(os.environ.get("CLAUDE_MPM_SOCKETIO_PORT", "8765"))
+        self.event_bus = EventBus.get_instance()
+        self.client: Optional[Any] = None
+        self.connected = False
+        self.enabled = True
+        self.debug = os.environ.get("CLAUDE_MPM_RELAY_DEBUG", "false").lower() == "true"
+
+        # Connection retry settings
+        self.max_retries = 3
+        self.retry_delay = 0.5
+        self.last_connection_attempt = 0
+        self.connection_cooldown = 5.0  # Seconds between connection attempts
+
+        # Statistics
+        self.stats = {
+            "events_relayed": 0,
+            "events_failed": 0,
+            "connection_failures": 0,
+            "last_relay_time": None,
+        }
+
+        if not SOCKETIO_AVAILABLE:
+            logger.warning("Socket.IO not available, relay will be disabled")
+            self.enabled = False
+
+    def enable(self) -> None:
+        """Enable the relay."""
+        if not SOCKETIO_AVAILABLE:
+            logger.warning("Cannot enable relay: Socket.IO not available")
+            return
+        self.enabled = True
+        logger.info("SocketIO relay enabled")
+
+    def disable(self) -> None:
+        """Disable the relay."""
+        self.enabled = False
+        if self.client and self.connected:
+            with contextlib.suppress(Exception):
+                self.client.disconnect()
+        logger.info("SocketIO relay disabled")
+
+    def _create_client(self) -> bool:
+        """Create and connect Socket.IO client.
+
+        Returns:
+            bool: True if connection successful
+        """
+        if not SOCKETIO_AVAILABLE or not self.enabled:
+            return False
+
+        # Check connection cooldown
+        current_time = time.time()
+        if current_time - self.last_connection_attempt < self.connection_cooldown:
+            return False
+
+        self.last_connection_attempt = current_time
+
+        try:
+            # Create new client with better connection settings
+            self.client = socketio.Client(
+                reconnection=True,
+                reconnection_attempts=5,
+                reconnection_delay=2,
+                reconnection_delay_max=10,
+                logger=False,
+                engineio_logger=False,
+            )
+
+            # Connect to server with longer timeout
+            self.client.connect(
+                f"http://localhost:{self.port}",
+                wait=True,
+                wait_timeout=10.0,  # Increase timeout for stability
+                transports=["websocket", "polling"],
+            )
+
+            self.connected = True
+            logger.info(f"SocketIO relay connected to port {self.port}")
+            return True
+
+        except Exception as e:
+            self.stats["connection_failures"] += 1
+            if self.debug:
+                logger.debug(f"Failed to connect to Socket.IO server: {e}")
+            self.connected = False
+            self.client = None
+            return False
+
+    def _ensure_connection(self) -> bool:
+        """Ensure Socket.IO client is connected.
+
+        Returns:
+            bool: True if connected or reconnected
+        """
+        if not self.enabled:
+            return False
+
+        # Check existing connection
+        if self.client and self.connected:
+            try:
+                # Verify connection is still alive
+                if self.client.connected:
+                    return True
+            except Exception:
+                pass
+
+        # Need to create or reconnect
+        return self._create_client()
+
+    async def relay_event(self, event_type: str, data: Any) -> bool:
+        """Relay an event to Socket.IO.
+
+        Args:
+            event_type: The event type
+            data: The event data
+
+        Returns:
+            bool: True if successfully relayed
+        """
+        if not self.enabled:
+            return False
+
+        # Ensure we have a connection
+        if not self._ensure_connection():
+            self.stats["events_failed"] += 1
+            return False
+
+        try:
+            # Emit to Socket.IO
+            self.client.emit(
+                "claude_event",
+                {
+                    "event": "claude_event",
+                    "type": (
+                        event_type.split(".")[0] if "." in event_type else event_type
+                    ),
+                    "subtype": (
+                        event_type.split(".", 1)[1] if "." in event_type else "generic"
+                    ),
+                    "timestamp": data.get(
+                        "timestamp", datetime.now(timezone.utc).isoformat()
+                    ),
+                    "data": data,
+                    "source": "event_bus",
+                },
+            )
+
+            # Update statistics
+            self.stats["events_relayed"] += 1
+            self.stats["last_relay_time"] = datetime.now(timezone.utc).isoformat()
+
+            if self.debug:
+                logger.debug(f"Relayed event to Socket.IO: {event_type}")
+
+            return True
+
+        except Exception as e:
+            self.stats["events_failed"] += 1
+            if self.debug:
+                logger.debug(f"Failed to relay event {event_type}: {e}")
+            # Mark connection as failed for retry
+            self.connected = False
+            return False
+
+    def start(self) -> None:
+        """Start the relay by subscribing to EventBus events.
+
+        This sets up listeners for all hook events and relays them
+        to Socket.IO clients.
+        """
+        if not self.enabled:
+            logger.warning("Cannot start relay: disabled or Socket.IO not available")
+            return
+
+        # Define async handler for events
+        async def handle_hook_event(event_type: str, data: Any):
+            """Handle events from the event bus."""
+            # Debug logging
+            print(f"[Relay] Received event: {event_type}", flush=True)
+
+            # Only relay hook events by default
+            if event_type.startswith("hook."):
+                print(f"[Relay] Relaying hook event: {event_type}", flush=True)
+                await self.relay_event(event_type, data)
+
+        # Subscribe to all hook events via wildcard
+        # This will catch ALL hook.* events
+        self.event_bus.on("hook.*", handle_hook_event)
+
+        logger.info("SocketIO relay started and subscribed to events")
+        print("[Relay] Started and subscribed to hook.* events", flush=True)
+
+    def stop(self) -> None:
+        """Stop the relay and clean up resources."""
+        # Disconnect Socket.IO client
+        if self.client and self.connected:
+            with contextlib.suppress(Exception):
+                self.client.disconnect()
+
+        # Could remove event bus listeners here if needed
+        # For now, let them be cleaned up naturally
+
+        self.connected = False
+        self.client = None
+        logger.info("SocketIO relay stopped")
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get relay statistics.
+
+        Returns:
+            dict: Statistics about relay operation
+        """
+        return {
+            **self.stats,
+            "enabled": self.enabled,
+            "connected": self.connected,
+            "port": self.port,
+        }
+
+
+# Global relay instance
+_relay_instance: Optional[SocketIORelay] = None
+_relay_lock = threading.Lock()
+
+
+def get_relay(port: Optional[int] = None) -> SocketIORelay:
+    """Get or create the global SocketIO relay instance.
+
+    Thread-safe implementation using double-checked locking pattern to
+    prevent race conditions during concurrent initialization.
+
+    Args:
+        port: Optional port number
+
+    Returns:
+        SocketIORelay: The relay instance
+    """
+    global _relay_instance
+
+    # Fast path - check without lock
+    if _relay_instance is not None:
+        return _relay_instance
+
+    # Slow path - acquire lock and double-check
+    with _relay_lock:
+        if _relay_instance is None:
+            _relay_instance = SocketIORelay(port)
+        return _relay_instance
+
+
+def start_relay(port: Optional[int] = None) -> SocketIORelay:
+    """Start the global SocketIO relay.
+
+    Args:
+        port: Optional port number
+
+    Returns:
+        SocketIORelay: The started relay instance
+    """
+    relay = get_relay(port)
+    relay.start()
+    return relay
+
+
+def stop_relay() -> None:
+    """Stop the global SocketIO relay.
+
+    Thread-safe implementation ensures proper cleanup.
+    """
+    global _relay_instance
+    with _relay_lock:
+        if _relay_instance:
+            _relay_instance.stop()
+            _relay_instance = None

claude_mpm/services/events/__init__.py

@@ -0,0 +1,44 @@
+"""
+Event Bus System for Claude MPM
+===============================
+
+A decoupled event system that separates event producers from consumers,
+providing reliable, testable, and maintainable event handling.
+
+Key Components:
+- EventBus: Core pub/sub system
+- Event: Standard event format
+- IEventProducer: Interface for event producers
+- IEventConsumer: Interface for event consumers
+- Various consumer implementations
+"""
+
+from .consumers import (
+    DeadLetterConsumer,
+    LoggingConsumer,
+    MetricsConsumer,
+    SocketIOConsumer,
+)
+from .core import Event, EventBus, EventMetadata, EventPriority
+from .interfaces import ConsumerConfig, IEventConsumer, IEventProducer
+from .producers import HookEventProducer, SystemEventProducer
+
+__all__ = [
+    "ConsumerConfig",
+    "DeadLetterConsumer",
+    # Core
+    "Event",
+    "EventBus",
+    "EventMetadata",
+    "EventPriority",
+    # Producers
+    "HookEventProducer",
+    # Interfaces
+    "IEventConsumer",
+    "IEventProducer",
+    "LoggingConsumer",
+    "MetricsConsumer",
+    # Consumers
+    "SocketIOConsumer",
+    "SystemEventProducer",
+]

claude_mpm/services/events/consumers/__init__.py

@@ -0,0 +1,18 @@
+"""
+Event Bus Consumers
+==================
+
+Various consumer implementations for processing events from the event bus.
+"""
+
+from .dead_letter import DeadLetterConsumer
+from .logging import LoggingConsumer
+from .metrics import MetricsConsumer
+from .socketio import SocketIOConsumer
+
+__all__ = [
+    "DeadLetterConsumer",
+    "LoggingConsumer",
+    "MetricsConsumer",
+    "SocketIOConsumer",
+]

claude_mpm/services/events/consumers/dead_letter.py

@@ -0,0 +1,306 @@
+"""
+Dead Letter Queue Consumer
+=========================
+
+Handles events that failed processing in other consumers.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logging_config import get_logger
+
+from ..core import Event
+from ..interfaces import ConsumerConfig, ConsumerPriority, IEventConsumer
+
+
+class DeadLetterConsumer(IEventConsumer):
+    """
+    Handles failed events by persisting them for later analysis.
+
+    Features:
+    - Persist failed events to disk
+    - Configurable retention policy
+    - Event replay capability
+    - Failed event analysis
+    """
+
+    def __init__(
+        self,
+        output_dir: Optional[Path] = None,
+        max_file_size: int = 10 * 1024 * 1024,  # 10MB
+        retention_days: int = 7,
+        topics: Optional[List[str]] = None,
+    ):
+        """
+        Initialize dead letter consumer.
+
+        Args:
+            output_dir: Directory to store failed events
+            max_file_size: Maximum size per file (bytes)
+            retention_days: How long to keep failed events
+            topics: Topics to handle (None = all failed events)
+        """
+        self.logger = get_logger("DeadLetterConsumer")
+
+        # Configuration
+        self.output_dir = output_dir or Path.home() / ".claude-mpm" / "dead-letter"
+        self.max_file_size = max_file_size
+        self.retention_days = retention_days
+
+        # State
+        self._initialized = False
+        self._current_file: Optional[Path] = None
+        self._current_file_size = 0
+
+        # Metrics
+        self._metrics = {
+            "events_stored": 0,
+            "events_replayed": 0,
+            "files_created": 0,
+            "total_size_bytes": 0,
+        }
+
+        # Consumer configuration
+        self._config = ConsumerConfig(
+            name="DeadLetterConsumer",
+            topics=topics or ["error.**", "failed.**"],
+            priority=ConsumerPriority.CRITICAL,  # Process failed events first
+            filter_func=self._should_store,
+        )
+
+    async def initialize(self) -> bool:
+        """Initialize the dead letter consumer."""
+        try:
+            # Create output directory
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+
+            # Clean old files
+            await self._cleanup_old_files()
+
+            # Initialize current file
+            self._rotate_file()
+
+            self._initialized = True
+            self.logger.info(
+                f"Dead letter consumer initialized (output: {self.output_dir})"
+            )
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Failed to initialize dead letter consumer: {e}")
+            return False
+
+    async def consume(self, event: Event) -> bool:
+        """Store a failed event."""
+        if not self._initialized:
+            return False
+
+        try:
+            # Serialize event
+            event_data = self._serialize_event(event)
+            event_json = json.dumps(event_data) + "\n"
+            event_bytes = event_json.encode("utf-8")
+
+            # Check if rotation needed
+            if self._current_file_size + len(event_bytes) > self.max_file_size:
+                self._rotate_file()
+
+            # Write to file
+            with self._current_file.open("a") as f:
+                f.write(event_json)
+
+            # Update metrics
+            self._current_file_size += len(event_bytes)
+            self._metrics["events_stored"] += 1
+            self._metrics["total_size_bytes"] += len(event_bytes)
+
+            self.logger.debug(
+                f"Stored failed event: {event.topic}/{event.type} "
+                f"(reason: {event.metadata.error_messages if event.metadata else 'unknown'})"
+            )
+
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Error storing failed event: {e}")
+            return False
+
+    async def consume_batch(self, events: List[Event]) -> int:
+        """Store multiple failed events."""
+        successful = 0
+        for event in events:
+            if await self.consume(event):
+                successful += 1
+        return successful
+
+    async def shutdown(self) -> None:
+        """Shutdown the consumer."""
+        self.logger.info(
+            f"Dead letter consumer shutdown - stored {self._metrics['events_stored']} events"
+        )
+        self._initialized = False
+
+    async def replay_events(
+        self,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        topic_filter: Optional[str] = None,
+    ) -> List[Event]:
+        """
+        Replay stored events for reprocessing.
+
+        Args:
+            start_time: Start of time range
+            end_time: End of time range
+            topic_filter: Topic pattern to filter
+
+        Returns:
+            List of events matching criteria
+        """
+        replayed_events = []
+
+        # Find files in time range
+        for file_path in sorted(self.output_dir.glob("dead-letter-*.jsonl")):
+            try:
+                with file_path.open() as f:
+                    for line in f:
+                        event_data = json.loads(line)
+
+                        # Apply filters
+                        event_time = datetime.fromisoformat(event_data["timestamp"])
+
+                        if start_time and event_time < start_time:
+                            continue
+                        if end_time and event_time > end_time:
+                            continue
+                        if topic_filter and not event_data["topic"].startswith(
+                            topic_filter
+                        ):
+                            continue
+
+                        # Reconstruct event
+                        event = self._deserialize_event(event_data)
+                        replayed_events.append(event)
+
+            except Exception as e:
+                self.logger.error(f"Error replaying events from {file_path}: {e}")
+
+        self._metrics["events_replayed"] += len(replayed_events)
+        self.logger.info(f"Replayed {len(replayed_events)} events")
+
+        return replayed_events
+
+    @property
+    def config(self) -> ConsumerConfig:
+        """Get consumer configuration."""
+        return self._config
+
+    @property
+    def is_healthy(self) -> bool:
+        """Check if consumer is healthy."""
+        return self._initialized and self._current_file is not None
+
+    def get_metrics(self) -> Dict[str, Any]:
+        """Get consumer metrics."""
+        return {
+            **self._metrics,
+            "current_file": str(self._current_file) if self._current_file else None,
+            "current_file_size": self._current_file_size,
+        }
+
+    def _should_store(self, event: Event) -> bool:
+        """
+        Determine if an event should be stored.
+
+        Only store events that have actually failed processing.
+        """
+        if not event.metadata:
+            return False
+
+        # Store if any consumers failed
+        if event.metadata.consumers_failed:
+            return True
+
+        # Store if max retries exceeded
+        if event.metadata.retry_count >= event.metadata.max_retries:
+            return True
+
+        # Store if event has error messages
+        return bool(event.metadata.error_messages)
+
+    def _serialize_event(self, event: Event) -> Dict[str, Any]:
+        """Serialize an event for storage."""
+        return {
+            "id": event.id,
+            "topic": event.topic,
+            "type": event.type,
+            "timestamp": event.timestamp.isoformat(),
+            "source": event.source,
+            "data": event.data,
+            "correlation_id": event.correlation_id,
+            "priority": event.priority.name,
+            "metadata": (
+                {
+                    "retry_count": event.metadata.retry_count if event.metadata else 0,
+                    "consumers_failed": (
+                        list(event.metadata.consumers_failed) if event.metadata else []
+                    ),
+                    "error_messages": (
+                        event.metadata.error_messages if event.metadata else []
+                    ),
+                }
+                if event.metadata
+                else None
+            ),
+        }
+
+    def _deserialize_event(self, data: Dict[str, Any]) -> Event:
+        """Deserialize an event from storage."""
+        from ..core import EventMetadata, EventPriority
+
+        # Reconstruct metadata
+        metadata = None
+        if data.get("metadata"):
+            metadata = EventMetadata(
+                retry_count=data["metadata"].get("retry_count", 0),
+                consumers_failed=set(data["metadata"].get("consumers_failed", [])),
+                error_messages=data["metadata"].get("error_messages", []),
+            )
+
+        return Event(
+            id=data["id"],
+            topic=data["topic"],
+            type=data["type"],
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            source=data["source"],
+            data=data["data"],
+            metadata=metadata,
+            correlation_id=data.get("correlation_id"),
+            priority=EventPriority[data.get("priority", "NORMAL")],
+        )
+
+    def _rotate_file(self) -> None:
+        """Rotate to a new output file."""
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+        self._current_file = self.output_dir / f"dead-letter-{timestamp}.jsonl"
+        self._current_file_size = 0
+        self._metrics["files_created"] += 1
+
+        self.logger.debug(f"Rotated to new file: {self._current_file}")
+
+    async def _cleanup_old_files(self) -> None:
+        """Remove files older than retention period."""
+        cutoff_time = datetime.now(timezone.utc).timestamp() - (
+            self.retention_days * 86400
+        )
+
+        for file_path in self.output_dir.glob("dead-letter-*.jsonl"):
+            try:
+                if file_path.stat().st_mtime < cutoff_time:
+                    file_path.unlink()
+                    self.logger.info(f"Removed old dead letter file: {file_path}")
+            except Exception as e:
+                self.logger.error(f"Error removing old file {file_path}: {e}")