mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/domain/model/health_tracker.py

@@ -0,0 +1,183 @@
+"""Health tracking entity for providers."""
+
+from dataclasses import dataclass, field
+import time
+from typing import Optional
+
+
+@dataclass
+class HealthTracker:
+    """Tracks health metrics for a provider.
+
+    This is a mutable entity (not a value object) that encapsulates
+    health-related business logic including:
+    - Failure counting and threshold detection
+    - Backoff calculation for retry logic
+    - Success/failure recording with timestamps
+
+    Note:
+        This class is intentionally mutable as it tracks state over time.
+        It is not a value object and should not be compared by value.
+
+    Attributes:
+        max_consecutive_failures: Threshold for triggering degradation.
+
+    Example:
+        >>> tracker = HealthTracker(max_consecutive_failures=3)
+        >>> tracker.record_failure()
+        >>> tracker.consecutive_failures
+        1
+    """
+
+    max_consecutive_failures: int = 3
+    _consecutive_failures: int = field(default=0, init=False)
+    _last_success_at: Optional[float] = field(default=None, init=False)
+    _last_failure_at: Optional[float] = field(default=None, init=False)
+    _total_invocations: int = field(default=0, init=False)
+    _total_failures: int = field(default=0, init=False)
+
+    @property
+    def consecutive_failures(self) -> int:
+        """Get the current consecutive failure count.
+
+        Returns:
+            Number of consecutive failures since last success.
+        """
+        return self._consecutive_failures
+
+    @property
+    def last_success_at(self) -> Optional[float]:
+        """Get the timestamp of last successful operation.
+
+        Returns:
+            Unix timestamp of last success, or None if never succeeded.
+        """
+        return self._last_success_at
+
+    @property
+    def last_failure_at(self) -> Optional[float]:
+        """Get the timestamp of last failed operation.
+
+        Returns:
+            Unix timestamp of last failure, or None if never failed.
+        """
+        return self._last_failure_at
+
+    @property
+    def total_invocations(self) -> int:
+        """Get the total number of invocations.
+
+        Returns:
+            Total count of success + failure invocations.
+        """
+        return self._total_invocations
+
+    @property
+    def total_failures(self) -> int:
+        """Get the total number of failures.
+
+        Returns:
+            Total count of failed invocations.
+        """
+        return self._total_failures
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate the success rate as a percentage.
+
+        Returns:
+            Success rate from 0.0 to 1.0. Returns 1.0 if no invocations yet.
+        """
+        if self._total_invocations == 0:
+            return 1.0
+        return (self._total_invocations - self._total_failures) / self._total_invocations
+
+    def record_success(self) -> None:
+        """Record a successful operation.
+
+        Resets the consecutive failure counter and updates timestamps.
+        """
+        self._consecutive_failures = 0
+        self._last_success_at = time.time()
+        self._total_invocations += 1
+
+    def record_failure(self) -> None:
+        """Record a failed operation.
+
+        Increments both consecutive and total failure counters.
+        """
+        self._consecutive_failures += 1
+        self._last_failure_at = time.time()
+        self._total_failures += 1
+        self._total_invocations += 1
+
+    def record_invocation_failure(self) -> None:
+        """Record a failed tool invocation.
+
+        Increments total_failures but not consecutive failures.
+        Use this for application-level errors that shouldn't trigger degradation.
+        """
+        self._total_failures += 1
+        self._total_invocations += 1
+
+    def should_degrade(self) -> bool:
+        """Check if provider should transition to DEGRADED state.
+
+        Returns:
+            True when consecutive failures reach the threshold.
+        """
+        return self._consecutive_failures >= self.max_consecutive_failures
+
+    def can_retry(self) -> bool:
+        """Check if enough time has passed for a retry attempt.
+
+        Uses exponential backoff: min(60, 2^consecutive_failures) seconds.
+
+        Returns:
+            True if retry is allowed, False if still in backoff period.
+        """
+        if self._last_failure_at is None:
+            return True
+
+        backoff = self._calculate_backoff()
+        elapsed = time.time() - self._last_failure_at
+        return elapsed >= backoff
+
+    def time_until_retry(self) -> float:
+        """Calculate time remaining until retry is allowed.
+
+        Returns:
+            Seconds until retry is allowed. Returns 0 if retry is already allowed.
+        """
+        if self._last_failure_at is None:
+            return 0.0
+
+        backoff = self._calculate_backoff()
+        elapsed = time.time() - self._last_failure_at
+        remaining = backoff - elapsed
+        return max(0.0, remaining)
+
+    def _calculate_backoff(self) -> float:
+        """Calculate backoff duration based on consecutive failures."""
+        return min(60.0, 2**self._consecutive_failures)
+
+    def reset(self) -> None:
+        """Reset health tracker to initial state."""
+        self._consecutive_failures = 0
+        self._last_success_at = None
+        self._last_failure_at = None
+        self._total_invocations = 0
+        self._total_failures = 0
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary representation."""
+        return {
+            "consecutive_failures": self._consecutive_failures,
+            "last_success_at": self._last_success_at,
+            "last_failure_at": self._last_failure_at,
+            "total_invocations": self._total_invocations,
+            "total_failures": self._total_failures,
+            "success_rate": self.success_rate,
+            "can_retry": self.can_retry(),
+            "time_until_retry": self.time_until_retry(),
+        }

