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

provide/foundation/metrics/otel.py

@@ -1,9 +1,9 @@
 """OpenTelemetry metrics integration."""
 
-from provide.foundation.logger import get_logger
 from provide.foundation.logger.config.telemetry import TelemetryConfig
+from provide.foundation.logger.setup import get_vanilla_logger
 
-log = get_logger(__name__)
+slog = get_vanilla_logger(__name__)
 
 # Feature detection
 try:
@@ -47,15 +47,15 @@ def setup_opentelemetry_metrics(config: TelemetryConfig) -> None:
     """
     # Check if metrics are disabled first, before checking dependencies
     if not config.metrics_enabled or config.globally_disabled:
-        log.debug("📊 OpenTelemetry metrics disabled")
+        slog.debug("📊 OpenTelemetry metrics disabled")
         return
 
     # Check if OpenTelemetry metrics are available
     if not _HAS_OTEL_METRICS:
-        log.debug("📊 OpenTelemetry metrics not available (dependencies not installed)")
+        slog.debug("📊 OpenTelemetry metrics not available (dependencies not installed)")
         return
 
-    log.debug("📊🚀 Setting up OpenTelemetry metrics")
+    slog.debug("📊🚀 Setting up OpenTelemetry metrics")
 
     # Create resource with service information
     resource_attrs = {}
@@ -73,7 +73,7 @@ def setup_opentelemetry_metrics(config: TelemetryConfig) -> None:
         endpoint = config.otlp_endpoint
         headers = config.get_otlp_headers_dict()
 
-        log.debug(f"📊📤 Configuring OTLP metrics exporter: {endpoint}")
+        slog.debug(f"📊📤 Configuring OTLP metrics exporter: {endpoint}")
 
         # Choose exporter based on protocol
         if config.otlp_protocol == "grpc":
@@ -91,7 +91,7 @@ def setup_opentelemetry_metrics(config: TelemetryConfig) -> None:
         reader = PeriodicExportingMetricReader(exporter, export_interval_millis=60000)
         readers.append(reader)
 
-        log.debug(f"✅ OTLP metrics exporter configured: {config.otlp_protocol}")
+        slog.debug(f"✅ OTLP metrics exporter configured: {config.otlp_protocol}")
 
     # Create meter provider
     meter_provider = MeterProvider(resource=resource, metric_readers=readers)
@@ -105,7 +105,7 @@ def setup_opentelemetry_metrics(config: TelemetryConfig) -> None:
     meter = otel_metrics.get_meter(__name__)
     _set_meter(meter)
 
-    log.info("📊✅ OpenTelemetry metrics setup complete")
+    slog.info("📊✅ OpenTelemetry metrics setup complete")
 
 
 def shutdown_opentelemetry_metrics() -> None:
@@ -117,6 +117,6 @@ def shutdown_opentelemetry_metrics() -> None:
         meter_provider = otel_metrics.get_meter_provider()
         if hasattr(meter_provider, "shutdown"):
             meter_provider.shutdown()
-            log.debug("📊🛑 OpenTelemetry meter provider shutdown")
+            slog.debug("📊🛑 OpenTelemetry meter provider shutdown")
     except Exception as e:
-        log.warning(f"⚠️ Error shutting down OpenTelemetry metrics: {e}")
+        slog.warning(f"⚠️ Error shutting down OpenTelemetry metrics: {e}")

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
 
@@ -67,8 +74,16 @@ class ManagedProcess:
         self.stderr_relay = stderr_relay
         self.kwargs = kwargs
 
-        # Build environment
+        # 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')):
+                self._env.pop(key, None)
+        
+        # Merge in any provided environment variables
         if env:
             self._env.update(env)
 
@@ -104,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.
@@ -117,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."""
@@ -178,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.
 
@@ -213,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.
 
@@ -250,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.
 
@@ -332,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:
     """
@@ -357,6 +365,7 @@ async def wait_for_process_output(
     loop = asyncio.get_event_loop()
     start_time = loop.time()
     buffer = ""
+    last_exit_code = None
 
     plog.debug(
         "⏳ Waiting for process output pattern",
@@ -365,17 +374,62 @@ async def wait_for_process_output(
     )
 
     while (loop.time() - start_time) < timeout:
-        # Check if process is still running
+        # Check if process has exited
         if not process.is_running():
-            returncode = process.returncode
-            plog.error("Process exited unexpectedly", returncode=returncode)
-            raise ProcessError(f"Process exited with code {returncode}")
-
+            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:
+                    # Non-blocking read of any remaining data
+                    remaining = process._process.stdout.read()
+                    if remaining:
+                        if isinstance(remaining, bytes):
+                            buffer += remaining.decode("utf-8", errors="replace")
+                        else:
+                            buffer += str(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])
+                    raise ProcessError(f"Process exited with code {last_exit_code}")
+                else:
+                    # For exit code 0, give it a small window to collect buffered output
+                    await asyncio.sleep(0.1)
+                    # Try one more time to drain output
+                    if process._process and process._process.stdout:
+                        try:
+                            remaining = process._process.stdout.read()
+                            if remaining:
+                                if isinstance(remaining, bytes):
+                                    buffer += remaining.decode("utf-8", errors="replace")
+                                else:
+                                    buffer += str(remaining)
+                        except Exception:
+                            pass
+                    # Final check
+                    if all(part in buffer for part in expected_parts):
+                        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")
+        
         try:
-            # Try to read a line first
-            line = await process.read_line_async(timeout=2.0)
+            # Try to read a line with short timeout
+            line = await process.read_line_async(timeout=0.1)
             if line:
-                buffer += line
+                buffer += line + "\n"  # Add newline back since readline strips it
                 plog.debug("Read line from process", line=line[:100])
 
                 # Check if we have all expected parts
@@ -384,23 +438,25 @@ async def wait_for_process_output(
                     return buffer
 
         except TimeoutError:
-            plog.debug("Line read timeout, trying character-by-character")
-
-        try:
-            # Fall back to character-by-character reading
-            char = await process.read_char_async(timeout=1.0)
-            if char:
-                buffer += char
-                plog.debug("Read character", char=repr(char), buffer_size=len(buffer))
-
-                # Check pattern again
-                if all(part in buffer for part in expected_parts):
-                    plog.debug("Found expected pattern in buffer (char mode)")
-                    return buffer
-
-        except TimeoutError:
-            await asyncio.sleep(0.25)
-
+            pass
+        except Exception:
+            # Process might have exited, continue
+            pass
+
+        # Short sleep to avoid busy loop
+        await asyncio.sleep(0.01)
+
+    # 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",
+        expected_parts=expected_parts,
+        buffer=buffer[:200],
+        last_exit_code=last_exit_code,
+    )
     raise TimeoutError(
         f"Expected pattern {expected_parts} not found within {timeout}s timeout"
     )

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