mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/domain/exceptions.py

@@ -0,0 +1,525 @@
+"""
+Domain exceptions for the MCP Registry.
+
+All domain-specific exceptions should be defined here.
+These exceptions carry context and can be serialized to structured error responses.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class MCPError(Exception):
+    """Base exception for all MCP registry errors.
+
+    Provides structured error information with context for debugging and logging.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        provider_id: str = "",
+        operation: str = "",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.provider_id = provider_id
+        self.operation = operation
+        self.details = details or {}
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to structured error dictionary for API responses."""
+        return {
+            "error": self.message,
+            "provider_id": self.provider_id,
+            "operation": self.operation,
+            "details": self.details,
+            "type": self.__class__.__name__,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"provider_id={self.provider_id!r}, "
+            f"operation={self.operation!r})"
+        )
+
+
+# --- Provider Lifecycle Exceptions ---
+
+
+class ProviderError(MCPError):
+    """Base exception for provider-related errors."""
+
+    pass
+
+
+class ProviderNotFoundError(ProviderError):
+    """Raised when a provider is not found in the registry."""
+
+    def __init__(self, provider_id: str):
+        super().__init__(
+            message=f"Provider not found: {provider_id}",
+            provider_id=provider_id,
+            operation="lookup",
+        )
+
+
+class ProviderStartError(ProviderError):
+    """Raised when a provider fails to start."""
+
+    def __init__(self, provider_id: str, reason: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(
+            message=f"Failed to start provider: {reason}",
+            provider_id=provider_id,
+            operation="start",
+            details=details or {},
+        )
+        self.reason = reason
+
+
+class ProviderDegradedError(ProviderError):
+    """Raised when a provider is in degraded state and cannot accept requests."""
+
+    def __init__(
+        self,
+        provider_id: str,
+        backoff_remaining: float = 0,
+        consecutive_failures: int = 0,
+    ):
+        super().__init__(
+            message=f"Provider is degraded, retry in {backoff_remaining:.1f}s",
+            provider_id=provider_id,
+            operation="ensure_ready",
+            details={
+                "backoff_remaining_s": backoff_remaining,
+                "consecutive_failures": consecutive_failures,
+            },
+        )
+        self.backoff_remaining = backoff_remaining
+        self.consecutive_failures = consecutive_failures
+
+
+class CannotStartProviderError(ProviderError):
+    """Raised when provider cannot be started due to backoff or other constraints."""
+
+    def __init__(self, provider_id: str, reason: str, time_until_retry: float = 0):
+        super().__init__(
+            message=f"Cannot start provider: {reason}",
+            provider_id=provider_id,
+            operation="start",
+            details={"time_until_retry_s": time_until_retry},
+        )
+        self.reason = reason
+        self.time_until_retry = time_until_retry
+
+
+class ProviderNotReadyError(ProviderError):
+    """Raised when an operation requires READY state but provider is not ready."""
+
+    def __init__(self, provider_id: str, current_state: str):
+        super().__init__(
+            message=f"Provider is not ready (state={current_state})",
+            provider_id=provider_id,
+            operation="invoke",
+            details={"current_state": current_state},
+        )
+        self.current_state = current_state
+
+
+class InvalidStateTransitionError(ProviderError):
+    """Raised when an invalid state transition is attempted."""
+
+    def __init__(self, provider_id: str, from_state: str, to_state: str):
+        super().__init__(
+            message=f"Invalid state transition: {from_state} -> {to_state}",
+            provider_id=provider_id,
+            operation="transition",
+            details={"from_state": from_state, "to_state": to_state},
+        )
+        self.from_state = from_state
+        self.to_state = to_state
+
+
+# --- Tool Invocation Exceptions ---
+
+
+class ToolError(MCPError):
+    """Base exception for tool-related errors."""
+
+    pass
+
+
+class ToolNotFoundError(ToolError):
+    """Raised when a tool is not found in the provider's catalog."""
+
+    def __init__(self, provider_id: str, tool_name: str):
+        super().__init__(
+            message=f"Tool not found: {tool_name}",
+            provider_id=provider_id,
+            operation="invoke",
+            details={"tool_name": tool_name},
+        )
+        self.tool_name = tool_name
+
+
+class ToolInvocationError(ToolError):
+    """Raised when a tool invocation fails."""
+
+    def __init__(self, provider_id: str, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(
+            message=message,
+            provider_id=provider_id,
+            operation="invoke",
+            details=details or {},
+        )
+
+
+class ToolTimeoutError(ToolError):
+    """Raised when a tool invocation times out."""
+
+    def __init__(self, provider_id: str, tool_name: str, timeout: float):
+        super().__init__(
+            message=f"Tool invocation timed out after {timeout}s",
+            provider_id=provider_id,
+            operation="invoke",
+            details={"tool_name": tool_name, "timeout_s": timeout},
+        )
+        self.tool_name = tool_name
+        self.timeout = timeout
+
+
+# --- Client/Communication Exceptions ---
+
+
+class ClientError(MCPError):
+    """Raised when the stdio client encounters an error."""
+
+    def __init__(
+        self,
+        message: str,
+        provider_id: str = "",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            provider_id=provider_id,
+            operation="client",
+            details=details or {},
+        )
+
+
+class ClientNotConnectedError(ClientError):
+    """Raised when attempting to use a client that is not connected."""
+
+    def __init__(self, provider_id: str = ""):
+        super().__init__(message="Client is not connected", provider_id=provider_id)
+
+
+class ClientTimeoutError(ClientError):
+    """Raised when a client operation times out."""
+
+    def __init__(self, provider_id: str = "", timeout: float = 0, operation: str = "call"):
+        super().__init__(
+            message=f"Client operation timed out after {timeout}s",
+            provider_id=provider_id,
+            details={"timeout_s": timeout, "operation": operation},
+        )
+        self.timeout = timeout
+
+
+# --- Validation Exceptions ---
+
+
+class ValidationError(MCPError):
+    """Raised when input validation fails."""
+
+    def __init__(
+        self,
+        message: str,
+        field: str = "",
+        value: Any = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        base_details = {"field": field}
+        if value is not None:
+            # Sanitize value for logging (truncate if too long)
+            str_value = str(value)
+            if len(str_value) > 100:
+                str_value = str_value[:100] + "..."
+            base_details["value"] = str_value
+        if details:
+            base_details.update(details)
+
+        super().__init__(message=message, operation="validation", details=base_details)
+        self.field = field
+        self.value = value
+
+
+class ConfigurationError(MCPError):
+    """Raised when configuration is invalid."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(message=message, operation="configuration", details=details or {})
+
+
+# --- Rate Limiting Exceptions ---
+
+
+class RateLimitExceeded(MCPError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, provider_id: str = "", limit: int = 0, window_seconds: int = 0):
+        super().__init__(
+            message=f"Rate limit exceeded: {limit} requests per {window_seconds}s",
+            provider_id=provider_id,
+            operation="rate_limit",
+            details={"limit": limit, "window_seconds": window_seconds},
+        )
+        self.limit = limit
+        self.window_seconds = window_seconds
+
+
+# --- Authentication Exceptions ---
+
+
+class AuthenticationError(MCPError):
+    """Base class for authentication errors.
+
+    All authentication-related failures inherit from this class,
+    enabling unified handling of auth errors.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        auth_method: str = "",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            operation="authentication",
+            details={"auth_method": auth_method, **(details or {})},
+        )
+        self.auth_method = auth_method
+
+
+class InvalidCredentialsError(AuthenticationError):
+    """Credentials are invalid or malformed.
+
+    Raised when:
+    - API key format is invalid
+    - JWT signature verification fails
+    - Token is malformed
+    - Unknown API key
+    """
+
+    def __init__(
+        self,
+        message: str = "Invalid credentials",
+        auth_method: str = "",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            auth_method=auth_method,
+            details=details,
+        )
+
+
+class ExpiredCredentialsError(AuthenticationError):
+    """Credentials have expired.
+
+    Raised when:
+    - JWT exp claim is in the past
+    - API key has passed its expiration date
+    """
+
+    def __init__(
+        self,
+        message: str = "Credentials have expired",
+        auth_method: str = "",
+        expired_at: Optional[float] = None,
+    ):
+        super().__init__(
+            message=message,
+            auth_method=auth_method,
+            details={"expired_at": expired_at} if expired_at else None,
+        )
+        self.expired_at = expired_at
+
+
+class RevokedCredentialsError(AuthenticationError):
+    """Credentials have been revoked.
+
+    Raised when:
+    - API key has been explicitly revoked
+    - JWT is on a revocation list
+    """
+
+    def __init__(
+        self,
+        message: str = "Credentials have been revoked",
+        auth_method: str = "",
+        revoked_at: Optional[float] = None,
+    ):
+        super().__init__(
+            message=message,
+            auth_method=auth_method,
+            details={"revoked_at": revoked_at} if revoked_at else None,
+        )
+        self.revoked_at = revoked_at
+
+
+class MissingCredentialsError(AuthenticationError):
+    """No credentials provided when authentication is required.
+
+    Raised when:
+    - No Authorization header present
+    - No API key header present
+    - Authentication is required but allow_anonymous is False
+    """
+
+    def __init__(
+        self,
+        message: str = "No credentials provided",
+        expected_methods: Optional[list[str]] = None,
+    ):
+        super().__init__(
+            message=message,
+            auth_method="none",
+            details={"expected_methods": expected_methods} if expected_methods else None,
+        )
+        self.expected_methods = expected_methods or []
+
+
+class RateLimitExceededError(AuthenticationError):
+    """Rate limit exceeded for authentication attempts.
+
+    Raised when:
+    - Too many failed authentication attempts from an IP
+    - IP is temporarily locked out
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[float] = None,
+    ):
+        super().__init__(
+            message=message,
+            auth_method="rate_limit",
+            details={"retry_after": retry_after} if retry_after else None,
+        )
+        self.retry_after = retry_after
+
+
+# --- Authorization Exceptions ---
+
+
+class AuthorizationError(MCPError):
+    """Base class for authorization errors.
+
+    All authorization-related failures inherit from this class.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        principal_id: str = "",
+        action: str = "",
+        resource: str = "",
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            operation="authorization",
+            details={
+                "principal_id": principal_id,
+                "action": action,
+                "resource": resource,
+                **(details or {}),
+            },
+        )
+        self.principal_id = principal_id
+        self.action = action
+        self.resource = resource
+
+
+class AccessDeniedError(AuthorizationError):
+    """Principal does not have permission for the requested action.
+
+    The most common authorization error - principal is authenticated
+    but lacks the necessary permissions.
+    """
+
+    def __init__(
+        self,
+        principal_id: str,
+        action: str,
+        resource: str,
+        reason: str = "",
+    ):
+        message = f"Access denied: {principal_id} cannot {action} on {resource}"
+        if reason:
+            message = f"{message} ({reason})"
+        super().__init__(
+            message=message,
+            principal_id=principal_id,
+            action=action,
+            resource=resource,
+            details={"reason": reason} if reason else None,
+        )
+        self.reason = reason
+
+
+class InsufficientScopeError(AuthorizationError):
+    """Token does not have required scope.
+
+    Raised when JWT token scopes don't include the required scope
+    for the requested operation.
+    """
+
+    def __init__(
+        self,
+        principal_id: str,
+        required_scope: str,
+        available_scopes: list[str] | None = None,
+    ):
+        super().__init__(
+            message=f"Insufficient scope: required '{required_scope}'",
+            principal_id=principal_id,
+            action="scope_check",
+            resource=required_scope,
+            details={"available_scopes": available_scopes} if available_scopes else None,
+        )
+        self.required_scope = required_scope
+        self.available_scopes = available_scopes or []
+
+
+class TenantAccessDeniedError(AuthorizationError):
+    """Principal cannot access resources in the specified tenant.
+
+    Raised when a principal attempts to access resources in a tenant
+    they don't belong to.
+    """
+
+    def __init__(
+        self,
+        principal_id: str,
+        principal_tenant: str | None,
+        resource_tenant: str,
+    ):
+        super().__init__(
+            message=f"Access denied: cannot access tenant '{resource_tenant}'",
+            principal_id=principal_id,
+            action="tenant_access",
+            resource=resource_tenant,
+            details={
+                "principal_tenant": principal_tenant,
+                "resource_tenant": resource_tenant,
+            },
+        )
+        self.principal_tenant = principal_tenant
+        self.resource_tenant = resource_tenant