mcp_hangar/domain/model/load_balancer.py

@@ -0,0 +1,185 @@
+"""Load balancing strategies for provider groups.
+
+This module implements various load balancing strategies for distributing
+requests across group members.
+"""
+
+from abc import ABC, abstractmethod
+import random
+import threading
+from typing import List, Optional, TYPE_CHECKING
+
+from ..value_objects import LoadBalancerStrategy
+
+if TYPE_CHECKING:
+    from .provider_group import GroupMember
+
+
+class BaseStrategy(ABC):
+    """Abstract base class for load balancing strategies."""
+
+    @abstractmethod
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        """
+        Select a member from available members.
+
+        Args:
+            members: List of available (in_rotation) group members
+
+        Returns:
+            Selected member or None if no members available
+        """
+        pass
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Reset strategy state (e.g., after rebalancing)."""
+        pass
+
+
+class RoundRobinStrategy(BaseStrategy):
+    """Simple round-robin selection.
+
+    Each member gets selected in order, cycling through the list.
+    """
+
+    def __init__(self):
+        self._index = 0
+        self._lock = threading.Lock()
+
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        if not members:
+            return None
+        with self._lock:
+            selected = members[self._index % len(members)]
+            self._index += 1
+        return selected
+
+    def reset(self) -> None:
+        with self._lock:
+            self._index = 0
+
+
+class WeightedRoundRobinStrategy(BaseStrategy):
+    """
+    Weighted round-robin using smooth weighted algorithm.
+
+    Members with higher weights get proportionally more requests.
+    Uses the Nginx smooth weighted round-robin algorithm for even distribution.
+    """
+
+    def __init__(self):
+        self._current_weights: dict = {}
+        self._lock = threading.Lock()
+
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        if not members:
+            return None
+
+        with self._lock:
+            total_weight = sum(m.weight for m in members)
+
+            # Initialize or update current weights
+            for m in members:
+                mid = id(m)
+                if mid not in self._current_weights:
+                    self._current_weights[mid] = 0
+                self._current_weights[mid] += m.weight
+
+            # Select member with highest current weight
+            best = max(members, key=lambda m: self._current_weights.get(id(m), 0))
+
+            # Reduce selected member's weight by total weight
+            self._current_weights[id(best)] -= total_weight
+
+            return best
+
+    def reset(self) -> None:
+        with self._lock:
+            self._current_weights.clear()
+
+
+class LeastConnectionsStrategy(BaseStrategy):
+    """Select member with fewest recent selections.
+
+    Uses last_selected_at timestamp as a proxy for "connections".
+    Prefers members that haven't been selected recently.
+    """
+
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        if not members:
+            return None
+        # Select member with oldest last_selected_at (least recently used)
+        return min(members, key=lambda m: m.last_selected_at)
+
+    def reset(self) -> None:
+        # No state to reset
+        pass
+
+
+class RandomStrategy(BaseStrategy):
+    """Random selection with optional weights.
+
+    Uses weighted random selection where higher weight = higher probability.
+    """
+
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        if not members:
+            return None
+        weights = [m.weight for m in members]
+        return random.choices(members, weights=weights, k=1)[0]
+
+    def reset(self) -> None:
+        # No state to reset
+        pass
+
+
+class PriorityStrategy(BaseStrategy):
+    """Always select lowest priority member that's healthy.
+
+    Priority 1 is highest priority. Falls back to next priority if 1 is unavailable.
+    Useful for primary/backup scenarios.
+    """
+
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        if not members:
+            return None
+        # Select member with lowest priority number (highest priority)
+        return min(members, key=lambda m: m.priority)
+
+    def reset(self) -> None:
+        # No state to reset
+        pass
+
+
+class LoadBalancer:
+    """
+    Load balancer that selects members based on configured strategy.
+
+    Thread-safe - each strategy implementation handles its own locking.
+    """
+
+    _STRATEGIES = {
+        LoadBalancerStrategy.ROUND_ROBIN: RoundRobinStrategy,
+        LoadBalancerStrategy.WEIGHTED_ROUND_ROBIN: WeightedRoundRobinStrategy,
+        LoadBalancerStrategy.LEAST_CONNECTIONS: LeastConnectionsStrategy,
+        LoadBalancerStrategy.RANDOM: RandomStrategy,
+        LoadBalancerStrategy.PRIORITY: PriorityStrategy,
+    }
+
+    def __init__(self, strategy: LoadBalancerStrategy):
+        self._strategy_type = strategy
+        self._impl = self._STRATEGIES[strategy]()
+
+    @property
+    def strategy(self) -> LoadBalancerStrategy:
+        """Get the current strategy type."""
+        return self._strategy_type
+
+    def select(self, members: List["GroupMember"]) -> Optional["GroupMember"]:
+        """Select a member from available members."""
+        return self._impl.select(members)
+
+    def reset(self) -> None:
+        """Reset strategy state."""
+        self._impl.reset()