mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/gc.py

@@ -0,0 +1,134 @@
+"""Background workers for garbage collection and health checks."""
+
+import threading
+import time
+from typing import Any, Literal, Optional
+
+from .domain.contracts.provider_runtime import normalize_state_to_str, ProviderMapping, ProviderRuntime
+from .infrastructure.event_bus import get_event_bus
+from .logging_config import get_logger
+from .metrics import observe_health_check, record_error, record_gc_cycle, record_provider_stop
+
+logger = get_logger(__name__)
+
+
+class BackgroundWorker:
+    """Generic background worker for GC and health checks.
+
+    Expects provider storage that supports `.items()` (dict-like) returning
+    `(provider_id, provider)` pairs where `provider` satisfies the `ProviderRuntime`
+    contract.
+
+    Works with:
+    - Provider aggregates
+    - backward-compatibility wrappers (as long as they implement the contract)
+    """
+
+    def __init__(
+        self,
+        providers: ProviderMapping,
+        interval_s: int = 10,
+        task: Literal["gc", "health_check"] = "gc",
+        event_bus: Optional[Any] = None,
+    ):
+        """
+        Initialize background worker.
+
+        Args:
+            providers: Dict-like mapping (provider_id -> ProviderRuntime).
+            interval_s: Interval between runs in seconds.
+            task: Task type - either "gc" (garbage collection) or "health_check".
+            event_bus: Optional event bus for publishing events (uses global if not provided).
+        """
+        self.providers: ProviderMapping = providers
+        self.interval_s = interval_s
+        self.task = task
+        self._event_bus = event_bus or get_event_bus()
+        self.thread = threading.Thread(target=self._loop, daemon=True, name=f"worker-{task}")
+        self.running = False
+
+    def start(self):
+        """Start the background worker thread."""
+        if self.running:
+            logger.warning("background_worker_already_running", task=self.task)
+            return
+
+        self.running = True
+        self.thread.start()
+        logger.info("background_worker_started", task=self.task, interval_s=self.interval_s)
+
+    def stop(self):
+        """Stop the background worker thread."""
+        self.running = False
+        logger.info("background_worker_stopped", task=self.task)
+
+    def _publish_events(self, provider: ProviderRuntime) -> None:
+        """Publish all collected events from a provider.
+
+        ProviderRuntime is expected to support event collection.
+        """
+        for event in provider.collect_events():
+            try:
+                self._event_bus.publish(event)
+            except Exception:
+                logger.exception("event_publish_failed")
+
+    def _loop(self):
+        """Main worker loop."""
+        while self.running:
+            time.sleep(self.interval_s)
+
+            start_time = time.perf_counter()
+            gc_collected = {"idle": 0, "dead": 0}
+
+            # Get snapshot of providers to avoid holding mapping lock (if any)
+            providers_snapshot = list(self.providers.items())
+
+            for provider_id, provider in providers_snapshot:
+                try:
+                    if self.task == "gc":
+                        # Garbage collection - shutdown idle providers
+                        if provider.maybe_shutdown_idle():
+                            logger.info("gc_shutdown", provider_id=provider_id)
+                            gc_collected["idle"] += 1
+                            record_provider_stop(provider_id, "idle")
+
+                    elif self.task == "health_check":
+                        # Determine whether provider is cold (not started yet)
+                        state_str = normalize_state_to_str(provider.state)
+                        is_cold = state_str == "cold"
+
+                        # Active health check
+                        hc_start = time.perf_counter()
+                        is_healthy = provider.health_check()
+                        hc_duration = time.perf_counter() - hc_start
+
+                        consecutive = int(getattr(provider.health, "consecutive_failures", 0))
+
+                        observe_health_check(
+                            provider=provider_id,
+                            duration=hc_duration,
+                            healthy=is_healthy,
+                            is_cold=is_cold,
+                            consecutive_failures=consecutive,
+                        )
+
+                        if not is_healthy and not is_cold:
+                            logger.warning("health_check_unhealthy", provider_id=provider_id)
+
+                    # Publish any collected events
+                    self._publish_events(provider)
+
+                except Exception as e:
+                    record_error("gc", type(e).__name__)
+                    logger.exception(
+                        "background_task_failed",
+                        provider_id=provider_id,
+                        task=self.task,
+                        error=str(e),
+                    )
+
+            # Record GC cycle metrics
+            if self.task == "gc":
+                duration = time.perf_counter() - start_time
+                record_gc_cycle(duration, gc_collected)