mcp_hangar/domain/model/__init__.py

@@ -0,0 +1,70 @@
+"""Domain model - Aggregates and entities."""
+
+# Re-export ProviderState from value_objects for convenience
+from ..value_objects import GroupState, LoadBalancerStrategy, MemberPriority, MemberWeight, ProviderState
+from .aggregate import AggregateRoot
+from .circuit_breaker import CircuitBreaker, CircuitBreakerConfig, CircuitState
+from .event_sourced_provider import EventSourcedProvider, ProviderSnapshot
+from .health_tracker import HealthTracker
+from .load_balancer import (
+    BaseStrategy,
+    LeastConnectionsStrategy,
+    LoadBalancer,
+    PriorityStrategy,
+    RandomStrategy,
+    RoundRobinStrategy,
+    WeightedRoundRobinStrategy,
+)
+from .provider import Provider
+from .provider_group import (
+    GroupCircuitClosed,
+    GroupCircuitOpened,
+    GroupCreated,
+    GroupMember,
+    GroupMemberAdded,
+    GroupMemberHealthChanged,
+    GroupMemberRemoved,
+    GroupStateChanged,
+    ProviderGroup,
+)
+from .tool_catalog import ToolCatalog, ToolSchema
+
+__all__ = [
+    # Base
+    "AggregateRoot",
+    # Circuit Breaker
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "CircuitState",
+    # Provider
+    "HealthTracker",
+    "ToolCatalog",
+    "ToolSchema",
+    "Provider",
+    "ProviderState",
+    "EventSourcedProvider",
+    "ProviderSnapshot",
+    # Provider Group
+    "ProviderGroup",
+    "GroupMember",
+    "GroupState",
+    "LoadBalancerStrategy",
+    "MemberWeight",
+    "MemberPriority",
+    # Load Balancer
+    "LoadBalancer",
+    "BaseStrategy",
+    "RoundRobinStrategy",
+    "WeightedRoundRobinStrategy",
+    "LeastConnectionsStrategy",
+    "RandomStrategy",
+    "PriorityStrategy",
+    # Group Events
+    "GroupCreated",
+    "GroupMemberAdded",
+    "GroupMemberRemoved",
+    "GroupMemberHealthChanged",
+    "GroupStateChanged",
+    "GroupCircuitOpened",
+    "GroupCircuitClosed",
+]

