truthound 1.0.8__py3-none-any.whl

truthound/common/resilience/composite.py

@@ -0,0 +1,332 @@
+"""Composite resilience patterns.
+
+This module provides a fluent builder for combining multiple
+resilience patterns into a single wrapper.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from contextlib import contextmanager
+from typing import Any, Callable, Generator, TypeVar
+
+from truthound.common.resilience.circuit_breaker import CircuitBreaker, CircuitBreakerConfig
+from truthound.common.resilience.retry import RetryPolicy, RetryConfig
+from truthound.common.resilience.bulkhead import SemaphoreBulkhead, BulkheadConfig
+from truthound.common.resilience.rate_limiter import (
+    TokenBucketRateLimiter,
+    RateLimiterConfig,
+)
+from truthound.common.resilience.protocols import (
+    CircuitBreakerProtocol,
+    RetryPolicyProtocol,
+    BulkheadProtocol,
+    RateLimiterProtocol,
+)
+
+logger = logging.getLogger(__name__)
+
+R = TypeVar("R")
+
+
+class ResilientWrapper:
+    """Wrapper that applies multiple resilience patterns.
+
+    Patterns are applied in order:
+    1. Rate limiter (if configured)
+    2. Bulkhead (if configured)
+    3. Circuit breaker (if configured)
+    4. Retry (if configured)
+    5. Function execution
+
+    Example:
+        wrapper = ResilientWrapper(
+            name="my-service",
+            circuit_breaker=CircuitBreaker("cb"),
+            retry=RetryPolicy(),
+        )
+
+        result = wrapper.execute(risky_function, arg1, arg2)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        circuit_breaker: CircuitBreakerProtocol | None = None,
+        retry: RetryPolicyProtocol | None = None,
+        bulkhead: BulkheadProtocol | None = None,
+        rate_limiter: RateLimiterProtocol | None = None,
+    ):
+        """Initialize resilient wrapper.
+
+        Args:
+            name: Unique name for this wrapper.
+            circuit_breaker: Optional circuit breaker.
+            retry: Optional retry policy.
+            bulkhead: Optional bulkhead.
+            rate_limiter: Optional rate limiter.
+        """
+        self._name = name
+        self._circuit_breaker = circuit_breaker
+        self._retry = retry
+        self._bulkhead = bulkhead
+        self._rate_limiter = rate_limiter
+
+    @property
+    def name(self) -> str:
+        """Get wrapper name."""
+        return self._name
+
+    def execute(self, func: Callable[..., R], *args: Any, **kwargs: Any) -> R:
+        """Execute function with all configured resilience patterns."""
+        def wrapped() -> R:
+            return func(*args, **kwargs)
+
+        # Build execution chain from inside out using default arguments
+        # to avoid late binding closure issues
+        execution = wrapped
+
+        # Innermost: circuit breaker
+        if self._circuit_breaker:
+            def with_cb(cb: CircuitBreakerProtocol = self._circuit_breaker, inner: Callable[[], R] = execution) -> R:
+                with cb.protect():
+                    return inner()
+            execution = with_cb
+
+        # Wrap with retry
+        if self._retry:
+            def with_retry(retry: RetryPolicyProtocol = self._retry, inner: Callable[[], R] = execution) -> R:
+                return retry.execute(inner)
+            execution = with_retry
+
+        # Wrap with bulkhead
+        if self._bulkhead:
+            def with_bulkhead(bulkhead: BulkheadProtocol = self._bulkhead, inner: Callable[[], R] = execution) -> R:
+                with bulkhead.limit():
+                    return inner()
+            execution = with_bulkhead
+
+        # Outermost: rate limiter
+        if self._rate_limiter:
+            def with_limiter(limiter: RateLimiterProtocol = self._rate_limiter, inner: Callable[[], R] = execution) -> R:
+                with limiter.limit():
+                    return inner()
+            execution = with_limiter
+
+        return execution()
+
+    @contextmanager
+    def protect(self) -> Generator[None, None, None]:
+        """Context manager for protected execution."""
+        # Apply patterns in order
+        cm_stack: list[Any] = []
+
+        if self._rate_limiter:
+            cm_stack.append(self._rate_limiter.limit())
+        if self._bulkhead:
+            cm_stack.append(self._bulkhead.limit())
+        if self._circuit_breaker:
+            cm_stack.append(self._circuit_breaker.protect())
+
+        # Enter all context managers
+        for cm in cm_stack:
+            cm.__enter__()
+
+        try:
+            yield
+        except Exception as e:
+            # Exit with exception
+            for cm in reversed(cm_stack):
+                try:
+                    cm.__exit__(type(e), e, e.__traceback__)
+                except Exception:
+                    pass
+            raise
+        else:
+            # Exit normally
+            for cm in reversed(cm_stack):
+                cm.__exit__(None, None, None)
+
+    def __call__(self, func: Callable[..., R]) -> Callable[..., R]:
+        """Decorator for resilient execution."""
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> R:
+            return self.execute(func, *args, **kwargs)
+        return wrapper
+
+    def get_metrics(self) -> dict[str, Any]:
+        """Get metrics from all components."""
+        metrics: dict[str, Any] = {"name": self._name}
+
+        if self._circuit_breaker:
+            metrics["circuit_breaker"] = self._circuit_breaker.get_metrics()
+        if self._retry:
+            metrics["retry"] = self._retry.get_metrics()
+        if self._bulkhead:
+            metrics["bulkhead"] = self._bulkhead.get_metrics()
+        if self._rate_limiter:
+            metrics["rate_limiter"] = self._rate_limiter.get_metrics()
+
+        return metrics
+
+    def reset(self) -> None:
+        """Reset all components."""
+        if self._circuit_breaker:
+            self._circuit_breaker.reset()
+        if self._retry:
+            self._retry.reset()
+        if self._bulkhead:
+            self._bulkhead.reset()
+        if self._rate_limiter:
+            self._rate_limiter.reset()
+
+
+class ResilienceBuilder:
+    """Fluent builder for creating resilient wrappers.
+
+    Example:
+        wrapper = (
+            ResilienceBuilder("my-service")
+            .with_circuit_breaker(CircuitBreakerConfig.aggressive())
+            .with_retry(RetryConfig.exponential())
+            .with_bulkhead(BulkheadConfig(max_concurrent=10))
+            .with_rate_limit(RateLimiterConfig.per_second(100))
+            .build()
+        )
+
+        @wrapper
+        def risky_operation():
+            return external_service.call()
+    """
+
+    def __init__(self, name: str):
+        """Initialize builder.
+
+        Args:
+            name: Unique name for the wrapper.
+        """
+        self._name = name
+        self._circuit_breaker: CircuitBreakerProtocol | None = None
+        self._retry: RetryPolicyProtocol | None = None
+        self._bulkhead: BulkheadProtocol | None = None
+        self._rate_limiter: RateLimiterProtocol | None = None
+
+    def with_circuit_breaker(
+        self,
+        config: CircuitBreakerConfig | None = None,
+        instance: CircuitBreakerProtocol | None = None,
+    ) -> "ResilienceBuilder":
+        """Add circuit breaker to the wrapper.
+
+        Args:
+            config: Configuration for a new circuit breaker.
+            instance: Existing circuit breaker instance.
+        """
+        if instance:
+            self._circuit_breaker = instance
+        else:
+            self._circuit_breaker = CircuitBreaker(
+                f"{self._name}-cb",
+                config or CircuitBreakerConfig(),
+            )
+        return self
+
+    def with_retry(
+        self,
+        config: RetryConfig | None = None,
+        instance: RetryPolicyProtocol | None = None,
+    ) -> "ResilienceBuilder":
+        """Add retry policy to the wrapper.
+
+        Args:
+            config: Configuration for a new retry policy.
+            instance: Existing retry policy instance.
+        """
+        if instance:
+            self._retry = instance
+        else:
+            self._retry = RetryPolicy(config or RetryConfig())
+        return self
+
+    def with_bulkhead(
+        self,
+        config: BulkheadConfig | None = None,
+        instance: BulkheadProtocol | None = None,
+    ) -> "ResilienceBuilder":
+        """Add bulkhead to the wrapper.
+
+        Args:
+            config: Configuration for a new bulkhead.
+            instance: Existing bulkhead instance.
+        """
+        if instance:
+            self._bulkhead = instance
+        else:
+            self._bulkhead = SemaphoreBulkhead(
+                f"{self._name}-bulkhead",
+                config or BulkheadConfig(),
+            )
+        return self
+
+    def with_rate_limit(
+        self,
+        config: RateLimiterConfig | None = None,
+        instance: RateLimiterProtocol | None = None,
+    ) -> "ResilienceBuilder":
+        """Add rate limiter to the wrapper.
+
+        Args:
+            config: Configuration for a new rate limiter.
+            instance: Existing rate limiter instance.
+        """
+        if instance:
+            self._rate_limiter = instance
+        else:
+            self._rate_limiter = TokenBucketRateLimiter(
+                f"{self._name}-limiter",
+                config or RateLimiterConfig(),
+            )
+        return self
+
+    def build(self) -> ResilientWrapper:
+        """Build the resilient wrapper."""
+        return ResilientWrapper(
+            name=self._name,
+            circuit_breaker=self._circuit_breaker,
+            retry=self._retry,
+            bulkhead=self._bulkhead,
+            rate_limiter=self._rate_limiter,
+        )
+
+    @classmethod
+    def for_database(cls, name: str) -> ResilientWrapper:
+        """Create a wrapper optimized for database operations."""
+        return (
+            cls(name)
+            .with_circuit_breaker(CircuitBreakerConfig.for_database())
+            .with_retry(RetryConfig.quick())
+            .with_bulkhead(BulkheadConfig.for_database())
+            .build()
+        )
+
+    @classmethod
+    def for_external_api(cls, name: str) -> ResilientWrapper:
+        """Create a wrapper optimized for external API calls."""
+        return (
+            cls(name)
+            .with_circuit_breaker(CircuitBreakerConfig.for_external_api())
+            .with_retry(RetryConfig.exponential())
+            .with_rate_limit(RateLimiterConfig.per_second(100))
+            .build()
+        )
+
+    @classmethod
+    def simple(cls, name: str) -> ResilientWrapper:
+        """Create a simple wrapper with default settings."""
+        return (
+            cls(name)
+            .with_circuit_breaker()
+            .with_retry()
+            .build()
+        )

