mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/application/queries/auth_queries.py

@@ -0,0 +1,118 @@
+"""Authentication and Authorization queries.
+
+Queries represent read operations in CQRS pattern.
+They do not modify state, only retrieve data.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Query:
+    """Base class for all queries."""
+
+    pass
+
+
+# =============================================================================
+# API Key Queries
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class GetApiKeysByPrincipalQuery(Query):
+    """Query to get all API keys for a principal.
+
+    Attributes:
+        principal_id: Principal whose keys to retrieve.
+        include_revoked: Whether to include revoked keys.
+    """
+
+    principal_id: str
+    include_revoked: bool = True
+
+
+@dataclass(frozen=True)
+class GetApiKeyCountQuery(Query):
+    """Query to get count of active API keys for a principal.
+
+    Attributes:
+        principal_id: Principal whose keys to count.
+    """
+
+    principal_id: str
+
+
+# =============================================================================
+# Role Queries
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class GetRolesForPrincipalQuery(Query):
+    """Query to get all roles assigned to a principal.
+
+    Attributes:
+        principal_id: Principal whose roles to retrieve.
+        scope: Optional scope filter (use "*" for all scopes).
+    """
+
+    principal_id: str
+    scope: str = "*"
+
+
+@dataclass(frozen=True)
+class GetRoleQuery(Query):
+    """Query to get a specific role by name.
+
+    Attributes:
+        role_name: Name of the role to retrieve.
+    """
+
+    role_name: str
+
+
+@dataclass(frozen=True)
+class ListBuiltinRolesQuery(Query):
+    """Query to list all built-in roles."""
+
+    pass
+
+
+@dataclass(frozen=True)
+class CheckPermissionQuery(Query):
+    """Query to check if a principal has a specific permission.
+
+    Attributes:
+        principal_id: Principal to check.
+        action: Action being requested.
+        resource_type: Type of resource.
+        resource_id: Specific resource ID.
+    """
+
+    principal_id: str
+    action: str
+    resource_type: str
+    resource_id: str = "*"
+
+
+# =============================================================================
+# Audit Queries
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class GetAuthAuditLogQuery(Query):
+    """Query to get authentication audit log entries.
+
+    Attributes:
+        principal_id: Optional filter by principal.
+        event_type: Optional filter by event type.
+        limit: Maximum number of entries.
+        since_timestamp: Optional filter for entries after this time.
+    """
+
+    principal_id: str | None = None
+    event_type: str | None = None
+    limit: int = 100
+    since_timestamp: float | None = None

mcp_hangar/application/queries/handlers.py

@@ -0,0 +1,227 @@
+"""Query handlers implementation."""
+
+import time
+from typing import Dict, List
+
+from ...domain.exceptions import ProviderNotFoundError
+from ...domain.policies.provider_health import to_health_status_string
+from ...domain.repository import IProviderRepository
+from ...infrastructure.query_bus import (
+    GetProviderHealthQuery,
+    GetProviderQuery,
+    GetProviderToolsQuery,
+    GetSystemMetricsQuery,
+    ListProvidersQuery,
+    QueryBus,
+    QueryHandler,
+)
+from ...logging_config import get_logger
+from ..read_models import HealthInfo, ProviderDetails, ProviderSummary, SystemMetrics, ToolInfo
+
+logger = get_logger(__name__)
+
+
+class BaseQueryHandler(QueryHandler):
+    """Base class for query handlers."""
+
+    def __init__(self, repository: IProviderRepository):
+        self._repository = repository
+
+    def _get_provider(self, provider_id: str):
+        """Get provider or raise ProviderNotFoundError."""
+        provider = self._repository.get(provider_id)
+        if provider is None:
+            raise ProviderNotFoundError(provider_id)
+        return provider
+
+    def _get_health_status(self, provider) -> str:
+        """Determine health status string.
+
+        Delegates classification to a domain policy to keep CQRS query layer free
+        from business interpretation logic.
+        """
+        return to_health_status_string(
+            state=provider.state,
+            consecutive_failures=provider.health.consecutive_failures,
+        )
+
+    def _build_health_info(self, provider) -> HealthInfo:
+        """Build HealthInfo from provider."""
+        health = provider.health
+        now = time.time()
+
+        last_success_ago = None
+        if health.last_success_at:
+            last_success_ago = now - health.last_success_at
+
+        last_failure_ago = None
+        if health.last_failure_at:
+            last_failure_ago = now - health.last_failure_at
+
+        return HealthInfo(
+            consecutive_failures=health.consecutive_failures,
+            total_invocations=health.total_invocations,
+            total_failures=health.total_failures,
+            success_rate=health.success_rate,
+            can_retry=health.can_retry(),
+            last_success_ago=last_success_ago,
+            last_failure_ago=last_failure_ago,
+        )
+
+    def _build_tool_info(self, tool) -> ToolInfo:
+        """Build ToolInfo from tool schema."""
+        return ToolInfo(
+            name=tool.name,
+            description=tool.description,
+            input_schema=tool.input_schema,
+            output_schema=tool.output_schema,
+        )
+
+
+class ListProvidersHandler(BaseQueryHandler):
+    """Handler for ListProvidersQuery."""
+
+    def handle(self, query: ListProvidersQuery) -> List[ProviderSummary]:
+        """
+        List all providers with optional state filtering.
+
+        Returns:
+            List of ProviderSummary
+        """
+        result = []
+        for provider_id, provider in self._repository.get_all().items():
+            state = provider.state.value
+
+            # Apply filter if specified
+            if query.state_filter and state != query.state_filter:
+                continue
+
+            summary = ProviderSummary(
+                provider_id=provider_id,
+                state=state,
+                mode=provider.mode.value,
+                is_alive=provider.is_alive,
+                tools_count=provider.tools.count(),
+                health_status=self._get_health_status(provider),
+                description=provider.description,
+                tools_predefined=provider.tools_predefined,
+            )
+            result.append(summary)
+
+        return result
+
+
+class GetProviderHandler(BaseQueryHandler):
+    """Handler for GetProviderQuery."""
+
+    def handle(self, query: GetProviderQuery) -> ProviderDetails:
+        """
+        Get detailed information about a provider.
+
+        Returns:
+            ProviderDetails
+        """
+        provider = self._get_provider(query.provider_id)
+
+        tools = [self._build_tool_info(t) for t in provider.tools]
+        health = self._build_health_info(provider)
+
+        return ProviderDetails(
+            provider_id=query.provider_id,
+            state=provider.state.value,
+            mode=provider.mode.value,
+            is_alive=provider.is_alive,
+            tools=tools,
+            health=health,
+            idle_time=provider.idle_time,
+            meta=provider.meta,
+        )
+
+
+class GetProviderToolsHandler(BaseQueryHandler):
+    """Handler for GetProviderToolsQuery."""
+
+    def handle(self, query: GetProviderToolsQuery) -> List[ToolInfo]:
+        """
+        Get tools for a specific provider.
+
+        Returns:
+            List of ToolInfo
+        """
+        provider = self._get_provider(query.provider_id)
+        return [self._build_tool_info(t) for t in provider.tools]
+
+
+class GetProviderHealthHandler(BaseQueryHandler):
+    """Handler for GetProviderHealthQuery."""
+
+    def handle(self, query: GetProviderHealthQuery) -> HealthInfo:
+        """
+        Get health information for a provider.
+
+        Returns:
+            HealthInfo
+        """
+        provider = self._get_provider(query.provider_id)
+        return self._build_health_info(provider)
+
+
+class GetSystemMetricsHandler(BaseQueryHandler):
+    """Handler for GetSystemMetricsQuery."""
+
+    def handle(self, query: GetSystemMetricsQuery) -> SystemMetrics:
+        """
+        Get system-wide metrics.
+
+        Returns:
+            SystemMetrics
+        """
+        providers = self._repository.get_all()
+
+        total_providers = len(providers)
+        providers_by_state: Dict[str, int] = {}
+        total_tools = 0
+        total_invocations = 0
+        total_failures = 0
+
+        for provider in providers.values():
+            # Count by state
+            state = provider.state.value
+            providers_by_state[state] = providers_by_state.get(state, 0) + 1
+
+            # Sum metrics
+            total_tools += provider.tools.count()
+            total_invocations += provider.health.total_invocations
+            total_failures += provider.health.total_failures
+
+        # Calculate overall success rate
+        if total_invocations > 0:
+            overall_success_rate = (total_invocations - total_failures) / total_invocations
+        else:
+            overall_success_rate = 1.0
+
+        return SystemMetrics(
+            total_providers=total_providers,
+            providers_by_state=providers_by_state,
+            total_tools=total_tools,
+            total_invocations=total_invocations,
+            total_failures=total_failures,
+            overall_success_rate=overall_success_rate,
+        )
+
+
+def register_all_handlers(query_bus: QueryBus, repository: IProviderRepository) -> None:
+    """
+    Register all query handlers with the query bus.
+
+    Args:
+        query_bus: The query bus to register handlers with
+        repository: Provider repository
+    """
+    query_bus.register(ListProvidersQuery, ListProvidersHandler(repository))
+    query_bus.register(GetProviderQuery, GetProviderHandler(repository))
+    query_bus.register(GetProviderToolsQuery, GetProviderToolsHandler(repository))
+    query_bus.register(GetProviderHealthQuery, GetProviderHealthHandler(repository))
+    query_bus.register(GetSystemMetricsQuery, GetSystemMetricsHandler(repository))
+
+    logger.info("query_handlers_registered")

mcp_hangar/application/read_models/__init__.py

@@ -0,0 +1,11 @@
+"""Read models for optimized queries."""
+
+from .provider_views import HealthInfo, ProviderDetails, ProviderSummary, SystemMetrics, ToolInfo
+
+__all__ = [
+    "ProviderSummary",
+    "ProviderDetails",
+    "ToolInfo",
+    "HealthInfo",
+    "SystemMetrics",
+]

mcp_hangar/application/read_models/provider_views.py

@@ -0,0 +1,139 @@
+"""Read models (views) for provider queries.
+
+Read models are optimized for specific query use cases.
+They are immutable and contain only the data needed for display.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class ToolInfo:
+    """Read model for tool information."""
+
+    name: str
+    description: str
+    input_schema: Dict[str, Any]
+    output_schema: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        result = {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+        if self.output_schema is not None:
+            result["outputSchema"] = self.output_schema
+        return result
+
+
+@dataclass(frozen=True)
+class HealthInfo:
+    """Read model for health information."""
+
+    consecutive_failures: int
+    total_invocations: int
+    total_failures: int
+    success_rate: float
+    can_retry: bool
+    last_success_ago: Optional[float] = None  # seconds since last success
+    last_failure_ago: Optional[float] = None  # seconds since last failure
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "consecutive_failures": self.consecutive_failures,
+            "total_invocations": self.total_invocations,
+            "total_failures": self.total_failures,
+            "success_rate": self.success_rate,
+            "can_retry": self.can_retry,
+            "last_success_ago": self.last_success_ago,
+            "last_failure_ago": self.last_failure_ago,
+        }
+
+
+@dataclass(frozen=True)
+class ProviderSummary:
+    """Read model for provider list view.
+
+    Contains minimal information for listing providers.
+    """
+
+    provider_id: str
+    state: str
+    mode: str
+    is_alive: bool
+    tools_count: int
+    health_status: str  # healthy, degraded, unhealthy
+    description: Optional[str] = None
+    tools_predefined: bool = False  # True if tools were defined in config (no startup needed)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        result = {
+            "provider": self.provider_id,
+            "state": self.state,
+            "mode": self.mode,
+            "alive": self.is_alive,
+            "tools_count": self.tools_count,
+            "health_status": self.health_status,
+            "tools_predefined": self.tools_predefined,
+        }
+        if self.description:
+            result["description"] = self.description
+        return result
+
+
+@dataclass(frozen=True)
+class ProviderDetails:
+    """Read model for detailed provider view.
+
+    Contains full information about a provider.
+    """
+
+    provider_id: str
+    state: str
+    mode: str
+    is_alive: bool
+    tools: List[ToolInfo]
+    health: HealthInfo
+    idle_time: float
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "provider": self.provider_id,
+            "state": self.state,
+            "mode": self.mode,
+            "alive": self.is_alive,
+            "tools": [t.to_dict() for t in self.tools],
+            "health": self.health.to_dict(),
+            "idle_time": self.idle_time,
+            "meta": self.meta,
+        }
+
+
+@dataclass(frozen=True)
+class SystemMetrics:
+    """Read model for system-wide metrics."""
+
+    total_providers: int
+    providers_by_state: Dict[str, int]
+    total_tools: int
+    total_invocations: int
+    total_failures: int
+    overall_success_rate: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "total_providers": self.total_providers,
+            "providers_by_state": self.providers_by_state,
+            "total_tools": self.total_tools,
+            "total_invocations": self.total_invocations,
+            "total_failures": self.total_failures,
+            "overall_success_rate": self.overall_success_rate,
+        }