mcp_hangar/domain/model/aggregate.py

@@ -0,0 +1,58 @@
+"""Base class for aggregate roots in the domain model."""
+
+from abc import ABC
+from typing import List
+
+from ..events import DomainEvent
+
+
+class AggregateRoot(ABC):
+    """
+    Base class for aggregate roots.
+
+    Aggregate roots are the entry points to aggregates and ensure consistency
+    within their boundaries. They collect domain events that can be published
+    after the aggregate is persisted.
+    """
+
+    def __init__(self):
+        self._uncommitted_events: List[DomainEvent] = []
+        self._version: int = 0
+
+    def _record_event(self, event: DomainEvent) -> None:
+        """
+        Record a domain event to be published after persistence.
+
+        Events are collected and published as a batch to ensure consistency.
+        The event bus should handle failures gracefully to avoid breaking
+        the aggregate's core functionality.
+        """
+        self._uncommitted_events.append(event)
+
+    def collect_events(self) -> List[DomainEvent]:
+        """
+        Collect and clear pending domain events.
+
+        This should be called after the aggregate is persisted to publish
+        events to the event bus. Returns a copy and clears internal list.
+        """
+        events = list(self._uncommitted_events)
+        self._uncommitted_events.clear()
+        return events
+
+    def has_uncommitted_events(self) -> bool:
+        """Check if there are uncommitted events."""
+        return len(self._uncommitted_events) > 0
+
+    @property
+    def version(self) -> int:
+        """
+        Get the aggregate version for optimistic concurrency control.
+
+        Version is incremented after each state change.
+        """
+        return self._version
+
+    def _increment_version(self) -> None:
+        """Increment version after state change."""
+        self._version += 1