truthound/common/resilience/config.py

@@ -0,0 +1,292 @@
+"""Configuration classes for resilience patterns.
+
+This module provides dataclass-based configuration for all resilience patterns,
+with factory methods for common presets.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+
+@dataclass(frozen=True)
+class CircuitBreakerConfig:
+    """Configuration for circuit breaker.
+
+    Attributes:
+        failure_threshold: Number of failures before opening circuit.
+        success_threshold: Number of successes in half-open to close circuit.
+        timeout_seconds: Time in open state before transitioning to half-open.
+        half_open_max_calls: Maximum calls allowed in half-open state.
+        failure_rate_threshold: Failure rate percentage to trigger open.
+        slow_call_threshold_ms: Latency threshold for slow calls.
+        slow_call_rate_threshold: Slow call rate percentage to trigger open.
+        window_size: Number of calls to track for rate calculations.
+        excluded_exceptions: Exceptions that don't count as failures.
+        record_slow_calls: Whether to track slow calls.
+    """
+
+    failure_threshold: int = 5
+    success_threshold: int = 3
+    timeout_seconds: float = 30.0
+    half_open_max_calls: int = 3
+    failure_rate_threshold: float = 50.0
+    slow_call_threshold_ms: float = 1000.0
+    slow_call_rate_threshold: float = 50.0
+    window_size: int = 100
+    excluded_exceptions: tuple[type[Exception], ...] = ()
+    record_slow_calls: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate configuration."""
+        if self.failure_threshold <= 0:
+            raise ValueError("failure_threshold must be positive")
+        if self.success_threshold <= 0:
+            raise ValueError("success_threshold must be positive")
+        if self.timeout_seconds < 0:
+            raise ValueError("timeout_seconds must be non-negative")
+        if not 0 <= self.failure_rate_threshold <= 100:
+            raise ValueError("failure_rate_threshold must be between 0 and 100")
+        if not 0 <= self.slow_call_rate_threshold <= 100:
+            raise ValueError("slow_call_rate_threshold must be between 0 and 100")
+
+    @classmethod
+    def aggressive(cls) -> "CircuitBreakerConfig":
+        """Aggressive config - opens quickly, recovers slowly."""
+        return cls(
+            failure_threshold=3,
+            success_threshold=3,
+            timeout_seconds=60.0,
+            failure_rate_threshold=30.0,
+        )
+
+    @classmethod
+    def lenient(cls) -> "CircuitBreakerConfig":
+        """Lenient config - tolerates more failures."""
+        return cls(
+            failure_threshold=10,
+            success_threshold=1,
+            timeout_seconds=15.0,
+            failure_rate_threshold=80.0,
+        )
+
+    @classmethod
+    def disabled(cls) -> "CircuitBreakerConfig":
+        """Effectively disabled circuit breaker."""
+        return cls(
+            failure_threshold=1_000_000,
+            timeout_seconds=0.1,
+        )
+
+    @classmethod
+    def for_database(cls) -> "CircuitBreakerConfig":
+        """Optimized for database connections."""
+        return cls(
+            failure_threshold=5,
+            success_threshold=2,
+            timeout_seconds=30.0,
+            slow_call_threshold_ms=5000.0,
+        )
+
+    @classmethod
+    def for_external_api(cls) -> "CircuitBreakerConfig":
+        """Optimized for external API calls."""
+        return cls(
+            failure_threshold=3,
+            success_threshold=2,
+            timeout_seconds=60.0,
+            slow_call_threshold_ms=2000.0,
+        )
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Configuration for retry policy.
+
+    Attributes:
+        max_attempts: Maximum number of attempts (1 = no retry).
+        base_delay: Base delay in seconds.
+        max_delay: Maximum delay cap in seconds.
+        exponential_base: Multiplier for exponential backoff.
+        jitter: Whether to add random jitter to delays.
+        jitter_factor: Maximum jitter as a fraction (0.0-1.0).
+        retryable_exceptions: Exceptions that trigger retry.
+        non_retryable_exceptions: Exceptions that should not be retried.
+    """
+
+    max_attempts: int = 3
+    base_delay: float = 0.1
+    max_delay: float = 30.0
+    exponential_base: float = 2.0
+    jitter: bool = True
+    jitter_factor: float = 0.5
+    retryable_exceptions: tuple[type[Exception], ...] = (
+        ConnectionError,
+        TimeoutError,
+        OSError,
+    )
+    non_retryable_exceptions: tuple[type[Exception], ...] = (
+        ValueError,
+        TypeError,
+        KeyError,
+    )
+
+    def __post_init__(self) -> None:
+        """Validate configuration."""
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if self.base_delay < 0:
+            raise ValueError("base_delay must be non-negative")
+        if self.max_delay < self.base_delay:
+            raise ValueError("max_delay must be >= base_delay")
+        if self.exponential_base < 1:
+            raise ValueError("exponential_base must be >= 1")
+        if not 0 <= self.jitter_factor <= 1:
+            raise ValueError("jitter_factor must be between 0 and 1")
+
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for given attempt number (0-indexed)."""
+        import random
+
+        delay = self.base_delay * (self.exponential_base ** attempt)
+        delay = min(delay, self.max_delay)
+
+        if self.jitter:
+            jitter_range = delay * self.jitter_factor
+            delay = delay + random.uniform(-jitter_range, jitter_range)
+            delay = max(0, delay)
+
+        return delay
+
+    def is_retryable(self, error: Exception) -> bool:
+        """Check if the error should trigger a retry."""
+        if isinstance(error, self.non_retryable_exceptions):
+            return False
+        if self.retryable_exceptions:
+            return isinstance(error, self.retryable_exceptions)
+        return True
+
+    @classmethod
+    def no_retry(cls) -> "RetryConfig":
+        """No retry - fail immediately."""
+        return cls(max_attempts=1)
+
+    @classmethod
+    def quick(cls) -> "RetryConfig":
+        """Quick retry for transient failures."""
+        return cls(
+            max_attempts=3,
+            base_delay=0.05,
+            max_delay=1.0,
+        )
+
+    @classmethod
+    def persistent(cls) -> "RetryConfig":
+        """Persistent retry for important operations."""
+        return cls(
+            max_attempts=5,
+            base_delay=0.5,
+            max_delay=30.0,
+        )
+
+    @classmethod
+    def exponential(cls) -> "RetryConfig":
+        """Standard exponential backoff."""
+        return cls(
+            max_attempts=4,
+            base_delay=0.1,
+            max_delay=10.0,
+            exponential_base=2.0,
+        )
+
+
+@dataclass(frozen=True)
+class BulkheadConfig:
+    """Configuration for bulkhead (resource isolation).
+
+    Attributes:
+        max_concurrent: Maximum concurrent executions.
+        max_wait_time: Maximum time to wait for a slot in seconds.
+        fairness: Whether to use fair ordering for waiting requests.
+    """
+
+    max_concurrent: int = 10
+    max_wait_time: float = 0.0
+    fairness: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate configuration."""
+        if self.max_concurrent <= 0:
+            raise ValueError("max_concurrent must be positive")
+        if self.max_wait_time < 0:
+            raise ValueError("max_wait_time must be non-negative")
+
+    @classmethod
+    def small(cls) -> "BulkheadConfig":
+        """Small bulkhead for limited resources."""
+        return cls(max_concurrent=5)
+
+    @classmethod
+    def medium(cls) -> "BulkheadConfig":
+        """Medium bulkhead for moderate concurrency."""
+        return cls(max_concurrent=20)
+
+    @classmethod
+    def large(cls) -> "BulkheadConfig":
+        """Large bulkhead for high concurrency."""
+        return cls(max_concurrent=50)
+
+    @classmethod
+    def for_database(cls) -> "BulkheadConfig":
+        """Optimized for database connection pools."""
+        return cls(max_concurrent=10, max_wait_time=5.0)
+
+
+@dataclass(frozen=True)
+class RateLimiterConfig:
+    """Configuration for rate limiter.
+
+    Attributes:
+        rate: Number of permits per period.
+        period_seconds: Period duration in seconds.
+        burst_size: Maximum burst size (for token bucket).
+        algorithm: Rate limiting algorithm ('token_bucket', 'sliding_window', 'fixed_window').
+    """
+
+    rate: int = 100
+    period_seconds: float = 1.0
+    burst_size: int | None = None
+    algorithm: str = "token_bucket"
+
+    def __post_init__(self) -> None:
+        """Validate configuration."""
+        if self.rate <= 0:
+            raise ValueError("rate must be positive")
+        if self.period_seconds <= 0:
+            raise ValueError("period_seconds must be positive")
+        if self.burst_size is not None and self.burst_size < 0:
+            raise ValueError("burst_size must be non-negative")
+        valid_algorithms = {"token_bucket", "sliding_window", "fixed_window"}
+        if self.algorithm not in valid_algorithms:
+            raise ValueError(f"algorithm must be one of {valid_algorithms}")
+
+    @property
+    def effective_burst_size(self) -> int:
+        """Get effective burst size (defaults to rate if not set)."""
+        return self.burst_size if self.burst_size is not None else self.rate
+
+    @classmethod
+    def per_second(cls, rate: int, burst: int | None = None) -> "RateLimiterConfig":
+        """Create rate limiter for N requests per second."""
+        return cls(rate=rate, period_seconds=1.0, burst_size=burst)
+
+    @classmethod
+    def per_minute(cls, rate: int, burst: int | None = None) -> "RateLimiterConfig":
+        """Create rate limiter for N requests per minute."""
+        return cls(rate=rate, period_seconds=60.0, burst_size=burst)
+
+    @classmethod
+    def per_hour(cls, rate: int, burst: int | None = None) -> "RateLimiterConfig":
+        """Create rate limiter for N requests per hour."""
+        return cls(rate=rate, period_seconds=3600.0, burst_size=burst)