mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/domain/model/circuit_breaker.py

@@ -0,0 +1,152 @@
+"""Circuit Breaker pattern implementation.
+
+The Circuit Breaker pattern prevents cascading failures by stopping
+requests to a failing service and allowing it time to recover.
+
+States:
+- CLOSED: Normal operation, requests pass through
+- OPEN: Failing, all requests rejected immediately
+- HALF_OPEN: Testing if service recovered (not implemented - we auto-reset)
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+import threading
+import time
+from typing import Optional
+
+
+class CircuitState(Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"
+    OPEN = "open"
+
+
+@dataclass
+class CircuitBreakerConfig:
+    """Configuration for circuit breaker behavior."""
+
+    failure_threshold: int = 10
+    reset_timeout_s: float = 60.0
+
+    def __post_init__(self):
+        self.failure_threshold = max(1, self.failure_threshold)
+        self.reset_timeout_s = max(1.0, self.reset_timeout_s)
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker that opens after reaching failure threshold.
+
+    Thread-safe implementation that tracks failures and automatically
+    resets after a timeout period.
+    """
+
+    def __init__(self, config: Optional[CircuitBreakerConfig] = None):
+        """
+        Initialize circuit breaker.
+
+        Args:
+            config: Circuit breaker configuration
+        """
+        self._config = config or CircuitBreakerConfig()
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._opened_at: Optional[float] = None
+        self._lock = threading.Lock()
+
+    @property
+    def is_open(self) -> bool:
+        """Check if circuit is open (blocking requests)."""
+        with self._lock:
+            return self._state == CircuitState.OPEN
+
+    @property
+    def state(self) -> CircuitState:
+        """Get current circuit state."""
+        with self._lock:
+            return self._state
+
+    @property
+    def failure_count(self) -> int:
+        """Get current failure count."""
+        with self._lock:
+            return self._failure_count
+
+    def allow_request(self) -> bool:
+        """
+        Check if a request should be allowed.
+
+        If circuit is open, checks if reset timeout has elapsed.
+        If so, closes the circuit and allows the request.
+
+        Returns:
+            True if request should proceed, False if circuit is open
+        """
+        with self._lock:
+            if self._state == CircuitState.CLOSED:
+                return True
+
+            # Check if we should try to close
+            if self._should_reset():
+                self._close()
+                return True
+
+            return False
+
+    def record_success(self) -> None:
+        """Record a successful operation."""
+        with self._lock:
+            self._failure_count = 0
+            if self._state == CircuitState.OPEN:
+                self._close()
+
+    def record_failure(self) -> bool:
+        """
+        Record a failed operation.
+
+        Returns:
+            True if circuit just opened, False otherwise
+        """
+        with self._lock:
+            self._failure_count += 1
+
+            if self._state == CircuitState.CLOSED and self._failure_count >= self._config.failure_threshold:
+                self._open()
+                return True
+
+            return False
+
+    def reset(self) -> None:
+        """Manually reset the circuit breaker."""
+        with self._lock:
+            self._close()
+
+    def _should_reset(self) -> bool:
+        """Check if enough time has passed to attempt reset."""
+        if self._opened_at is None:
+            return True
+        return time.time() - self._opened_at >= self._config.reset_timeout_s
+
+    def _open(self) -> None:
+        """Open the circuit (must hold lock)."""
+        self._state = CircuitState.OPEN
+        self._opened_at = time.time()
+
+    def _close(self) -> None:
+        """Close the circuit (must hold lock)."""
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._opened_at = None
+
+    def to_dict(self) -> dict:
+        """Get circuit breaker status as dictionary."""
+        with self._lock:
+            return {
+                "state": self._state.value,
+                "is_open": self._state == CircuitState.OPEN,
+                "failure_count": self._failure_count,
+                "failure_threshold": self._config.failure_threshold,
+                "reset_timeout_s": self._config.reset_timeout_s,
+            }

mcp_hangar/domain/model/event_sourced_api_key.py

