taipanstack 0.1.0__py3-none-any.whl

taipanstack/utils/retry.py

@@ -0,0 +1,300 @@
+"""
+Retry logic with exponential backoff.
+
+Provides decorators for automatic retry of failing operations
+with configurable backoff strategies. Compatible with any
+Python framework (sync and async).
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import random
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+logger = logging.getLogger("taipanstack.utils.retry")
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Configuration for retry behavior.
+
+    Attributes:
+        max_attempts: Maximum number of retry attempts.
+        initial_delay: Initial delay between retries in seconds.
+        max_delay: Maximum delay between retries.
+        exponential_base: Base for exponential backoff (2 = double each time).
+        jitter: Whether to add random jitter to delays.
+        jitter_factor: Maximum jitter as fraction of delay (0.1 = 10%).
+
+    """
+
+    max_attempts: int = 3
+    initial_delay: float = 1.0
+    max_delay: float = 60.0
+    exponential_base: float = 2.0
+    jitter: bool = True
+    jitter_factor: float = 0.1
+
+
+class RetryError(Exception):
+    """Raised when all retry attempts have failed."""
+
+    def __init__(
+        self,
+        message: str,
+        attempts: int,
+        last_exception: Exception | None = None,
+    ) -> None:
+        """Initialize RetryError.
+
+        Args:
+            message: Description of the retry failure.
+            attempts: Number of attempts made.
+            last_exception: The last exception that was raised.
+
+        """
+        self.attempts = attempts
+        self.last_exception = last_exception
+        super().__init__(message)
+
+
+def calculate_delay(
+    attempt: int,
+    config: RetryConfig,
+) -> float:
+    """Calculate delay before next retry.
+
+    Args:
+        attempt: Current attempt number (1-indexed).
+        config: Retry configuration.
+
+    Returns:
+        Delay in seconds before next retry.
+
+    """
+    # Exponential backoff
+    delay = config.initial_delay * (config.exponential_base ** (attempt - 1))
+
+    # Cap at max delay
+    delay = min(delay, config.max_delay)
+
+    # Add jitter if enabled
+    if config.jitter:
+        jitter_amount = delay * config.jitter_factor
+        delay += random.uniform(-jitter_amount, jitter_amount)
+
+    return max(0, delay)
+
+
+def retry(
+    *,
+    max_attempts: int = 3,
+    initial_delay: float = 1.0,
+    max_delay: float = 60.0,
+    exponential_base: float = 2.0,
+    jitter: bool = True,
+    on: tuple[type[Exception], ...] = (Exception,),
+    reraise: bool = True,
+    log_retries: bool = True,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Retry a function with exponential backoff.
+
+    Automatically retries the decorated function when specified
+    exceptions are raised, with configurable backoff strategy.
+
+    Args:
+        max_attempts: Maximum number of retry attempts.
+        initial_delay: Initial delay between retries in seconds.
+        max_delay: Maximum delay between retries.
+        exponential_base: Base for exponential backoff.
+        jitter: Whether to add random jitter to delays.
+        on: Exception types to retry on.
+        reraise: Whether to reraise the last exception on failure.
+        log_retries: Whether to log retry attempts.
+
+    Returns:
+        Decorated function with retry logic.
+
+    Example:
+        >>> @retry(max_attempts=3, on=(ConnectionError, TimeoutError))
+        ... def fetch_data(url: str) -> dict:
+        ...     return requests.get(url).json()
+
+    """
+    config = RetryConfig(
+        max_attempts=max_attempts,
+        initial_delay=initial_delay,
+        max_delay=max_delay,
+        exponential_base=exponential_base,
+        jitter=jitter,
+    )
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            last_exception: Exception | None = None
+
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    return func(*args, **kwargs)
+                except on as e:
+                    last_exception = e
+
+                    if attempt == max_attempts:
+                        # Last attempt failed
+                        if log_retries:
+                            logger.warning(
+                                "All %d attempts failed for %s: %s",
+                                max_attempts,
+                                func.__name__,
+                                str(e),
+                            )
+                        break
+
+                    # Calculate delay and wait
+                    delay = calculate_delay(attempt, config)
+
+                    if log_retries:
+                        logger.info(
+                            "Attempt %d/%d failed for %s: %s. "
+                            "Retrying in %.2f seconds...",
+                            attempt,
+                            max_attempts,
+                            func.__name__,
+                            str(e),
+                            delay,
+                        )
+
+                    time.sleep(delay)
+
+            # All attempts failed
+            if reraise and last_exception is not None:
+                raise RetryError(
+                    f"All {max_attempts} attempts failed for {func.__name__}",
+                    attempts=max_attempts,
+                    last_exception=last_exception,
+                ) from last_exception
+
+            # Should never reach here if reraise=True
+            raise RetryError(
+                f"All {max_attempts} attempts failed for {func.__name__}",
+                attempts=max_attempts,
+                last_exception=last_exception,
+            )
+
+        return wrapper
+
+    return decorator
+
+
+def retry_on_exception(
+    exception_types: tuple[type[Exception], ...],
+    max_attempts: int = 3,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Retry on specific exceptions.
+
+    A simpler alternative to the full retry decorator when you
+    just need basic retry functionality.
+
+    Args:
+        exception_types: Exception types to retry on.
+        max_attempts: Maximum number of attempts.
+
+    Returns:
+        Decorated function with retry logic.
+
+    Example:
+        >>> @retry_on_exception((ValueError,), max_attempts=2)
+        ... def parse_data(data: str) -> dict:
+        ...     return json.loads(data)
+
+    """
+    return retry(
+        max_attempts=max_attempts,
+        on=exception_types,
+        jitter=False,
+        log_retries=False,
+    )
+
+
+class Retrier:
+    """Context manager for retry logic.
+
+    Provides a context manager interface for retry logic when
+    decorators are not suitable.
+
+    Example:
+        >>> retrier = Retrier(max_attempts=3, on=(ConnectionError,))
+        >>> with retrier:
+        ...     result = some_operation()
+
+    """
+
+    def __init__(
+        self,
+        *,
+        max_attempts: int = 3,
+        initial_delay: float = 1.0,
+        max_delay: float = 60.0,
+        on: tuple[type[Exception], ...] = (Exception,),
+    ) -> None:
+        """Initialize Retrier.
+
+        Args:
+            max_attempts: Maximum retry attempts.
+            initial_delay: Initial delay between retries.
+            max_delay: Maximum delay between retries.
+            on: Exception types to retry on.
+
+        """
+        self.config = RetryConfig(
+            max_attempts=max_attempts,
+            initial_delay=initial_delay,
+            max_delay=max_delay,
+        )
+        self.exception_types = on
+        self.attempt = 0
+        self.last_exception: Exception | None = None
+
+    def __enter__(self) -> Retrier:
+        """Enter the retry context."""
+        self.attempt = 0
+        self.last_exception = None
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[Exception] | None,
+        exc_val: Exception | None,
+        exc_tb: Any,
+    ) -> bool:
+        """Exit the retry context.
+
+        Returns True to suppress the exception if we should retry,
+        False to let it propagate.
+        """
+        if exc_type is None:
+            return False  # No exception, exit normally
+
+        if not issubclass(exc_type, self.exception_types):
+            return False  # Exception type not in retry list
+
+        self.last_exception = exc_val
+        self.attempt += 1
+
+        if self.attempt >= self.config.max_attempts:
+            return False  # Max attempts reached, propagate exception
+
+        # Calculate delay and wait
+        delay = calculate_delay(self.attempt, self.config)
+        time.sleep(delay)
+
+        return True  # Suppress exception and retry

