mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/context.py

@@ -0,0 +1,178 @@
+"""Request context management using contextvars.
+
+This module provides utilities for binding contextual information to log entries
+within a request scope. All logs emitted during request processing will automatically
+include the bound context (request_id, server_name, tool_name, etc.).
+
+Usage:
+    from mcp_hangar.context import bind_request_context, clear_request_context
+
+    async def handle_request(request):
+        bind_request_context(
+            request_id=request.id,
+            server_name="filesystem",
+            tool_name="read_file",
+        )
+        try:
+            # All logs in this scope will include the bound context
+            logger.info("processing_request")
+            result = await process(request)
+            logger.info("request_completed")
+            return result
+        finally:
+            clear_request_context()
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+import uuid
+
+import structlog
+
+# Context variables for request-scoped data
+request_id_var: ContextVar[str | None] = ContextVar("request_id", default=None)
+server_name_var: ContextVar[str | None] = ContextVar("server_name", default=None)
+tool_name_var: ContextVar[str | None] = ContextVar("tool_name", default=None)
+user_id_var: ContextVar[str | None] = ContextVar("user_id", default=None)
+
+
+def generate_request_id() -> str:
+    """Generate a short unique request ID."""
+    return uuid.uuid4().hex[:12]
+
+
+def get_request_id() -> str | None:
+    """Get the current request ID from context."""
+    return request_id_var.get()
+
+
+def bind_request_context(
+    request_id: str | None = None,
+    server_name: str | None = None,
+    tool_name: str | None = None,
+    user_id: str | None = None,
+    **extra: Any,
+) -> str:
+    """Bind contextual information to all logs in the current scope.
+
+    This function sets context variables and binds them to structlog's contextvars,
+    ensuring all subsequent log entries include this information.
+
+    Args:
+        request_id: Unique identifier for the request. Auto-generated if not provided.
+        server_name: Name of the target server/provider.
+        tool_name: Name of the tool being invoked.
+        user_id: Optional user identifier for attribution.
+        **extra: Additional key-value pairs to include in log context.
+
+    Returns:
+        The request_id (either provided or generated).
+
+    Example:
+        request_id = bind_request_context(
+            server_name="filesystem",
+            tool_name="read_file",
+            path="/tmp/test.txt",
+        )
+    """
+    # Generate request_id if not provided
+    if request_id is None:
+        request_id = generate_request_id()
+
+    # Set context variables
+    request_id_var.set(request_id)
+    if server_name is not None:
+        server_name_var.set(server_name)
+    if tool_name is not None:
+        tool_name_var.set(tool_name)
+    if user_id is not None:
+        user_id_var.set(user_id)
+
+    # Build context dict for structlog
+    context: dict[str, Any] = {"request_id": request_id}
+    if server_name is not None:
+        context["server"] = server_name
+    if tool_name is not None:
+        context["tool"] = tool_name
+    if user_id is not None:
+        context["user_id"] = user_id
+    context.update(extra)
+
+    # Clear any previous context and bind new one
+    structlog.contextvars.clear_contextvars()
+    structlog.contextvars.bind_contextvars(**context)
+
+    return request_id
+
+
+def update_request_context(**kwargs: Any) -> None:
+    """Update the current request context with additional information.
+
+    This is useful for adding information that becomes available during processing,
+    such as the routed server name or response status.
+
+    Args:
+        **kwargs: Key-value pairs to add to the context.
+
+    Example:
+        update_request_context(routed_to="memory-server", status="success")
+    """
+    structlog.contextvars.bind_contextvars(**kwargs)
+
+
+def clear_request_context() -> None:
+    """Clear all request-scoped context.
+
+    Should be called at the end of request processing to prevent context leakage.
+    """
+    structlog.contextvars.clear_contextvars()
+    request_id_var.set(None)
+    server_name_var.set(None)
+    tool_name_var.set(None)
+    user_id_var.set(None)
+
+
+class RequestContextManager:
+    """Context manager for automatic request context handling.
+
+    Example:
+        async with RequestContextManager(tool_name="read_file") as ctx:
+            logger.info("processing")
+            # ctx.request_id is available
+    """
+
+    def __init__(
+        self,
+        request_id: str | None = None,
+        server_name: str | None = None,
+        tool_name: str | None = None,
+        user_id: str | None = None,
+        **extra: Any,
+    ):
+        self._request_id = request_id
+        self._server_name = server_name
+        self._tool_name = tool_name
+        self._user_id = user_id
+        self._extra = extra
+        self.request_id: str | None = None
+
+    def __enter__(self) -> "RequestContextManager":
+        self.request_id = bind_request_context(
+            request_id=self._request_id,
+            server_name=self._server_name,
+            tool_name=self._tool_name,
+            user_id=self._user_id,
+            **self._extra,
+        )
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        clear_request_context()
+
+    async def __aenter__(self) -> "RequestContextManager":
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.__exit__(exc_type, exc_val, exc_tb)

mcp_hangar/domain/__init__.py

@@ -0,0 +1,117 @@
+"""Domain layer - Core business logic, events, and exceptions."""
+
+from .events import (
+    DomainEvent,
+    HealthCheckFailed,
+    HealthCheckPassed,
+    ProviderDegraded,
+    ProviderIdleDetected,
+    ProviderStarted,
+    ProviderStateChanged,
+    ProviderStopped,
+    ToolInvocationCompleted,
+    ToolInvocationFailed,
+    ToolInvocationRequested,
+)
+from .exceptions import (  # Client; Base; Provider; Rate Limiting; Tool; Validation
+    CannotStartProviderError,
+    ClientError,
+    ClientNotConnectedError,
+    ClientTimeoutError,
+    ConfigurationError,
+    InvalidStateTransitionError,
+    MCPError,
+    ProviderDegradedError,
+    ProviderError,
+    ProviderNotFoundError,
+    ProviderNotReadyError,
+    ProviderStartError,
+    RateLimitExceeded,
+    ToolError,
+    ToolInvocationError,
+    ToolNotFoundError,
+    ToolTimeoutError,
+    ValidationError,
+)
+from .repository import InMemoryProviderRepository, IProviderRepository
+from .value_objects import (  # Configuration; Timing; Identity; Enums; Tool Arguments
+    CommandLine,
+    CorrelationId,
+    DockerImage,
+    Endpoint,
+    EnvironmentVariables,
+    HealthCheckInterval,
+    HealthStatus,
+    IdleTTL,
+    MaxConsecutiveFailures,
+    ProviderConfig,
+    ProviderId,
+    ProviderMode,
+    ProviderState,
+    TimeoutSeconds,
+    ToolArguments,
+    ToolName,
+)
+
+__all__ = [
+    # Events
+    "DomainEvent",
+    "ProviderStarted",
+    "ProviderStopped",
+    "ProviderDegraded",
+    "ProviderStateChanged",
+    "ToolInvocationRequested",
+    "ToolInvocationCompleted",
+    "ToolInvocationFailed",
+    "HealthCheckPassed",
+    "HealthCheckFailed",
+    "ProviderIdleDetected",
+    # Enums
+    "ProviderState",
+    "ProviderMode",
+    "HealthStatus",
+    # Value Objects - Identity
+    "ProviderId",
+    "ToolName",
+    "CorrelationId",
+    # Value Objects - Configuration
+    "CommandLine",
+    "DockerImage",
+    "Endpoint",
+    "EnvironmentVariables",
+    "ProviderConfig",
+    # Value Objects - Timing
+    "IdleTTL",
+    "HealthCheckInterval",
+    "MaxConsecutiveFailures",
+    "TimeoutSeconds",
+    # Value Objects - Tool Arguments
+    "ToolArguments",
+    # Exceptions - Base
+    "MCPError",
+    # Exceptions - Provider
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ProviderStartError",
+    "ProviderDegradedError",
+    "CannotStartProviderError",
+    "ProviderNotReadyError",
+    "InvalidStateTransitionError",
+    # Exceptions - Tool
+    "ToolError",
+    "ToolNotFoundError",
+    "ToolInvocationError",
+    "ToolTimeoutError",
+    # Exceptions - Client
+    "ClientError",
+    "ClientNotConnectedError",
+    "ClientTimeoutError",
+    # Exceptions - Validation
+    "ValidationError",
+    "ConfigurationError",
+    # Exceptions - Rate Limiting
+    "RateLimitExceeded",
+    # Repository
+    "IProviderRepository",
+    "InMemoryProviderRepository",
+]

mcp_hangar/domain/contracts/__init__.py

@@ -0,0 +1,57 @@
+"""Domain contracts - interfaces for external dependencies.
+
+This module defines contracts (abstract interfaces) that the domain layer
+depends on. Implementations are provided by the infrastructure layer.
+"""
+
+from .authentication import ApiKeyMetadata, AuthRequest, IApiKeyStore, IAuthenticator, ITokenValidator
+from .authorization import AuthorizationRequest, AuthorizationResult, IAuthorizer, IPolicyEngine, IRoleStore
+from .event_store import ConcurrencyError, IEventStore, NullEventStore, StreamNotFoundError
+from .metrics_publisher import IMetricsPublisher
+from .persistence import (
+    AuditAction,
+    AuditEntry,
+    ConcurrentModificationError,
+    ConfigurationNotFoundError,
+    IAuditRepository,
+    IProviderConfigRepository,
+    IRecoveryService,
+    IUnitOfWork,
+    PersistenceError,
+    ProviderConfigSnapshot,
+)
+from .provider_runtime import ProviderRuntime
+
+__all__ = [
+    # Authentication contracts
+    "ApiKeyMetadata",
+    "AuthRequest",
+    "IApiKeyStore",
+    "IAuthenticator",
+    "ITokenValidator",
+    # Authorization contracts
+    "AuthorizationRequest",
+    "AuthorizationResult",
+    "IAuthorizer",
+    "IPolicyEngine",
+    "IRoleStore",
+    # Event store
+    "ConcurrencyError",
+    "IEventStore",
+    "NullEventStore",
+    "StreamNotFoundError",
+    # Metrics
+    "IMetricsPublisher",
+    # Persistence
+    "AuditAction",
+    "AuditEntry",
+    "ConcurrentModificationError",
+    "ConfigurationNotFoundError",
+    "IAuditRepository",
+    "IProviderConfigRepository",
+    "IRecoveryService",
+    "IUnitOfWork",
+    "PersistenceError",
+    "ProviderConfigSnapshot",
+    "ProviderRuntime",
+]

mcp_hangar/domain/contracts/authentication.py

@@ -0,0 +1,225 @@
+"""Authentication contracts (ports) for the domain layer.
+
+These protocols define the interfaces for authentication components.
+Infrastructure layer provides concrete implementations.
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+from ..value_objects import Principal
+
+
+@dataclass
+class AuthRequest:
+    """Normalized authentication request.
+
+    Contains all information needed to authenticate a request,
+    abstracted from the transport layer (HTTP, gRPC, etc.).
+
+    Attributes:
+        headers: Request headers as a case-insensitive dict.
+        source_ip: IP address of the request origin.
+        method: HTTP method or equivalent (GET, POST, etc.).
+        path: Request path/endpoint.
+        metadata: Additional context for authentication decisions.
+    """
+
+    headers: dict[str, str]
+    source_ip: str
+    method: str = ""
+    path: str = ""
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class ApiKeyMetadata:
+    """Metadata about an API key (never contains the actual key).
+
+    Attributes:
+        key_id: Unique identifier for the key (not the key itself).
+        name: Human-readable name for the key.
+        principal_id: Principal ID this key authenticates as.
+        created_at: When the key was created.
+        expires_at: Optional expiration datetime.
+        last_used_at: When the key was last used for authentication.
+        revoked: Whether the key has been revoked.
+    """
+
+    key_id: str
+    name: str
+    principal_id: str
+    created_at: datetime
+    expires_at: datetime | None = None
+    last_used_at: datetime | None = None
+    revoked: bool = False
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the key has expired."""
+        if self.expires_at is None:
+            return False
+        from datetime import timezone
+
+        return datetime.now(timezone.utc) > self.expires_at
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the key is valid (not revoked and not expired)."""
+        return not self.revoked and not self.is_expired
+
+
+@runtime_checkable
+class IAuthenticator(Protocol):
+    """Extracts and validates credentials from a request.
+
+    Authenticators are responsible for:
+    1. Detecting if they can handle a request (supports())
+    2. Extracting credentials from the request
+    3. Validating credentials
+    4. Returning an authenticated Principal
+
+    Multiple authenticators can be chained, with the first supporting
+    authenticator handling the request.
+    """
+
+    @abstractmethod
+    def authenticate(self, request: AuthRequest) -> Principal:
+        """Authenticate a request and return the principal.
+
+        Args:
+            request: The incoming request with credentials.
+
+        Returns:
+            Authenticated Principal.
+
+        Raises:
+            InvalidCredentialsError: If credentials are invalid.
+            ExpiredCredentialsError: If credentials have expired.
+            RevokedCredentialsError: If credentials have been revoked.
+            MissingCredentialsError: If required credentials are missing.
+        """
+        ...
+
+    @abstractmethod
+    def supports(self, request: AuthRequest) -> bool:
+        """Check if this authenticator can handle the request.
+
+        Args:
+            request: The incoming request to check.
+
+        Returns:
+            True if this authenticator should handle the request.
+        """
+        ...
+
+
+@runtime_checkable
+class ITokenValidator(Protocol):
+    """Validates tokens (JWT, API keys, etc.).
+
+    Token validators handle the cryptographic verification of tokens
+    without the transport-layer concerns of extracting them from requests.
+    """
+
+    @abstractmethod
+    def validate(self, token: str) -> dict:
+        """Validate token and return claims.
+
+        Args:
+            token: The token string to validate.
+
+        Returns:
+            Dictionary of validated claims from the token.
+
+        Raises:
+            InvalidCredentialsError: If token is invalid or malformed.
+            ExpiredCredentialsError: If token has expired.
+        """
+        ...
+
+
+@runtime_checkable
+class IApiKeyStore(Protocol):
+    """Storage for API keys.
+
+    Handles CRUD operations for API keys. Keys are stored as hashes,
+    never in plaintext. The raw key is only returned once during creation.
+    """
+
+    @abstractmethod
+    def get_principal_for_key(self, key_hash: str) -> Principal | None:
+        """Look up principal for an API key hash.
+
+        Args:
+            key_hash: SHA-256 hash of the API key.
+
+        Returns:
+            Principal associated with the key, or None if not found.
+
+        Raises:
+            ExpiredCredentialsError: If the key has expired.
+            RevokedCredentialsError: If the key has been revoked.
+        """
+        ...
+
+    @abstractmethod
+    def create_key(
+        self,
+        principal_id: str,
+        name: str,
+        expires_at: datetime | None = None,
+        groups: frozenset[str] | None = None,
+        tenant_id: str | None = None,
+    ) -> str:
+        """Create a new API key.
+
+        Args:
+            principal_id: ID for the principal this key authenticates as.
+            name: Human-readable name for the key.
+            expires_at: Optional expiration datetime.
+            groups: Optional groups to assign to the principal.
+            tenant_id: Optional tenant ID for multi-tenancy.
+
+        Returns:
+            The raw API key (only shown once!).
+        """
+        ...
+
+    @abstractmethod
+    def revoke_key(self, key_id: str) -> bool:
+        """Revoke an API key.
+
+        Args:
+            key_id: Unique identifier of the key to revoke.
+
+        Returns:
+            True if key was found and revoked, False if not found.
+        """
+        ...
+
+    @abstractmethod
+    def list_keys(self, principal_id: str) -> list[ApiKeyMetadata]:
+        """List API keys for a principal (metadata only, not the keys).
+
+        Args:
+            principal_id: ID of the principal to list keys for.
+
+        Returns:
+            List of ApiKeyMetadata for the principal's keys.
+        """
+        ...
+
+    @abstractmethod
+    def count_keys(self, principal_id: str) -> int:
+        """Count active (non-revoked) API keys for a principal.
+
+        Args:
+            principal_id: ID of the principal to count keys for.
+
+        Returns:
+            Number of active API keys.
+        """
+        ...