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

provide/foundation/observability/__init__.py

@@ -17,7 +17,7 @@ except ImportError:
 # Only import OpenObserve if OpenTelemetry is available
 if _HAS_OTEL:
     try:
-        from provide.foundation.observability.openobserve import (
+        from provide.foundation.integrations.openobserve import (
             OpenObserveClient,
             search_logs,
             stream_logs,
@@ -25,7 +25,7 @@ if _HAS_OTEL:
 
         # Commands will auto-register if click is available
         try:
-            from provide.foundation.observability.openobserve.commands import (
+            from provide.foundation.integrations.openobserve.commands import (
                 openobserve_group,
             )
         except ImportError:

provide/foundation/process/__init__.py

@@ -10,6 +10,11 @@ from provide.foundation.process.async_runner import (
     async_run_shell,
     async_stream_command,
 )
+from provide.foundation.process.exit import (
+    exit_success,
+    exit_error,
+    exit_interrupted,
+)
 from provide.foundation.process.lifecycle import (
     ManagedProcess,
     wait_for_process_output,
@@ -36,4 +41,8 @@ __all__ = [
     # Process lifecycle management
     "ManagedProcess",
     "wait_for_process_output",
+    # Exit utilities
+    "exit_success",
+    "exit_error",
+    "exit_interrupted",
 ]

provide/foundation/process/exit.py

@@ -0,0 +1,47 @@
+"""Process exit utilities for standardized exit handling."""
+
+import sys
+
+from provide.foundation.config.defaults import EXIT_SUCCESS, EXIT_ERROR, EXIT_SIGINT
+
+
+def _get_logger():
+    """Get logger instance lazily to avoid circular imports."""
+    from provide.foundation.logger import logger
+    return logger
+
+
+def exit_success(message: str | None = None) -> None:
+    """Exit with success status.
+    
+    Args:
+        message: Optional message to log before exiting
+    """
+    if message:
+        logger = _get_logger()
+        logger.info(f"Exiting successfully: {message}")
+    sys.exit(EXIT_SUCCESS)
+
+
+def exit_error(message: str | None = None, code: int = EXIT_ERROR) -> None:
+    """Exit with error status.
+    
+    Args:
+        message: Optional error message to log before exiting
+        code: Exit code to use (defaults to EXIT_ERROR)
+    """
+    if message:
+        logger = _get_logger()
+        logger.error(f"Exiting with error: {message}", exit_code=code)
+    sys.exit(code)
+
+
+def exit_interrupted(message: str = "Process interrupted") -> None:
+    """Exit due to interrupt signal (SIGINT).
+    
+    Args:
+        message: Message to log before exiting
+    """
+    logger = _get_logger()
+    logger.warning(f"Exiting due to interrupt: {message}")
+    sys.exit(EXIT_SIGINT)

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_READLINE_TIMEOUT,
+    DEFAULT_PROCESS_READCHAR_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
 
@@ -112,6 +119,9 @@ 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 +135,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 +186,7 @@ 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 +221,7 @@ 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 +258,7 @@ 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 +340,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:
     """

provide/foundation/resilience/__init__.py

@@ -0,0 +1,35 @@
+"""
+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,164 @@
+"""
+Circuit breaker implementation for preventing cascading failures.
+"""
+
+import asyncio
+import time
+from enum import Enum
+from typing import Any, Callable, TypeVar
+
+from attrs import define, field
+
+from provide.foundation.logger import logger
+
+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,220 @@
+"""
+Resilience decorators for retry, circuit breaker, and fallback patterns.
+"""
+
+import asyncio
+import functools
+import time
+from typing import Any, Callable, TypeVar
+
+from attrs import define, field
+
+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