mcp_hangar/infrastructure/__init__.py

@@ -0,0 +1,79 @@
+"""Infrastructure layer - Technical implementations.
+
+This package provides infrastructure components for:
+- Command Bus: CQRS command dispatching
+- Query Bus: CQRS query dispatching
+- Event Bus: Publish/subscribe for domain events
+- Event Store: Append-only event persistence
+- Event Sourced Repository: Provider persistence via event sourcing
+- Saga Manager: Long-running business process orchestration
+
+Note: Command classes (StartProviderCommand, etc.) have been moved to
+application.commands to maintain proper layer separation.
+"""
+
+from .command_bus import CommandBus, CommandHandler, get_command_bus, reset_command_bus
+from .event_bus import EventBus, EventHandler, get_event_bus, reset_event_bus
+from .event_sourced_repository import EventSourcedProviderRepository, ProviderConfigStore
+from .event_store import (
+    ConcurrencyError,
+    EventStore,
+    EventStoreSnapshot,
+    get_event_store,
+    InMemoryEventStore,
+    StoredEvent,
+)
+from .query_bus import (
+    get_query_bus,
+    GetProviderHealthQuery,
+    GetProviderQuery,
+    GetProviderToolsQuery,
+    GetSystemMetricsQuery,
+    ListProvidersQuery,
+    Query,
+    QueryBus,
+    QueryHandler,
+    reset_query_bus,
+)
+from .saga_manager import get_saga_manager, Saga, SagaContext, SagaManager, SagaState, SagaStep
+
+__all__ = [
+    # Command Bus
+    "CommandBus",
+    "CommandHandler",
+    "get_command_bus",
+    "reset_command_bus",
+    # Event Bus
+    "EventBus",
+    "EventHandler",
+    "get_event_bus",
+    "reset_event_bus",
+    # Query Bus
+    "Query",
+    "QueryBus",
+    "QueryHandler",
+    "ListProvidersQuery",
+    "GetProviderQuery",
+    "GetProviderToolsQuery",
+    "GetProviderHealthQuery",
+    "GetSystemMetricsQuery",
+    "get_query_bus",
+    "reset_query_bus",
+    # Event Store
+    "EventStore",
+    "InMemoryEventStore",
+    "StoredEvent",
+    "EventStoreSnapshot",
+    "ConcurrencyError",
+    "get_event_store",
+    # Event Sourced Repository
+    "EventSourcedProviderRepository",
+    "ProviderConfigStore",
+    # Saga
+    "Saga",
+    "SagaManager",
+    "SagaState",
+    "SagaStep",
+    "SagaContext",
+    "get_saga_manager",
+]

mcp_hangar/infrastructure/async_executor.py

