provide-foundation 0.0.0.dev1__py3-none-any.whl → 0.0.0.dev3__py3-none-any.whl

provide/foundation/process/lifecycle.py

@@ -16,6 +16,13 @@ import threading
 import traceback
 from typing import Any
 
+from provide.foundation.config.defaults import (
+    DEFAULT_PROCESS_READCHAR_TIMEOUT,
+    DEFAULT_PROCESS_READLINE_TIMEOUT,
+    DEFAULT_PROCESS_TERMINATE_TIMEOUT,
+    DEFAULT_PROCESS_WAIT_TIMEOUT,
+)
+from provide.foundation.errors.decorators import with_error_handling
 from provide.foundation.logger import get_logger
 from provide.foundation.process.runner import ProcessError
 
@@ -69,13 +76,13 @@ class ManagedProcess:
 
         # Build environment - always start with current environment
         self._env = os.environ.copy()
-        
+
         # Clean coverage-related environment variables from subprocess
         # to prevent interference with output capture during testing
         for key in list(self._env.keys()):
-            if key.startswith(('COVERAGE', 'COV_CORE')):
+            if key.startswith(("COVERAGE", "COV_CORE")):
                 self._env.pop(key, None)
-        
+
         # Merge in any provided environment variables
         if env:
             self._env.update(env)
@@ -112,6 +119,11 @@ class ManagedProcess:
             return False
         return self._process.poll() is None
 
+    @with_error_handling(
+        error_mapper=lambda e: ProcessError(f"Failed to launch process: {e}")
+        if not isinstance(e, (ProcessError, RuntimeError))
+        else e
+    )
     def launch(self) -> None:
         """
         Launch the managed process.
@@ -125,37 +137,27 @@ class ManagedProcess:
 
         plog.debug("🚀 Launching managed process", command=" ".join(self.command))
 
-        try:
-            self._process = subprocess.Popen(
-                self.command,
-                cwd=self.cwd,
-                env=self._env,
-                stdout=subprocess.PIPE if self.capture_output else None,
-                stderr=subprocess.PIPE if self.capture_output else None,
-                text=self.text_mode,
-                bufsize=self.bufsize,
-                **self.kwargs,
-            )
-            self._started = True
-
-            plog.info(
-                "🚀 Managed process started successfully",
-                pid=self._process.pid,
-                command=" ".join(self.command),
-            )
+        self._process = subprocess.Popen(
+            self.command,
+            cwd=self.cwd,
+            env=self._env,
+            stdout=subprocess.PIPE if self.capture_output else None,
+            stderr=subprocess.PIPE if self.capture_output else None,
+            text=self.text_mode,
+            bufsize=self.bufsize,
+            **self.kwargs,
+        )
+        self._started = True
 
-            # Start stderr relay if enabled
-            if self.stderr_relay and self._process.stderr:
-                self._start_stderr_relay()
+        plog.info(
+            "🚀 Managed process started successfully",
+            pid=self._process.pid,
+            command=" ".join(self.command),
+        )
 
-        except Exception as e:
-            plog.error(
-                "🚀❌ Failed to launch managed process",
-                command=" ".join(self.command),
-                error=str(e),
-                trace=traceback.format_exc(),
-            )
-            raise ProcessError(f"Failed to launch process: {e}") from e
+        # Start stderr relay if enabled
+        if self.stderr_relay and self._process.stderr:
+            self._start_stderr_relay()
 
     def _start_stderr_relay(self) -> None:
         """Start a background thread to relay stderr output."""
@@ -186,7 +188,9 @@ class ManagedProcess:
         self._stderr_thread.start()
         plog.debug("🚀 Started stderr relay thread")
 
-    async def read_line_async(self, timeout: float = 2.0) -> str:
+    async def read_line_async(
+        self, timeout: float = DEFAULT_PROCESS_READLINE_TIMEOUT
+    ) -> str:
         """
         Read a line from stdout asynchronously with timeout.
 
@@ -221,7 +225,9 @@ class ManagedProcess:
             plog.debug("Read timeout on managed process stdout")
             raise TimeoutError(f"Read timeout after {timeout}s") from e
 