mcp_hangar/application/sagas/__init__.py

@@ -0,0 +1,11 @@
+"""Sagas for orchestrating complex provider workflows."""
+
+from .group_rebalance_saga import GroupRebalanceSaga
+from .provider_failover_saga import ProviderFailoverSaga
+from .provider_recovery_saga import ProviderRecoverySaga
+
+__all__ = [
+    "ProviderRecoverySaga",
+    "ProviderFailoverSaga",
+    "GroupRebalanceSaga",
+]

mcp_hangar/application/sagas/group_rebalance_saga.py

@@ -0,0 +1,137 @@
+"""Group Rebalance Saga - automatically rebalances groups based on events.
+
+This saga listens for provider health events and updates group member
+rotation status. The actual logic is delegated to ProviderGroup methods.
+
+Note: Most of the group health management is already handled by ProviderGroup
+through report_success() and report_failure() calls. This saga primarily
+serves as an event-driven bridge for external events (like health checks)
+that may not flow through the standard invoke path.
+"""
+
+from typing import Callable, Dict, List, Optional, Type, TYPE_CHECKING
+
+from ...domain.events import (
+    DomainEvent,
+    HealthCheckFailed,
+    HealthCheckPassed,
+    ProviderDegraded,
+    ProviderStarted,
+    ProviderStopped,
+)
+from ...infrastructure.saga_manager import EventTriggeredSaga
+from ...logging_config import get_logger
+from ..commands import Command
+
+if TYPE_CHECKING:
+    from ...domain.model.provider_group import ProviderGroup
+
+logger = get_logger(__name__)
+
+
+class GroupRebalanceSaga(EventTriggeredSaga):
+    """
+    Saga that observes provider events for group members.
+
+    This saga tracks which providers belong to which groups and logs
+    relevant events. The actual rotation management is handled by
+    ProviderGroup through its report_success/report_failure methods.
+
+    The saga can optionally execute direct actions on groups if provided
+    with a groups reference.
+    """
+
+    def __init__(
+        self,
+        group_lookup: Optional[Callable[[str], Optional[str]]] = None,
+        groups: Optional[Dict[str, "ProviderGroup"]] = None,
+    ):
+        """
+        Initialize the saga.
+
+        Args:
+            group_lookup: Function that takes a member_id and returns
+                          the group_id it belongs to, or None.
+            groups: Direct reference to groups dict for applying changes.
+        """
+        super().__init__()
+        self._group_lookup = group_lookup
+        self._groups = groups
+        self._member_to_group: Dict[str, str] = {}
+
+    @property
+    def saga_type(self) -> str:
+        return "group_rebalance"
+
+    @property
+    def handled_events(self) -> List[Type[DomainEvent]]:
+        return [
+            ProviderStarted,
+            ProviderStopped,
+            ProviderDegraded,
+            HealthCheckPassed,
+            HealthCheckFailed,
+        ]
+
+    def register_member(self, member_id: str, group_id: str) -> None:
+        """Register a member-to-group mapping."""
+        self._member_to_group[member_id] = group_id
+
+    def unregister_member(self, member_id: str) -> None:
+        """Unregister a member from the mapping."""
+        self._member_to_group.pop(member_id, None)
+
+    def _get_group_id(self, member_id: str) -> Optional[str]:
+        """Get the group ID for a member."""
+        group_id = self._member_to_group.get(member_id)
+        if group_id:
+            return group_id
+        if self._group_lookup:
+            return self._group_lookup(member_id)
+        return None
+
+    def _get_group(self, group_id: str) -> Optional["ProviderGroup"]:
+        """Get group instance if available."""
+        if self._groups:
+            return self._groups.get(group_id)
+        return None
+
+    def handle(self, event: DomainEvent) -> List[Command]:
+        """
+        Handle provider events that affect group membership.
+
+        Returns empty list as we apply changes directly to groups
+        rather than emitting commands.
+        """
+        provider_id = getattr(event, "provider_id", None)
+        if not provider_id:
+            return []
+
+        group_id = self._get_group_id(provider_id)
+        if not group_id:
+            return []
+
+        group = self._get_group(group_id)
+
+        if isinstance(event, ProviderStarted):
+            logger.info(f"Member {provider_id} started in group {group_id}")
+            if group:
+                group.report_success(provider_id)
+
+        elif isinstance(event, (ProviderStopped, ProviderDegraded)):
+            reason = getattr(event, "reason", "unknown")
+            logger.info(f"Member {provider_id} unavailable in group {group_id}: {reason}")
+            if group:
+                group.report_failure(provider_id)
+
+        elif isinstance(event, HealthCheckPassed):
+            logger.debug(f"Health check passed for {provider_id} in group {group_id}")
+            if group:
+                group.report_success(provider_id)
+
+        elif isinstance(event, HealthCheckFailed):
+            logger.debug(f"Health check failed for {provider_id} in group {group_id}")
+            if group:
+                group.report_failure(provider_id)
+
+        return []