@@ -0,0 +1,133 @@
+"""Async executor for running async operations from sync context.
+
+This module provides a clean way to execute async coroutines from
+synchronous code without blocking, using a background thread pool.
+
+This solves the common problem of "Event loop is closed" errors
+when trying to use asyncio from sync handlers.
+
+Usage:
+    from mcp_hangar.infrastructure.async_executor import async_executor
+
+    # Fire-and-forget
+    async_executor.submit(some_coroutine())
+
+    # With callback
+    async_executor.submit(some_coroutine(), on_error=lambda e: logger.error(e))
+"""
+
+import asyncio
+import atexit
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Coroutine, Optional
+
+from ..logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class AsyncExecutor:
+    """Executes async coroutines from sync context using a thread pool.
+
+    This class provides a singleton executor that runs async operations
+    in background threads, each with their own event loop. This avoids
+    the "Event loop is closed" error that occurs when trying to use
+    asyncio from sync code.
+
+    Attributes:
+        _executor: Thread pool for running async operations
+        _max_workers: Maximum number of concurrent background operations
+    """
+
+    _instance: Optional["AsyncExecutor"] = None
+
+    def __init__(self, max_workers: int = 4):
+        """Initialize the async executor.
+
+        Args:
+            max_workers: Maximum number of concurrent background threads
+        """
+        self._max_workers = max_workers
+        self._executor: Optional[ThreadPoolExecutor] = None
+        self._started = False
+
+    @classmethod
+    def get_instance(cls) -> "AsyncExecutor":
+        """Get or create the singleton instance."""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def _ensure_started(self) -> None:
+        """Ensure the thread pool is started."""
+        if not self._started:
+            self._executor = ThreadPoolExecutor(max_workers=self._max_workers, thread_name_prefix="async-executor-")
+            self._started = True
+            # Register cleanup on exit
+            atexit.register(self.shutdown)
+
+    def submit(
+        self,
+        coro: Coroutine[Any, Any, Any],
+        on_success: Optional[Callable[[Any], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        """Submit an async coroutine for background execution.
+
+        The coroutine will be executed in a background thread with its
+        own event loop. This is fire-and-forget by default.
+
+        Args:
+            coro: The coroutine to execute
+            on_success: Optional callback on successful completion
+            on_error: Optional callback on error (default: log debug)
+        """
+        self._ensure_started()
+
+        def run_coro():
+            try:
+                result = asyncio.run(coro)
+                if on_success:
+                    try:
+                        on_success(result)
+                    except (TypeError, ValueError, RuntimeError) as e:
+                        logger.debug("async_executor_callback_error", error=str(e))
+            except (asyncio.CancelledError, asyncio.TimeoutError, ValueError, RuntimeError, OSError) as e:
+                # Handle expected async/runtime errors
+                if on_error:
+                    try:
+                        on_error(e)
+                    except (TypeError, ValueError, RuntimeError) as callback_err:
+                        logger.debug("async_executor_error_callback_failed", error=str(callback_err))
+                else:
+                    logger.debug("async_executor_error", error_type=type(e).__name__, error=str(e))
+
+        self._executor.submit(run_coro)
+
+    def shutdown(self, wait: bool = False) -> None:
+        """Shutdown the executor.
+
+        Args:
+            wait: Whether to wait for pending operations to complete
+        """
+        if self._executor:
+            self._executor.shutdown(wait=wait)
+            self._executor = None
+            self._started = False
+
+
+# Singleton instance for easy access
+async_executor = AsyncExecutor.get_instance()
+
+
+def submit_async(
+    coro: Coroutine[Any, Any, Any],
+    on_error: Optional[Callable[[Exception], None]] = None,
+) -> None:
+    """Convenience function to submit an async operation.
+
+    Args:
+        coro: The coroutine to execute
+        on_error: Optional error callback
+    """
+    async_executor.submit(coro, on_error=on_error)

mcp_hangar/infrastructure/auth/__init__.py

@@ -0,0 +1,37 @@
+"""Authentication infrastructure implementations.
+
+This module provides concrete implementations of authentication contracts
+defined in the domain layer.
+"""
+
+from .api_key_authenticator import ApiKeyAuthenticator, InMemoryApiKeyStore
+from .jwt_authenticator import JWKSTokenValidator, JWTAuthenticator, OIDCConfig
+from .middleware import AuthContext, AuthenticationMiddleware, AuthorizationMiddleware
+from .opa_authorizer import OPAAuthorizer
+from .rate_limiter import AuthRateLimitConfig, AuthRateLimiter
+from .rbac_authorizer import InMemoryRoleStore, RBACAuthorizer
+
+# Persistent stores - imported lazily to avoid dependency issues
+# Use: from mcp_hangar.infrastructure.auth.sqlite_store import SQLiteApiKeyStore
+# Use: from mcp_hangar.infrastructure.auth.postgres_store import PostgresApiKeyStore
+
+__all__ = [
+    # API Key authentication
+    "ApiKeyAuthenticator",
+    "InMemoryApiKeyStore",
+    # JWT/OIDC authentication
+    "JWTAuthenticator",
+    "JWKSTokenValidator",
+    "OIDCConfig",
+    # Middleware
+    "AuthenticationMiddleware",
+    "AuthorizationMiddleware",
+    "AuthContext",
+    # Rate limiting
+    "AuthRateLimiter",
+    "AuthRateLimitConfig",
+    # Authorization
+    "RBACAuthorizer",
+    "InMemoryRoleStore",
+    "OPAAuthorizer",
+]