mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/application/services/traced_provider_service.py

@@ -0,0 +1,211 @@
+"""Traced provider service - adds observability to provider operations.
+
+This decorator wraps ProviderService to automatically trace all tool
+invocations and health checks with the configured observability backend.
+
+Example:
+    service = TracedProviderService(
+        provider_service=ProviderService(...),
+        observability=LangfuseObservabilityAdapter(config),
+    )
+
+    # Tool invocations are automatically traced
+    result = service.invoke_tool("math", "add", {"a": 1, "b": 2})
+"""
+
+import logging
+import time
+from typing import Any
+
+from ..ports.observability import ObservabilityPort, TraceContext
+
+logger = logging.getLogger(__name__)
+
+
+class TracedProviderService:
+    """Decorator that adds observability tracing to ProviderService.
+
+    Wraps an existing ProviderService instance and automatically traces:
+    - Tool invocations with input/output and timing
+    - Health checks with results and latency
+    - Provider state transitions
+
+    All tracing is transparent to callers and adds minimal overhead
+    when observability is disabled.
+    """
+
+    def __init__(
+        self,
+        provider_service: "ProviderService",  # noqa: F821
+        observability: ObservabilityPort,
+    ) -> None:
+        """Initialize traced service.
+
+        Args:
+            provider_service: The underlying provider service to wrap.
+            observability: Observability adapter for tracing.
+        """
+        self._service = provider_service
+        self._observability = observability
+
+    # --- Delegated methods (no tracing needed) ---
+
+    def list_providers(self) -> list[dict[str, Any]]:
+        """List all providers with their status."""
+        return self._service.list_providers()
+
+    def start_provider(self, provider_id: str) -> dict[str, Any]:
+        """Start a provider."""
+        return self._service.start_provider(provider_id)
+
+    def stop_provider(self, provider_id: str) -> dict[str, Any]:
+        """Stop a provider."""
+        return self._service.stop_provider(provider_id)
+
+    def get_provider_tools(self, provider_id: str) -> dict[str, Any]:
+        """Get provider tools."""
+        return self._service.get_provider_tools(provider_id)
+
+    # --- Traced methods ---
+
+    def invoke_tool(
+        self,
+        provider_id: str,
+        tool_name: str,
+        arguments: dict[str, Any],
+        timeout: float = 30.0,
+        trace_id: str | None = None,
+        user_id: str | None = None,
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Invoke a tool with full tracing.
+
+        Args:
+            provider_id: Provider identifier.
+            tool_name: Tool name.
+            arguments: Tool arguments.
+            timeout: Timeout in seconds.
+            trace_id: Optional trace ID for correlation.
+            user_id: Optional user ID for attribution.
+            session_id: Optional session ID for grouping.
+
+        Returns:
+            Tool result dictionary.
+
+        Raises:
+            ProviderNotFoundError: If provider doesn't exist.
+            ToolNotFoundError: If tool doesn't exist.
+            ToolInvocationError: If invocation fails.
+        """
+        trace_context = None
+        if trace_id or user_id or session_id:
+            trace_context = TraceContext(
+                trace_id=trace_id or "",
+                user_id=user_id,
+                session_id=session_id,
+            )
+
+        span = self._observability.start_tool_span(
+            provider_name=provider_id,
+            tool_name=tool_name,
+            input_params=arguments,
+            trace_context=trace_context,
+        )
+
+        try:
+            result = self._service.invoke_tool(
+                provider_id=provider_id,
+                tool_name=tool_name,
+                arguments=arguments,
+                timeout=timeout,
+            )
+            span.end_success(output=result)
+            return result
+
+        except Exception as e:
+            span.end_error(error=e)
+            raise
+
+    def health_check(
+        self,
+        provider_id: str,
+        trace_id: str | None = None,
+    ) -> bool:
+        """Perform health check with tracing.
+
+        Args:
+            provider_id: Provider identifier.
+            trace_id: Optional trace ID to attach result to.
+
+        Returns:
+            True if healthy, False otherwise.
+        """
+        start_time = time.perf_counter()
+
+        try:
+            healthy = self._service.health_check(provider_id)
+            latency_ms = (time.perf_counter() - start_time) * 1000
+
+            self._observability.record_health_check(
+                provider_name=provider_id,
+                healthy=healthy,
+                latency_ms=latency_ms,
+                trace_id=trace_id,
+            )
+
+            return healthy
+
+        except Exception as e:
+            latency_ms = (time.perf_counter() - start_time) * 1000
+
+            self._observability.record_health_check(
+                provider_name=provider_id,
+                healthy=False,
+                latency_ms=latency_ms,
+                trace_id=trace_id,
+            )
+
+            logger.error(
+                "Health check failed for provider %s: %s",
+                provider_id,
+                e,
+            )
+            raise
+
+    def check_all_health(
+        self,
+        trace_id: str | None = None,
+    ) -> dict[str, bool]:
+        """Check health of all providers with tracing.
+
+        Args:
+            trace_id: Optional trace ID to attach results to.
+
+        Returns:
+            Dictionary mapping provider_id to health status.
+        """
+        results = {}
+
+        for provider_status in self._service.list_providers():
+            provider_id = provider_status.get("name") or provider_status.get("provider_id")
+            if provider_id:
+                try:
+                    results[provider_id] = self.health_check(provider_id, trace_id)
+                except Exception:
+                    results[provider_id] = False
+
+        return results
+
+    def shutdown_idle_providers(self) -> list[str]:
+        """Shutdown idle providers."""
+        return self._service.shutdown_idle_providers()
+
+    # --- Observability control ---
+
+    def flush_traces(self) -> None:
+        """Flush pending traces to backend."""
+        self._observability.flush()
+
+    def shutdown_tracing(self) -> None:
+        """Shutdown tracing with final flush."""
+        self._observability.shutdown()

mcp_hangar/bootstrap/runtime.py

@@ -0,0 +1,328 @@
+"""Bootstrap helpers for wiring runtime dependencies.
+
+This module centralizes object graph creation (composition root helpers) so that
+the rest of the codebase can avoid module-level singletons and implicit globals.
+
+It intentionally returns plain objects (repository, buses, security plumbing)
+without starting any background threads.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from typing import Any, Optional, Protocol, runtime_checkable
+
+from ..application.event_handlers import get_security_handler
+from ..application.ports.observability import NullObservabilityAdapter, ObservabilityPort
+from ..domain.repository import InMemoryProviderRepository, IProviderRepository
+from ..domain.security.input_validator import InputValidator
+from ..domain.security.rate_limiter import get_rate_limiter, RateLimitConfig
+from ..infrastructure.command_bus import CommandBus, get_command_bus
+from ..infrastructure.event_bus import EventBus, get_event_bus
+from ..infrastructure.persistence import (
+    Database,
+    DatabaseConfig,
+    InMemoryAuditRepository,
+    InMemoryProviderConfigRepository,
+    RecoveryService,
+    SQLiteAuditRepository,
+    SQLiteProviderConfigRepository,
+)
+from ..infrastructure.query_bus import get_query_bus, QueryBus
+
+# =============================================================================
+# Protocol Interfaces for Runtime Dependencies
+# =============================================================================
+
+
+@runtime_checkable
+class IRateLimiter(Protocol):
+    """Interface for rate limiter."""
+
+    def consume(self, key: str) -> Any:
+        """Check rate limit for a key."""
+        ...
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get rate limiter statistics."""
+        ...
+
+
+@runtime_checkable
+class ISecurityHandler(Protocol):
+    """Interface for security event handler."""
+
+    def handle(self, event: Any) -> None:
+        """Handle a security event."""
+        ...
+
+    def log_rate_limit_exceeded(self, limit: int, window_seconds: int) -> None:
+        """Log rate limit exceeded."""
+        ...
+
+    def log_validation_failed(
+        self,
+        field: str,
+        message: str,
+        provider_id: Optional[str] = None,
+        value: Optional[str] = None,
+    ) -> None:
+        """Log validation failure."""
+        ...
+
+
+@runtime_checkable
+class IConfigRepository(Protocol):
+    """Interface for provider config repository."""
+
+    async def save(self, config: Any) -> None:
+        """Save a configuration."""
+        ...
+
+    async def get(self, provider_id: str) -> Optional[Any]:
+        """Get configuration by provider ID."""
+        ...
+
+    async def get_all(self) -> list[Any]:
+        """Get all configurations."""
+        ...
+
+
+@runtime_checkable
+class IAuditRepository(Protocol):
+    """Interface for audit repository."""
+
+    async def append(self, entry: Any) -> None:
+        """Append an audit entry."""
+        ...
+
+
+@dataclass(frozen=True)
+class PersistenceConfig:
+    """Configuration for persistence layer."""
+
+    enabled: bool = False
+    database_path: str = "data/mcp_hangar.db"
+    enable_wal: bool = True
+    auto_recover: bool = True
+
+
+@dataclass(frozen=True)
+class ObservabilityConfig:
+    """Configuration for observability integrations.
+
+    Supports Langfuse for LLM observability and tracing.
+
+    Attributes:
+        langfuse_enabled: Whether Langfuse integration is active.
+        langfuse_public_key: Langfuse public API key.
+        langfuse_secret_key: Langfuse secret API key.
+        langfuse_host: Langfuse host URL.
+        langfuse_sample_rate: Fraction of traces to sample (0.0 to 1.0).
+        langfuse_scrub_inputs: Whether to redact sensitive inputs.
+        langfuse_scrub_outputs: Whether to redact sensitive outputs.
+    """
+
+    langfuse_enabled: bool = False
+    langfuse_public_key: str = ""
+    langfuse_secret_key: str = ""
+    langfuse_host: str = "https://cloud.langfuse.com"
+    langfuse_sample_rate: float = 1.0
+    langfuse_scrub_inputs: bool = False
+    langfuse_scrub_outputs: bool = False
+
+
+@dataclass(frozen=True)
+class Runtime:
+    """Container for runtime dependencies.
+
+    Uses Protocol interfaces for type safety while maintaining flexibility.
+    """
+
+    repository: IProviderRepository
+    event_bus: EventBus
+    command_bus: CommandBus
+    query_bus: QueryBus
+
+    rate_limit_config: RateLimitConfig
+    rate_limiter: IRateLimiter
+
+    input_validator: InputValidator
+    security_handler: ISecurityHandler
+
+    # Persistence components (optional)
+    persistence_config: Optional[PersistenceConfig] = None
+    database: Optional[Database] = None
+    config_repository: Optional[IConfigRepository] = None
+    audit_repository: Optional[IAuditRepository] = None
+    recovery_service: Optional[RecoveryService] = None
+
+    # Observability components (optional)
+    observability_config: Optional[ObservabilityConfig] = None
+    observability: Optional[ObservabilityPort] = None
+
+
+def create_runtime(
+    *,
+    repository: Optional[IProviderRepository] = None,
+    event_bus: Optional[EventBus] = None,
+    command_bus: Optional[CommandBus] = None,
+    query_bus: Optional[QueryBus] = None,
+    persistence_config: Optional[PersistenceConfig] = None,
+    observability_config: Optional[ObservabilityConfig] = None,
+    env: Optional[dict[str, str]] = None,
+) -> Runtime:
+    """Create runtime dependencies explicitly.
+
+    Args:
+        repository: Optional repository override (useful for tests).
+        event_bus: Optional event bus override.
+        command_bus: Optional command bus override.
+        query_bus: Optional query bus override.
+        persistence_config: Optional persistence configuration.
+        observability_config: Optional observability configuration.
+        env: Optional environment mapping (defaults to os.environ).
+
+    Returns:
+        Runtime container.
+    """
+    env = env or os.environ
+
+    repo = repository or InMemoryProviderRepository()
+    eb = event_bus or get_event_bus()
+    cb = command_bus or get_command_bus()
+    qb = query_bus or get_query_bus()
+
+    rate_limit_config = RateLimitConfig(
+        requests_per_second=float(env.get("MCP_RATE_LIMIT_RPS", "10")),
+        burst_size=int(env.get("MCP_RATE_LIMIT_BURST", "20")),
+    )
+    rate_limiter = get_rate_limiter(rate_limit_config)
+
+    input_validator = InputValidator(
+        allow_absolute_paths=env.get("MCP_ALLOW_ABSOLUTE_PATHS", "false").lower() == "true",
+    )
+
+    security_handler = get_security_handler()
+
+    # Configure persistence if enabled
+    persistence_enabled = env.get("MCP_PERSISTENCE_ENABLED", "false").lower() == "true"
+
+    if persistence_config is None and persistence_enabled:
+        persistence_config = PersistenceConfig(
+            enabled=True,
+            database_path=env.get("MCP_DATABASE_PATH", "data/mcp_hangar.db"),
+            enable_wal=env.get("MCP_DATABASE_WAL", "true").lower() == "true",
+            auto_recover=env.get("MCP_AUTO_RECOVER", "true").lower() == "true",
+        )
+
+    database = None
+    config_repository = None
+    audit_repository = None
+    recovery_service = None
+
+    if persistence_config and persistence_config.enabled:
+        db_config = DatabaseConfig(
+            path=persistence_config.database_path,
+            enable_wal=persistence_config.enable_wal,
+        )
+        database = Database(db_config)
+        config_repository = SQLiteProviderConfigRepository(database)
+        audit_repository = SQLiteAuditRepository(database)
+        recovery_service = RecoveryService(
+            database=database,
+            provider_repository=repo,
+            config_repository=config_repository,
+            audit_repository=audit_repository,
+        )
+    else:
+        # Use in-memory repositories for non-persistent mode
+        config_repository = InMemoryProviderConfigRepository()
+        audit_repository = InMemoryAuditRepository()
+
+    # Configure observability if enabled
+    langfuse_enabled = env.get("HANGAR_LANGFUSE_ENABLED", "false").lower() == "true"
+
+    if observability_config is None and langfuse_enabled:
+        observability_config = ObservabilityConfig(
+            langfuse_enabled=True,
+            langfuse_public_key=env.get("LANGFUSE_PUBLIC_KEY", ""),
+            langfuse_secret_key=env.get("LANGFUSE_SECRET_KEY", ""),
+            langfuse_host=env.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+            langfuse_sample_rate=float(env.get("HANGAR_LANGFUSE_SAMPLE_RATE", "1.0")),
+            langfuse_scrub_inputs=env.get("HANGAR_LANGFUSE_SCRUB_INPUTS", "false").lower() == "true",
+            langfuse_scrub_outputs=env.get("HANGAR_LANGFUSE_SCRUB_OUTPUTS", "false").lower() == "true",
+        )
+
+    observability: ObservabilityPort = NullObservabilityAdapter()
+
+    if observability_config and observability_config.langfuse_enabled:
+        try:
+            from ..infrastructure.observability import LangfuseConfig, LangfuseObservabilityAdapter
+
+            langfuse_config = LangfuseConfig(
+                enabled=True,
+                public_key=observability_config.langfuse_public_key,
+                secret_key=observability_config.langfuse_secret_key,
+                host=observability_config.langfuse_host,
+                sample_rate=observability_config.langfuse_sample_rate,
+                scrub_inputs=observability_config.langfuse_scrub_inputs,
+                scrub_outputs=observability_config.langfuse_scrub_outputs,
+            )
+            observability = LangfuseObservabilityAdapter(langfuse_config)
+        except ImportError:
+            import logging
+
+            logging.getLogger(__name__).warning(
+                "Langfuse enabled but package not installed. Install with: pip install mcp-hangar[observability]"
+            )
+
+    return Runtime(
+        repository=repo,
+        event_bus=eb,
+        command_bus=cb,
+        query_bus=qb,
+        rate_limit_config=rate_limit_config,
+        rate_limiter=rate_limiter,
+        input_validator=input_validator,
+        security_handler=security_handler,
+        persistence_config=persistence_config,
+        database=database,
+        config_repository=config_repository,
+        audit_repository=audit_repository,
+        recovery_service=recovery_service,
+        observability_config=observability_config,
+        observability=observability,
+    )
+
+
+async def initialize_runtime(runtime: Runtime) -> None:
+    """Initialize runtime async components.
+
+    Should be called during application startup.
+
+    Args:
+        runtime: Runtime container to initialize
+    """
+    if runtime.database:
+        await runtime.database.initialize()
+
+    if runtime.recovery_service and runtime.persistence_config:
+        if runtime.persistence_config.auto_recover:
+            await runtime.recovery_service.recover_providers()
+
+
+async def shutdown_runtime(runtime: Runtime) -> None:
+    """Shutdown runtime async components.
+
+    Should be called during application shutdown.
+
+    Args:
+        runtime: Runtime container to shutdown
+    """
+    if runtime.observability:
+        runtime.observability.shutdown()
+
+    if runtime.database:
+        await runtime.database.close()