@@ -0,0 +1,413 @@
+"""Event Sourced API Key aggregate.
+
+Implements Event Sourcing pattern for API keys where:
+- State is derived from events, not stored directly
+- All changes are captured as immutable events
+- State can be rebuilt by replaying events
+- Supports snapshots for performance
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from ..events import ApiKeyCreated, ApiKeyRevoked, DomainEvent
+from ..value_objects import Principal, PrincipalId, PrincipalType
+from .aggregate import AggregateRoot
+
+
+@dataclass
+class ApiKeySnapshot:
+    """Snapshot of API key state for faster loading.
+
+    Attributes:
+        key_hash: SHA-256 hash of the key.
+        key_id: Unique identifier.
+        principal_id: Principal this key authenticates as.
+        name: Human-readable name.
+        tenant_id: Optional tenant ID.
+        groups: Groups assigned to the principal.
+        created_at: Creation timestamp.
+        expires_at: Optional expiration timestamp.
+        last_used_at: Last usage timestamp.
+        revoked: Whether the key is revoked.
+        revoked_at: When the key was revoked.
+        version: Aggregate version.
+    """
+
+    key_hash: str
+    key_id: str
+    principal_id: str
+    name: str
+    tenant_id: str | None
+    groups: list[str]
+    created_at: float
+    expires_at: float | None
+    last_used_at: float | None
+    revoked: bool
+    revoked_at: float | None
+    version: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "key_hash": self.key_hash,
+            "key_id": self.key_id,
+            "principal_id": self.principal_id,
+            "name": self.name,
+            "tenant_id": self.tenant_id,
+            "groups": self.groups,
+            "created_at": self.created_at,
+            "expires_at": self.expires_at,
+            "last_used_at": self.last_used_at,
+            "revoked": self.revoked,
+            "revoked_at": self.revoked_at,
+            "version": self.version,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ApiKeySnapshot":
+        """Create from dictionary."""
+        return cls(
+            key_hash=d["key_hash"],
+            key_id=d["key_id"],
+            principal_id=d["principal_id"],
+            name=d["name"],
+            tenant_id=d.get("tenant_id"),
+            groups=d.get("groups", []),
+            created_at=d["created_at"],
+            expires_at=d.get("expires_at"),
+            last_used_at=d.get("last_used_at"),
+            revoked=d.get("revoked", False),
+            revoked_at=d.get("revoked_at"),
+            version=d.get("version", 0),
+            metadata=d.get("metadata", {}),
+        )
+
+
+class EventSourcedApiKey(AggregateRoot):
+    """Event Sourced API Key aggregate.
+
+    All state changes are recorded as events and state is rebuilt
+    by replaying those events. This provides:
+    - Complete audit trail
+    - Time-travel debugging
+    - Event-driven integrations
+    """
+
+    def __init__(
+        self,
+        key_hash: str,
+        key_id: str,
+        principal_id: str,
+        name: str,
+        tenant_id: str | None = None,
+        groups: frozenset[str] | None = None,
+        expires_at: datetime | None = None,
+    ):
+        """Initialize a new API key aggregate.
+
+        Note: This doesn't record creation event - use create() factory method.
+        """
+        super().__init__()
+
+        # Identity
+        self._key_hash = key_hash
+        self._key_id = key_id
+
+        # Principal info
+        self._principal_id = principal_id
+        self._name = name
+        self._tenant_id = tenant_id
+        self._groups = groups or frozenset()
+
+        # Timestamps
+        self._created_at: datetime | None = None
+        self._expires_at = expires_at
+        self._last_used_at: datetime | None = None
+
+        # State
+        self._revoked = False
+        self._revoked_at: datetime | None = None
+        self._metadata: dict[str, Any] = {}
+
+    @property
+    def key_hash(self) -> str:
+        return self._key_hash
+
+    @property
+    def key_id(self) -> str:
+        return self._key_id
+
+    @property
+    def principal_id(self) -> str:
+        return self._principal_id
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def tenant_id(self) -> str | None:
+        return self._tenant_id
+
+    @property
+    def groups(self) -> frozenset[str]:
+        return self._groups
+
+    @property
+    def created_at(self) -> datetime | None:
+        return self._created_at
+
+    @property
+    def expires_at(self) -> datetime | None:
+        return self._expires_at
+
+    @property
+    def last_used_at(self) -> datetime | None:
+        return self._last_used_at
+
+    @property
+    def is_revoked(self) -> bool:
+        return self._revoked
+
+    @property
+    def is_expired(self) -> bool:
+        if self._expires_at is None:
+            return False
+        return datetime.now(timezone.utc) > self._expires_at
+
+    @property
+    def is_valid(self) -> bool:
+        return not self._revoked and not self.is_expired
+
+    # =========================================================================
+    # Factory Methods
+    # =========================================================================
+
+    @classmethod
+    def create(
+        cls,
+        key_hash: str,
+        key_id: str,
+        principal_id: str,
+        name: str,
+        created_by: str,
+        tenant_id: str | None = None,
+        groups: frozenset[str] | None = None,
+        expires_at: datetime | None = None,
+    ) -> "EventSourcedApiKey":
+        """Create a new API key and record creation event.
+
+        Args:
+            key_hash: SHA-256 hash of the raw key.
+            key_id: Unique identifier for management.
+            principal_id: Principal this key authenticates as.
+            name: Human-readable name.
+            created_by: Who created this key.
+            tenant_id: Optional tenant for multi-tenancy.
+            groups: Optional groups for the principal.
+            expires_at: Optional expiration datetime.
+
+        Returns:
+            New EventSourcedApiKey with ApiKeyCreated event recorded.
+        """
+        key = cls(
+            key_hash=key_hash,
+            key_id=key_id,
+            principal_id=principal_id,
+            name=name,
+            tenant_id=tenant_id,
+            groups=groups,
+            expires_at=expires_at,
+        )
+
+        # Record creation event
+        key._record_event(
+            ApiKeyCreated(
+                key_id=key_id,
+                principal_id=principal_id,
+                key_name=name,
+                expires_at=expires_at.timestamp() if expires_at else None,
+                created_by=created_by,
+            )
+        )
+
+        # Apply the event to set state
+        key._created_at = datetime.now(timezone.utc)
+
+        return key
+
+    @classmethod
+    def from_events(
+        cls,
+        key_hash: str,
+        key_id: str,
+        principal_id: str,
+        name: str,
+        events: list[DomainEvent],
+        tenant_id: str | None = None,
+        groups: frozenset[str] | None = None,
+        expires_at: datetime | None = None,
+    ) -> "EventSourcedApiKey":
+        """Rebuild API key state from events.
+
+        Args:
+            key_hash: SHA-256 hash of the key.
+            key_id: Unique identifier.
+            principal_id: Principal ID.
+            name: Key name.
+            events: Events to replay.
+            tenant_id: Optional tenant.
+            groups: Optional groups.
+            expires_at: Optional expiration.
+
+        Returns:
+            EventSourcedApiKey with state rebuilt from events.
+        """
+        key = cls(
+            key_hash=key_hash,
+            key_id=key_id,
+            principal_id=principal_id,
+            name=name,
+            tenant_id=tenant_id,
+            groups=groups,
+            expires_at=expires_at,
+        )
+
+        for event in events:
+            key._apply_event(event)
+
+        return key
+
+    @classmethod
+    def from_snapshot(
+        cls,
+        snapshot: ApiKeySnapshot,
+        events: list[DomainEvent] | None = None,
+    ) -> "EventSourcedApiKey":
+        """Load API key from snapshot and optional subsequent events.
+
+        Args:
+            snapshot: Snapshot to load from.
+            events: Optional events after snapshot.
+
+        Returns:
+            EventSourcedApiKey with state from snapshot + events.
+        """
+        key = cls(
+            key_hash=snapshot.key_hash,
+            key_id=snapshot.key_id,
+            principal_id=snapshot.principal_id,
+            name=snapshot.name,
+            tenant_id=snapshot.tenant_id,
+            groups=frozenset(snapshot.groups),
+            expires_at=datetime.fromtimestamp(snapshot.expires_at, tz=timezone.utc) if snapshot.expires_at else None,
+        )
+
+        # Restore state from snapshot
+        key._created_at = datetime.fromtimestamp(snapshot.created_at, tz=timezone.utc)
+        key._last_used_at = (
+            datetime.fromtimestamp(snapshot.last_used_at, tz=timezone.utc) if snapshot.last_used_at else None
+        )
+        key._revoked = snapshot.revoked
+        key._revoked_at = datetime.fromtimestamp(snapshot.revoked_at, tz=timezone.utc) if snapshot.revoked_at else None
+        key._metadata = dict(snapshot.metadata)
+        key._version = snapshot.version
+
+        # Apply any events after snapshot
+        if events:
+            for event in events:
+                key._apply_event(event)
+
+        return key
+
+    # =========================================================================
+    # Commands (mutate state via events)
+    # =========================================================================
+
+    def revoke(self, revoked_by: str, reason: str = "") -> None:
+        """Revoke this API key.
+
+        Args:
+            revoked_by: Principal revoking the key.
+            reason: Optional reason for revocation.
+
+        Raises:
+            ValueError: If key is already revoked.
+        """
+        if self._revoked:
+            raise ValueError(f"API key {self._key_id} is already revoked")
+
+        self._record_event(
+            ApiKeyRevoked(
+                key_id=self._key_id,
+                principal_id=self._principal_id,
+                revoked_by=revoked_by,
+                reason=reason,
+            )
+        )
+
+        # Apply immediately
+        self._revoked = True
+        self._revoked_at = datetime.now(timezone.utc)
+
+    def record_usage(self) -> None:
+        """Record that this key was used for authentication."""
+        self._last_used_at = datetime.now(timezone.utc)
+
+    # =========================================================================
+    # Event Application
+    # =========================================================================
+
+    def _apply_event(self, event: DomainEvent) -> None:
+        """Apply an event to update state.
+
+        This is called when replaying events to rebuild state.
+        """
+        if isinstance(event, ApiKeyCreated):
+            self._created_at = datetime.fromtimestamp(event.occurred_at, tz=timezone.utc)
+
+        elif isinstance(event, ApiKeyRevoked):
+            self._revoked = True
+            self._revoked_at = datetime.fromtimestamp(event.occurred_at, tz=timezone.utc)
+
+        self._version += 1
+
+    # =========================================================================
+    # Queries
+    # =========================================================================
+
+    def to_principal(self) -> Principal:
+        """Convert to Principal for authentication."""
+        return Principal(
+            id=PrincipalId(self._principal_id),
+            type=PrincipalType.SERVICE_ACCOUNT,
+            tenant_id=self._tenant_id,
+            groups=self._groups,
+            metadata={
+                "key_id": self._key_id,
+                "key_name": self._name,
+                **self._metadata,
+            },
+        )
+
+    def create_snapshot(self) -> ApiKeySnapshot:
+        """Create a snapshot of current state."""
+        return ApiKeySnapshot(
+            key_hash=self._key_hash,
+            key_id=self._key_id,
+            principal_id=self._principal_id,
+            name=self._name,
+            tenant_id=self._tenant_id,
+            groups=list(self._groups),
+            created_at=self._created_at.timestamp() if self._created_at else 0,
+            expires_at=self._expires_at.timestamp() if self._expires_at else None,
+            last_used_at=self._last_used_at.timestamp() if self._last_used_at else None,
+            revoked=self._revoked,
+            revoked_at=self._revoked_at.timestamp() if self._revoked_at else None,
+            version=self._version,
+            metadata=dict(self._metadata),
+        )