-    async def read_char_async(self, timeout: float = 1.0) -> str:
+    async def read_char_async(
+        self, timeout: float = DEFAULT_PROCESS_READCHAR_TIMEOUT
+    ) -> str:
         """
         Read a single character from stdout asynchronously.
 
@@ -258,7 +264,9 @@ class ManagedProcess:
             plog.debug("Character read timeout on managed process stdout")
             raise TimeoutError(f"Character read timeout after {timeout}s") from e
 
-    def terminate_gracefully(self, timeout: float = 7.0) -> bool:
+    def terminate_gracefully(
+        self, timeout: float = DEFAULT_PROCESS_TERMINATE_TIMEOUT
+    ) -> bool:
         """
         Terminate the process gracefully with a timeout.
 
@@ -340,7 +348,7 @@ class ManagedProcess:
 async def wait_for_process_output(
     process: ManagedProcess,
     expected_parts: list[str],
-    timeout: float = 10.0,
+    timeout: float = DEFAULT_PROCESS_WAIT_TIMEOUT,
     buffer_size: int = 1024,
 ) -> str:
     """
@@ -378,7 +386,7 @@ async def wait_for_process_output(
         if not process.is_running():
             last_exit_code = process.returncode
             plog.debug("Process exited", returncode=last_exit_code)
-            
+
             # Try to drain any remaining output from the pipes
             if process._process and process._process.stdout:
                 try:
@@ -389,19 +397,26 @@ async def wait_for_process_output(
                             buffer += remaining.decode("utf-8", errors="replace")
                         else:
                             buffer += str(remaining)
-                        plog.debug("Read remaining output from exited process", size=len(remaining))
+                        plog.debug(
+                            "Read remaining output from exited process",
+                            size=len(remaining),
+                        )
                 except Exception:
                     pass
-            
+
             # Check buffer after draining
             if all(part in buffer for part in expected_parts):
                 plog.debug("Found expected pattern after process exit")
                 return buffer
-            
+
             # If process exited and we don't have the pattern, fail
             if last_exit_code is not None:
                 if last_exit_code != 0:
-                    plog.error("Process exited with error", returncode=last_exit_code, buffer=buffer[:200])
+                    plog.error(
+                        "Process exited with error",
+                        returncode=last_exit_code,
+                        buffer=buffer[:200],
+                    )
                     raise ProcessError(f"Process exited with code {last_exit_code}")
                 else:
                     # For exit code 0, give it a small window to collect buffered output
@@ -412,7 +427,9 @@ async def wait_for_process_output(
                             remaining = process._process.stdout.read()
                             if remaining:
                                 if isinstance(remaining, bytes):
-                                    buffer += remaining.decode("utf-8", errors="replace")
+                                    buffer += remaining.decode(
+                                        "utf-8", errors="replace"
+                                    )
                                 else:
                                     buffer += str(remaining)
                         except Exception:
@@ -422,9 +439,15 @@ async def wait_for_process_output(
                         plog.debug("Found expected pattern after final drain")
                         return buffer
                     # Process exited cleanly but pattern not found
-                    plog.error("Process exited without expected output", returncode=0, buffer=buffer[:200])
-                    raise ProcessError(f"Process exited with code {last_exit_code} before expected output found")
-        
+                    plog.error(
+                        "Process exited without expected output",
+                        returncode=0,
+                        buffer=buffer[:200],
+                    )
+                    raise ProcessError(
+                        f"Process exited with code {last_exit_code} before expected output found"
+                    )
+
         try:
             # Try to read a line with short timeout
             line = await process.read_line_async(timeout=0.1)
@@ -449,7 +472,7 @@ async def wait_for_process_output(
     # Final check of buffer before timeout error
     if all(part in buffer for part in expected_parts):
         return buffer
-    
+
     # If process exited with 0 but we didn't get output, that's still a timeout
     plog.error(
         "Timeout waiting for pattern",

provide/foundation/resilience/__init__.py

@@ -0,0 +1,36 @@
+"""
+Resilience patterns for handling failures and improving reliability.
+
+This module provides unified implementations of common resilience patterns:
+- Retry with configurable backoff strategies
+- Circuit breaker for failing fast
+- Fallback for graceful degradation
+
+These patterns are used throughout foundation to eliminate code duplication
+and provide consistent failure handling.
+"""
+
+from provide.foundation.resilience.circuit import CircuitBreaker, CircuitState
+from provide.foundation.resilience.decorators import circuit_breaker, fallback, retry
+from provide.foundation.resilience.fallback import FallbackChain
+from provide.foundation.resilience.retry import (
+    BackoffStrategy,
+    RetryExecutor,
+    RetryPolicy,
+)
+
+__all__ = [
+    # Core retry functionality
+    "RetryPolicy",
+    "RetryExecutor",
+    "BackoffStrategy",
+    # Circuit breaker
+    "CircuitBreaker",
+    "CircuitState",
+    # Fallback
+    "FallbackChain",
+    # Decorators
+    "retry",
+    "circuit_breaker",
+    "fallback",
+]

provide/foundation/resilience/circuit.py

@@ -0,0 +1,166 @@
+"""
+Circuit breaker implementation for preventing cascading failures.
+"""
+
+from enum import Enum
+import time
+from typing import Callable, TypeVar
+
+from attrs import define, field
+
+from provide.foundation.logger import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+class CircuitState(Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Circuit is open, failing fast
+    HALF_OPEN = "half_open"  # Testing if service has recovered
+
+
+@define(kw_only=True, slots=True)
+class CircuitBreaker:
+    """Circuit breaker pattern for preventing cascading failures.
+
+    Tracks failures and opens the circuit when threshold is exceeded.
+    Periodically allows test requests to check if service has recovered.
+    """
+
+    failure_threshold: int = field(default=5)
+    recovery_timeout: float = field(default=60.0)  # seconds
+    expected_exception: tuple[type[Exception], ...] = field(
+        factory=lambda: (Exception,)
+    )
+
+    # Internal state
+    _state: CircuitState = field(default=CircuitState.CLOSED, init=False)
+    _failure_count: int = field(default=0, init=False)
+    _last_failure_time: float | None = field(default=None, init=False)
+    _next_attempt_time: float = field(default=0.0, init=False)
+
+    @property
+    def state(self) -> CircuitState:
+        """Current circuit breaker state."""
+        return self._state
+
+    @property
+    def failure_count(self) -> int:
+        """Current failure count."""
+        return self._failure_count
+
+    def _should_attempt_reset(self) -> bool:
+        """Check if we should attempt to reset the circuit."""
+        if self._state != CircuitState.OPEN:
+            return False
+
+        current_time = time.time()
+        return current_time >= self._next_attempt_time
+
+    def _record_success(self) -> None:
+        """Record successful execution."""
+        if self._state == CircuitState.HALF_OPEN:
+            logger.info(
+                "Circuit breaker recovered - closing circuit",
+                state="half_open->closed",
+                failure_count=self._failure_count,
+            )
+
+        self._failure_count = 0
+        self._last_failure_time = None
+        self._state = CircuitState.CLOSED
+
+    def _record_failure(self, exception: Exception) -> None:
+        """Record failed execution."""
+        self._failure_count += 1
+        self._last_failure_time = time.time()
+
+        if self._state == CircuitState.HALF_OPEN:
+            # Failed during recovery attempt
+            self._state = CircuitState.OPEN
+            self._next_attempt_time = self._last_failure_time + self.recovery_timeout
+            logger.warning(
+                "Circuit breaker recovery failed - opening circuit",
+                state="half_open->open",
+                failure_count=self._failure_count,
+                next_attempt_in=self.recovery_timeout,
+            )
+        elif self._failure_count >= self.failure_threshold:
+            # Threshold exceeded, open circuit
+            self._state = CircuitState.OPEN
+            self._next_attempt_time = self._last_failure_time + self.recovery_timeout
+            logger.error(
+                "Circuit breaker opened due to failures",
+                state="closed->open",
+                failure_count=self._failure_count,
+                failure_threshold=self.failure_threshold,
+                next_attempt_in=self.recovery_timeout,
+            )
+
+    def call(self, func: Callable[..., T], *args, **kwargs) -> T:
+        """Execute function with circuit breaker protection (sync)."""
+        # Check if circuit is open
+        if self._state == CircuitState.OPEN:
+            if self._should_attempt_reset():
+                self._state = CircuitState.HALF_OPEN
+                logger.info(
+                    "Circuit breaker attempting recovery",
+                    state="open->half_open",
+                    failure_count=self._failure_count,
+                )
+            else:
+                raise RuntimeError(
+                    f"Circuit breaker is open. Next attempt in "
+                    f"{self._next_attempt_time - time.time():.1f} seconds"
+                )
+
+        try:
+            result = func(*args, **kwargs)
+            self._record_success()
+            return result
+        except Exception as e:
+            if isinstance(e, self.expected_exception):
+                self._record_failure(e)
+            raise
+
+    async def call_async(self, func: Callable[..., T], *args, **kwargs) -> T:
+        """Execute async function with circuit breaker protection."""
+        # Check if circuit is open
+        if self._state == CircuitState.OPEN:
+            if self._should_attempt_reset():
+                self._state = CircuitState.HALF_OPEN
+                logger.info(
+                    "Circuit breaker attempting recovery",
+                    state="open->half_open",
+                    failure_count=self._failure_count,
+                )
+            else:
+                raise RuntimeError(
+                    f"Circuit breaker is open. Next attempt in "
+                    f"{self._next_attempt_time - time.time():.1f} seconds"
+                )
+
+        try:
+            result = await func(*args, **kwargs)
+            self._record_success()
+            return result
+        except Exception as e:
+            if isinstance(e, self.expected_exception):
+                self._record_failure(e)
+            raise
+
+    def reset(self) -> None:
+        """Manually reset the circuit breaker."""
+        logger.info(
+            "Circuit breaker manually reset",
+            previous_state=self._state.value,
+            failure_count=self._failure_count,
+        )
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._last_failure_time = None
+        self._next_attempt_time = 0.0

provide/foundation/resilience/decorators.py

@@ -0,0 +1,236 @@
+"""
+Resilience decorators for retry, circuit breaker, and fallback patterns.
+"""
+
+import asyncio
+import functools
+from typing import Any, Callable, TypeVar
+
+from provide.foundation.config.defaults import DEFAULT_CIRCUIT_BREAKER_RECOVERY_TIMEOUT
+from provide.foundation.resilience.retry import (
+    BackoffStrategy,
+    RetryExecutor,
+    RetryPolicy,
+)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _get_logger():
+    """Get logger instance lazily to avoid circular imports."""
+    from provide.foundation.logger import logger
+
+    return logger
+
+
+def retry(
+    *exceptions: type[Exception],
+    policy: RetryPolicy | None = None,
+    max_attempts: int | None = None,
+    base_delay: float | None = None,
+    backoff: BackoffStrategy | None = None,
+    max_delay: float | None = None,
+    jitter: bool | None = None,
+    on_retry: Callable[[int, Exception], None] | None = None,
+) -> Callable[[F], F]:
+    """
+    Decorator for retrying operations on errors.
+
+    Can be used in multiple ways:
+
+    1. With a policy object:
+        @retry(policy=RetryPolicy(max_attempts=5))
+
+    2. With individual parameters:
+        @retry(max_attempts=3, base_delay=1.0)
+
+    3. With specific exceptions:
+        @retry(ConnectionError, TimeoutError, max_attempts=3)
+
+    4. Without parentheses (uses defaults):
+        @retry
+        def my_func(): ...
+
+    Args:
+        *exceptions: Exception types to retry (all if empty)
+        policy: Complete retry policy (overrides other params)
+        max_attempts: Maximum retry attempts
+        base_delay: Base delay between retries
+        backoff: Backoff strategy
+        max_delay: Maximum delay cap
+        jitter: Whether to add jitter
+        on_retry: Callback for retry events
+
+    Returns:
+        Decorated function with retry logic
+
+    Examples:
+        >>> @retry(max_attempts=3)
+        ... def flaky_operation():
+        ...     # May fail occasionally
+        ...     pass
+
+        >>> @retry(ConnectionError, max_attempts=5, base_delay=2.0)
+        ... async def connect_to_service():
+        ...     # Async function with specific error handling
+        ...     pass
+    """
+    # Handle decorator without parentheses
+    if (
+        len(exceptions) == 1
+        and callable(exceptions[0])
+        and not isinstance(exceptions[0], type)
+    ):
+        # Called as @retry without parentheses
+        func = exceptions[0]
+        executor = RetryExecutor(RetryPolicy())
+
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                return await executor.execute_async(func, *args, **kwargs)
+
+            return async_wrapper
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                return executor.execute_sync(func, *args, **kwargs)
+
+            return sync_wrapper
+
+    # Build policy if not provided
+    if policy is not None and any(
+        p is not None for p in [max_attempts, base_delay, backoff, max_delay, jitter]
+    ):
+        raise ValueError("Cannot specify both policy and individual retry parameters")
+
+    if policy is None:
+        # Build policy from parameters
+        policy_kwargs = {}
+
+        if max_attempts is not None:
+            policy_kwargs["max_attempts"] = max_attempts
+        if base_delay is not None:
+            policy_kwargs["base_delay"] = base_delay
+        if backoff is not None:
+            policy_kwargs["backoff"] = backoff
+        if max_delay is not None:
+            policy_kwargs["max_delay"] = max_delay
+        if jitter is not None:
+            policy_kwargs["jitter"] = jitter
+        if exceptions:
+            policy_kwargs["retryable_errors"] = exceptions
+
+        policy = RetryPolicy(**policy_kwargs)
+
+    def decorator(func: F) -> F:
+        executor = RetryExecutor(policy, on_retry=on_retry)
+
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                return await executor.execute_async(func, *args, **kwargs)
+
+            return async_wrapper
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                return executor.execute_sync(func, *args, **kwargs)
+
+            return sync_wrapper
+
+    return decorator
+
+
+# Import CircuitBreaker from circuit module
+from provide.foundation.resilience.circuit import CircuitBreaker
+
+
+def circuit_breaker(
+    failure_threshold: int = 5,
+    recovery_timeout: float = DEFAULT_CIRCUIT_BREAKER_RECOVERY_TIMEOUT,
+    expected_exception: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[F], F]:
+    """Create a circuit breaker decorator.
+
+    Args:
+        failure_threshold: Number of failures before opening circuit.
+        recovery_timeout: Seconds to wait before attempting recovery.
+        expected_exception: Exception types that trigger the breaker.
+
+    Returns:
+        Circuit breaker decorator.
+
+    Examples:
+        >>> @circuit_breaker(failure_threshold=3, recovery_timeout=30)
+        ... def unreliable_service():
+        ...     return external_api_call()
+    """
+    breaker = CircuitBreaker(
+        failure_threshold=failure_threshold,
+        recovery_timeout=recovery_timeout,
+        expected_exception=expected_exception,
+    )
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            return breaker.call(func, *args, **kwargs)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            return await breaker.call_async(func, *args, **kwargs)
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        else:
+            return sync_wrapper  # type: ignore
+
+    return decorator
+
+
+def fallback(*fallback_funcs: Callable[..., Any]) -> Callable[[F], F]:
+    """
+    Fallback decorator using FallbackChain.
+
+    Args:
+        *fallback_funcs: Functions to use as fallbacks, in order of preference
+
+    Returns:
+        Decorated function with fallback chain
+
+    Examples:
+        >>> def backup_api():
+        ...     return "backup result"
+        ...
+        >>> @fallback(backup_api)
+        ... def primary_api():
+        ...     return external_api_call()
+    """
+    from provide.foundation.resilience.fallback import FallbackChain
+
+    def decorator(func: F) -> F:
+        chain = FallbackChain()
+        for fallback_func in fallback_funcs:
+            chain.add_fallback(fallback_func)
+
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                return await chain.execute_async(func, *args, **kwargs)
+
+            return async_wrapper  # type: ignore
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                return chain.execute(func, *args, **kwargs)
+
+            return sync_wrapper  # type: ignore
+
+    return decorator