taipanstack/utils/subprocess.py

@@ -0,0 +1,344 @@
+"""
+Safe subprocess execution with security guards.
+
+Provides secure wrappers around subprocess execution with
+command validation, timeout handling, and retry logic.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from taipanstack.security.guards import SecurityError, guard_command_injection
+
+
+@dataclass(frozen=True)
+class SafeCommandResult:
+    """Result of a safe command execution.
+
+    Attributes:
+        command: The executed command.
+        returncode: Exit code of the command.
+        stdout: Standard output.
+        stderr: Standard error.
+        success: Whether the command succeeded (returncode == 0).
+        duration_seconds: How long the command took.
+
+    """
+
+    command: list[str]
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+    duration_seconds: float = 0.0
+
+    @property
+    def success(self) -> bool:
+        """Check if command succeeded."""
+        return self.returncode == 0
+
+    def raise_on_error(self) -> SafeCommandResult:
+        """Raise an exception if command failed.
+
+        Returns:
+            Self if successful.
+
+        Raises:
+            subprocess.CalledProcessError: If command failed.
+
+        """
+        if not self.success:
+            raise subprocess.CalledProcessError(
+                self.returncode,
+                self.command,
+                self.stdout,
+                self.stderr,
+            )
+        return self
+
+
+# Default allowed commands whitelist
+DEFAULT_ALLOWED_COMMANDS: frozenset[str] = frozenset(
+    {
+        # Python/Poetry
+        "python",
+        "python3",
+        "pip",
+        "pip3",
+        "poetry",
+        "pipx",
+        # Version control
+        "git",
+        # Build tools
+        "make",
+        # Testing
+        "pytest",
+        "mypy",
+        "ruff",
+        "bandit",
+        "safety",
+        "semgrep",
+        "pre-commit",
+        # System
+        "echo",
+        "cat",
+        "ls",
+        "pwd",
+        "mkdir",
+        "rm",
+        "cp",
+        "mv",
+        "touch",
+        "chmod",
+        "which",
+    }
+)
+
+
+def run_safe_command(
+    command: Sequence[str],
+    *,
+    cwd: Path | str | None = None,
+    timeout: float = 300.0,
+    capture_output: bool = True,
+    check: bool = False,
+    allowed_commands: Sequence[str] | None = None,
+    env: dict[str, str] | None = None,
+    dry_run: bool = False,
+) -> SafeCommandResult:
+    """Execute a command safely with security guards.
+
+    This function provides a secure wrapper around subprocess.run
+    with command injection protection, timeout handling, and
+    optional command whitelisting.
+
+    Args:
+        command: Command and arguments as a sequence.
+        cwd: Working directory for the command.
+        timeout: Maximum execution time in seconds.
+        capture_output: Whether to capture stdout/stderr.
+        check: Whether to raise on non-zero exit.
+        allowed_commands: Whitelist of allowed commands.
+        env: Environment variables to set.
+        dry_run: If True, don't actually execute the command.
+
+    Returns:
+        SafeCommandResult with execution details.
+
+    Raises:
+        SecurityError: If command validation fails.
+        subprocess.TimeoutExpired: If command times out.
+        subprocess.CalledProcessError: If check=True and command fails.
+
+    Example:
+        >>> result = run_safe_command(["poetry", "install"])
+        >>> if result.success:
+        ...     print("Installation complete!")
+
+    """
+    # Convert to list
+    cmd_list = list(command)
+
+    if not cmd_list:
+        raise SecurityError(
+            "Empty command is not allowed",
+            guard_name="safe_command",
+        )
+
+    # Get command whitelist
+    if allowed_commands is not None:
+        whitelist = list(allowed_commands)
+    else:
+        whitelist = list(DEFAULT_ALLOWED_COMMANDS)
+
+    # Validate command against guards
+    validated_cmd = guard_command_injection(cmd_list, allowed_commands=whitelist)
+
+    # Verify command exists
+    base_command = validated_cmd[0]
+    if not shutil.which(base_command):
+        raise SecurityError(
+            f"Command not found: {base_command}",
+            guard_name="safe_command",
+            value=base_command,
+        )
+
+    # Handle dry run
+    if dry_run:
+        return SafeCommandResult(
+            command=validated_cmd,
+            returncode=0,
+            stdout=f"[DRY-RUN] Would execute: {' '.join(validated_cmd)}",
+            stderr="",
+            duration_seconds=0.0,
+        )
+
+    # Resolve working directory
+    if cwd is not None:
+        cwd = Path(cwd).resolve()
+        if not cwd.exists():
+            raise SecurityError(
+                f"Working directory does not exist: {cwd}",
+                guard_name="safe_command",
+            )
+
+    # Execute command
+    start_time = time.time()
+
+    try:
+        result = subprocess.run(
+            validated_cmd,
+            cwd=cwd,
+            timeout=timeout,
+            capture_output=capture_output,
+            text=True,
+            encoding="utf-8",
+            env=env,
+            check=False,  # We handle check ourselves
+        )
+    except subprocess.TimeoutExpired as e:
+        duration = time.time() - start_time
+        stdout_str = ""
+        if hasattr(e, "stdout") and e.stdout is not None:
+            if isinstance(e.stdout, str):
+                stdout_str = e.stdout
+            else:
+                stdout_str = e.stdout.decode("utf-8", errors="replace")
+        return SafeCommandResult(
+            command=validated_cmd,
+            returncode=-1,
+            stdout=stdout_str,
+            stderr=f"Command timed out after {timeout}s",
+            duration_seconds=duration,
+        )
+
+    duration = time.time() - start_time
+
+    safe_result = SafeCommandResult(
+        command=validated_cmd,
+        returncode=result.returncode,
+        stdout=result.stdout or "",
+        stderr=result.stderr or "",
+        duration_seconds=duration,
+    )
+
+    if check:
+        safe_result.raise_on_error()
+
+    return safe_result
+
+
+def run_poetry_command(
+    args: Sequence[str],
+    *,
+    cwd: Path | str | None = None,
+    timeout: float = 600.0,
+    dry_run: bool = False,
+) -> SafeCommandResult:
+    """Execute a Poetry command safely.
+
+    Args:
+        args: Arguments to pass to poetry.
+        cwd: Working directory.
+        timeout: Maximum execution time.
+        dry_run: Don't actually execute.
+
+    Returns:
+        SafeCommandResult with execution details.
+
+    Example:
+        >>> result = run_poetry_command(["install"])
+        >>> result = run_poetry_command(["add", "pytest", "--group", "dev"])
+
+    """
+    return run_safe_command(
+        ["poetry", *args],
+        cwd=cwd,
+        timeout=timeout,
+        dry_run=dry_run,
+        allowed_commands=["poetry"],
+    )
+
+
+def run_git_command(
+    args: Sequence[str],
+    *,
+    cwd: Path | str | None = None,
+    timeout: float = 60.0,
+    dry_run: bool = False,
+) -> SafeCommandResult:
+    """Execute a Git command safely.
+
+    Args:
+        args: Arguments to pass to git.
+        cwd: Working directory.
+        timeout: Maximum execution time.
+        dry_run: Don't actually execute.
+
+    Returns:
+        SafeCommandResult with execution details.
+
+    Example:
+        >>> result = run_git_command(["init"])
+        >>> result = run_git_command(["status", "--porcelain"])
+
+    """
+    return run_safe_command(
+        ["git", *args],
+        cwd=cwd,
+        timeout=timeout,
+        dry_run=dry_run,
+        allowed_commands=["git"],
+    )
+
+
+def check_command_exists(command: str) -> bool:
+    """Check if a command exists in PATH.
+
+    Args:
+        command: The command to check.
+
+    Returns:
+        True if command exists, False otherwise.
+
+    """
+    return shutil.which(command) is not None
+
+
+def get_command_version(
+    command: str,
+    version_arg: str = "--version",
+) -> str | None:
+    """Get the version of a command.
+
+    Args:
+        command: The command to check.
+        version_arg: Argument to get version (default: --version).
+
+    Returns:
+        Version string or None if command not found.
+
+    """
+    if not check_command_exists(command):
+        return None
+
+    try:
+        result = run_safe_command(
+            [command, version_arg],
+            timeout=10.0,
+            capture_output=True,
+        )
+        if result.success:
+            # Return first non-empty line
+            for raw_line in result.stdout.split("\n"):
+                stripped_line = raw_line.strip()
+                if stripped_line:
+                    return stripped_line
+        return None
+    except (SecurityError, subprocess.SubprocessError):
+        return None