unrealon 1.1.6__py3-none-any.whl → 2.0.4__py3-none-any.whl

unrealon_core/error_handling/retry.py

@@ -0,0 +1,268 @@
+"""
+Retry System
+
+Advanced retry logic with multiple backoff strategies.
+Following critical requirements - max 500 lines, functions < 20 lines.
+
+Phase 2: Core Systems - Error Handling
+"""
+
+import asyncio
+import logging
+import random
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from typing import Any, Callable, Optional, Type, Union, List
+from enum import Enum
+
+from pydantic import BaseModel, Field, ConfigDict
+
+from ..exceptions.base import UnrealOnError
+from ..utils.time import utc_now
+
+
+logger = logging.getLogger(__name__)
+
+
+class RetryStrategy(str, Enum):
+    """Retry strategy types."""
+    EXPONENTIAL = "exponential"
+    LINEAR = "linear"
+    FIXED = "fixed"
+
+
+class RetryResult(BaseModel):
+    """Result of retry operation."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    success: bool = Field(description="Whether operation succeeded")
+    attempts: int = Field(description="Number of attempts made")
+    total_duration: float = Field(description="Total duration in seconds")
+    last_error: Optional[str] = Field(default=None, description="Last error message")
+    result: Optional[Any] = Field(default=None, description="Operation result if successful")
+
+
+class RetryConfig(BaseModel):
+    """Configuration for retry behavior."""
+    
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="forbid"
+    )
+    
+    max_attempts: int = Field(default=3, ge=1, le=10, description="Maximum retry attempts")
+    strategy: RetryStrategy = Field(default=RetryStrategy.EXPONENTIAL, description="Backoff strategy")
+    base_delay: float = Field(default=1.0, ge=0.1, le=60.0, description="Base delay in seconds")
+    max_delay: float = Field(default=60.0, ge=1.0, le=300.0, description="Maximum delay in seconds")
+    jitter: bool = Field(default=True, description="Add random jitter to delays")
+    retryable_exceptions: List[str] = Field(
+        default_factory=lambda: ["ConnectionError", "TimeoutError", "HTTPError"],
+        description="Exception types that should trigger retry"
+    )
+
+
+class BackoffCalculator(ABC):
+    """Abstract base for backoff calculation strategies."""
+    
+    def __init__(self, config: RetryConfig):
+        self.config = config
+    
+    @abstractmethod
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for given attempt number."""
+        pass
+    
+    def add_jitter(self, delay: float) -> float:
+        """Add random jitter to delay."""
+        if not self.config.jitter:
+            return delay
+        
+        # Add ±25% jitter
+        jitter_range = delay * 0.25
+        jitter = random.uniform(-jitter_range, jitter_range)
+        return max(0.1, delay + jitter)
+
+
+class ExponentialBackoff(BackoffCalculator):
+    """Exponential backoff strategy."""
+    
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate exponential backoff delay."""
+        delay = self.config.base_delay * (2 ** (attempt - 1))
+        delay = min(delay, self.config.max_delay)
+        return self.add_jitter(delay)
+
+
+class LinearBackoff(BackoffCalculator):
+    """Linear backoff strategy."""
+    
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate linear backoff delay."""
+        delay = self.config.base_delay * attempt
+        delay = min(delay, self.config.max_delay)
+        return self.add_jitter(delay)
+
+
+class FixedBackoff(BackoffCalculator):
+    """Fixed delay backoff strategy."""
+    
+    def calculate_delay(self, attempt: int) -> float:
+        """Calculate fixed backoff delay."""
+        return self.add_jitter(self.config.base_delay)
+
+
+def create_backoff_calculator(config: RetryConfig) -> BackoffCalculator:
+    """Factory function to create backoff calculator."""
+    if config.strategy == RetryStrategy.EXPONENTIAL:
+        return ExponentialBackoff(config)
+    elif config.strategy == RetryStrategy.LINEAR:
+        return LinearBackoff(config)
+    else:
+        return FixedBackoff(config)
+
+
+def is_retryable_exception(
+    exception: Exception, 
+    retryable_types: List[str]
+) -> bool:
+    """Check if exception is retryable."""
+    exception_name = exception.__class__.__name__
+    return exception_name in retryable_types
+
+
+async def retry_async(
+    func: Callable[..., Any],
+    config: RetryConfig,
+    *args,
+    **kwargs
+) -> RetryResult:
+    """
+    Execute async function with retry logic.
+    
+    Args:
+        func: Async function to execute
+        config: Retry configuration
+        *args, **kwargs: Function arguments
+        
+    Returns:
+        RetryResult with operation outcome
+    """
+    start_time = utc_now()
+    backoff = create_backoff_calculator(config)
+    last_error = None
+    
+    for attempt in range(1, config.max_attempts + 1):
+        try:
+            logger.debug(f"Attempt {attempt}/{config.max_attempts} for {func.__name__}")
+            
+            result = await func(*args, **kwargs)
+            
+            duration = (utc_now() - start_time).total_seconds()
+            
+            if attempt > 1:
+                logger.info(f"{func.__name__} succeeded on attempt {attempt}")
+            
+            return RetryResult(
+                success=True,
+                attempts=attempt,
+                total_duration=duration,
+                result=result
+            )
+            
+        except Exception as e:
+            last_error = str(e)
+            
+            if not is_retryable_exception(e, config.retryable_exceptions):
+                logger.error(f"{func.__name__} failed with non-retryable error: {e}")
+                break
+            
+            if attempt < config.max_attempts:
+                delay = backoff.calculate_delay(attempt)
+                logger.warning(
+                    f"{func.__name__} attempt {attempt} failed: {e}. "
+                    f"Retrying in {delay:.2f}s..."
+                )
+                await asyncio.sleep(delay)
+            else:
+                logger.error(f"{func.__name__} failed after {attempt} attempts: {e}")
+    
+    duration = (utc_now() - start_time).total_seconds()
+    
+    return RetryResult(
+        success=False,
+        attempts=config.max_attempts,
+        total_duration=duration,
+        last_error=last_error
+    )
+
+
+def retry_sync(
+    func: Callable[..., Any],
+    config: RetryConfig,
+    *args,
+    **kwargs
+) -> RetryResult:
+    """
+    Execute sync function with retry logic.
+    
+    Args:
+        func: Sync function to execute
+        config: Retry configuration
+        *args, **kwargs: Function arguments
+        
+    Returns:
+        RetryResult with operation outcome
+    """
+    import time
+    
+    start_time = utc_now()
+    backoff = create_backoff_calculator(config)
+    last_error = None
+    
+    for attempt in range(1, config.max_attempts + 1):
+        try:
+            logger.debug(f"Attempt {attempt}/{config.max_attempts} for {func.__name__}")
+            
+            result = func(*args, **kwargs)
+            
+            duration = (utc_now() - start_time).total_seconds()
+            
+            if attempt > 1:
+                logger.info(f"{func.__name__} succeeded on attempt {attempt}")
+            
+            return RetryResult(
+                success=True,
+                attempts=attempt,
+                total_duration=duration,
+                result=result
+            )
+            
+        except Exception as e:
+            last_error = str(e)
+            
+            if not is_retryable_exception(e, config.retryable_exceptions):
+                logger.error(f"{func.__name__} failed with non-retryable error: {e}")
+                break
+            
+            if attempt < config.max_attempts:
+                delay = backoff.calculate_delay(attempt)
+                logger.warning(
+                    f"{func.__name__} attempt {attempt} failed: {e}. "
+                    f"Retrying in {delay:.2f}s..."
+                )
+                time.sleep(delay)
+            else:
+                logger.error(f"{func.__name__} failed after {attempt} attempts: {e}")
+    
+    duration = (utc_now() - start_time).total_seconds()
+    
+    return RetryResult(
+        success=False,
+        attempts=config.max_attempts,
+        total_duration=duration,
+        last_error=last_error
+    )

unrealon_core/exceptions/__init__.py

@@ -0,0 +1,46 @@
+"""
+UnrealOn Core Exceptions
+
+Custom exception hierarchy for the UnrealOn system.
+Provides specific exceptions for different error conditions
+with proper error codes and context information.
+
+Phase 1: Foundation exceptions with proper hierarchy
+"""
+
+from .base import UnrealOnError, UnrealOnWarning
+from .validation import ValidationError, ConfigurationError
+from .communication import CommunicationError, WebSocketError, RPCError
+from .driver import DriverError, DriverNotFoundError, DriverTimeoutError
+from .task import TaskError, TaskTimeoutError, TaskValidationError
+from .proxy import ProxyError, ProxyNotAvailableError, ProxyTimeoutError
+
+__all__ = [
+    # Base exceptions
+    "UnrealOnError",
+    "UnrealOnWarning",
+    
+    # Validation exceptions
+    "ValidationError",
+    "ConfigurationError",
+    
+    # Communication exceptions
+    "CommunicationError",
+    "WebSocketError", 
+    "RPCError",
+    
+    # Driver exceptions
+    "DriverError",
+    "DriverNotFoundError",
+    "DriverTimeoutError",
+    
+    # Task exceptions
+    "TaskError",
+    "TaskTimeoutError",
+    "TaskValidationError",
+    
+    # Proxy exceptions
+    "ProxyError",
+    "ProxyNotAvailableError",
+    "ProxyTimeoutError",
+]

unrealon_core/exceptions/base.py

@@ -0,0 +1,292 @@
+"""
+Base exceptions for UnrealOn system.
+
+Provides the foundation exception classes that all other
+UnrealOn exceptions inherit from. Includes error codes,
+context information, and structured error handling.
+
+Phase 1: Foundation exception hierarchy
+"""
+
+from typing import Optional, Dict, Any, Union
+from unrealon_core.utils.time import utc_now
+
+class UnrealOnError(Exception):
+    """
+    Base exception for all UnrealOn errors.
+    
+    Provides:
+    - Error codes for programmatic handling
+    - Context information for debugging
+    - Structured error data
+    - Timestamp tracking
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        error_code: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+        cause: Optional[Exception] = None
+    ):
+        """
+        Initialize UnrealOn error.
+        
+        Args:
+            message: Human-readable error message
+            error_code: Machine-readable error code
+            context: Additional context information
+            cause: Original exception that caused this error
+        """
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code or self._get_default_error_code()
+        self.context = context or {}
+        self.cause = cause
+        self.timestamp = utc_now()
+        
+        # Set the cause for proper exception chaining
+        if cause:
+            self.__cause__ = cause
+    
+    def _get_default_error_code(self) -> str:
+        """Get default error code based on exception class name."""
+        class_name = self.__class__.__name__
+        # Convert CamelCase to UPPER_SNAKE_CASE
+        import re
+        error_code = re.sub('([a-z0-9])([A-Z])', r'\1_\2', class_name).upper()
+        return error_code
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert exception to dictionary for serialization."""
+        return {
+            'error_type': self.__class__.__name__,
+            'error_code': self.error_code,
+            'message': self.message,
+            'context': self.context,
+            'timestamp': self.timestamp.isoformat(),
+            'cause': str(self.cause) if self.cause else None
+        }
+    
+    def add_context(self, key: str, value: Any) -> 'UnrealOnError':
+        """Add context information to the error."""
+        self.context[key] = value
+        return self
+    
+    def with_context(self, **context) -> 'UnrealOnError':
+        """Add multiple context items to the error."""
+        self.context.update(context)
+        return self
+    
+    def __str__(self) -> str:
+        """String representation of the error."""
+        parts = [f"[{self.error_code}] {self.message}"]
+        
+        if self.context:
+            context_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            parts.append(f"Context: {context_str}")
+        
+        if self.cause:
+            parts.append(f"Caused by: {self.cause}")
+        
+        return " | ".join(parts)
+    
+    def __repr__(self) -> str:
+        """Detailed representation of the error."""
+        return (
+            f"{self.__class__.__name__}("
+            f"message='{self.message}', "
+            f"error_code='{self.error_code}', "
+            f"context={self.context}, "
+            f"cause={self.cause!r})"
+        )
+
+
+class UnrealOnWarning(UserWarning):
+    """
+    Base warning for UnrealOn system.
+    
+    Used for non-fatal issues that should be logged
+    but don't prevent operation from continuing.
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        warning_code: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize UnrealOn warning.
+        
+        Args:
+            message: Human-readable warning message
+            warning_code: Machine-readable warning code
+            context: Additional context information
+        """
+        super().__init__(message)
+        self.message = message
+        self.warning_code = warning_code or self._get_default_warning_code()
+        self.context = context or {}
+        self.timestamp = utc_now()
+    
+    def _get_default_warning_code(self) -> str:
+        """Get default warning code based on class name."""
+        class_name = self.__class__.__name__
+        import re
+        warning_code = re.sub('([a-z0-9])([A-Z])', r'\1_\2', class_name).upper()
+        return warning_code
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert warning to dictionary for serialization."""
+        return {
+            'warning_type': self.__class__.__name__,
+            'warning_code': self.warning_code,
+            'message': self.message,
+            'context': self.context,
+            'timestamp': self.timestamp.isoformat()
+        }
+
+
+class UnrealOnTimeoutError(UnrealOnError):
+    """
+    Base timeout error for operations that exceed time limits.
+    
+    Used when operations take longer than expected or configured
+    timeout values are exceeded.
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        timeout_seconds: Optional[float] = None,
+        operation: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize timeout error.
+        
+        Args:
+            message: Error message
+            timeout_seconds: The timeout value that was exceeded
+            operation: Name of the operation that timed out
+            **kwargs: Additional arguments for base class
+        """
+        super().__init__(message, **kwargs)
+        
+        if timeout_seconds is not None:
+            self.add_context('timeout_seconds', timeout_seconds)
+        
+        if operation:
+            self.add_context('operation', operation)
+
+
+class UnrealOnConfigurationError(UnrealOnError):
+    """
+    Configuration-related errors.
+    
+    Used when there are issues with system configuration,
+    invalid settings, or missing required configuration.
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        config_key: Optional[str] = None,
+        config_value: Optional[Any] = None,
+        **kwargs
+    ):
+        """
+        Initialize configuration error.
+        
+        Args:
+            message: Error message
+            config_key: The configuration key that caused the error
+            config_value: The invalid configuration value
+            **kwargs: Additional arguments for base class
+        """
+        super().__init__(message, **kwargs)
+        
+        if config_key:
+            self.add_context('config_key', config_key)
+        
+        if config_value is not None:
+            self.add_context('config_value', str(config_value))
+
+
+class UnrealOnRetryableError(UnrealOnError):
+    """
+    Base class for errors that can be retried.
+    
+    Used for temporary failures that might succeed
+    if the operation is attempted again.
+    """
+    
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        **kwargs
+    ):
+        """
+        Initialize retryable error.
+        
+        Args:
+            message: Error message
+            retry_after: Suggested delay before retry (seconds)
+            max_retries: Maximum number of retries recommended
+            **kwargs: Additional arguments for base class
+        """
+        super().__init__(message, **kwargs)
+        
+        if retry_after is not None:
+            self.add_context('retry_after', retry_after)
+        
+        if max_retries is not None:
+            self.add_context('max_retries', max_retries)
+    
+    def should_retry(self, attempt_count: int) -> bool:
+        """
+        Check if the operation should be retried.
+        
+        Args:
+            attempt_count: Number of attempts already made
+            
+        Returns:
+            True if retry should be attempted
+        """
+        max_retries = self.context.get('max_retries')
+        if max_retries is None:
+            return True  # No limit specified
+        
+        return attempt_count < max_retries
+    
+    def get_retry_delay(self, attempt_count: int) -> float:
+        """
+        Get suggested delay before retry.
+        
+        Args:
+            attempt_count: Number of attempts already made
+            
+        Returns:
+            Delay in seconds
+        """
+        base_delay = self.context.get('retry_after', 1.0)
+        
+        # Exponential backoff: delay = base_delay * (2 ^ attempt_count)
+        return base_delay * (2 ** min(attempt_count, 6))  # Cap at 2^6 = 64x
+
+
+class UnrealOnFatalError(UnrealOnError):
+    """
+    Fatal errors that should stop system operation.
+    
+    Used for critical errors that indicate the system
+    cannot continue operating safely.
+    """
+    
+    def __init__(self, message: str, **kwargs):
+        """Initialize fatal error."""
+        super().__init__(message, **kwargs)
+        self.add_context('fatal', True)

unrealon_core/exceptions/communication.py

@@ -0,0 +1,22 @@
+"""
+Communication exceptions for UnrealOn system.
+
+Phase 1: Basic communication exceptions
+"""
+
+from .base import UnrealOnError, UnrealOnTimeoutError
+
+
+class CommunicationError(UnrealOnError):
+    """Base communication error."""
+    pass
+
+
+class WebSocketError(CommunicationError):
+    """WebSocket communication error."""
+    pass
+
+
+class RPCError(CommunicationError):
+    """RPC communication error."""
+    pass

unrealon_core/exceptions/driver.py

@@ -0,0 +1,11 @@
+"""Driver exceptions - Phase 1 stubs."""
+from .base import UnrealOnError, UnrealOnTimeoutError
+
+class DriverError(UnrealOnError):
+    pass
+
+class DriverNotFoundError(DriverError):
+    pass
+
+class DriverTimeoutError(UnrealOnTimeoutError):
+    pass

unrealon_core/exceptions/proxy.py

@@ -0,0 +1,11 @@
+"""Proxy exceptions - Phase 1 stubs."""
+from .base import UnrealOnError, UnrealOnTimeoutError
+
+class ProxyError(UnrealOnError):
+    pass
+
+class ProxyNotAvailableError(ProxyError):
+    pass
+
+class ProxyTimeoutError(UnrealOnTimeoutError):
+    pass

unrealon_core/exceptions/task.py

@@ -0,0 +1,12 @@
+"""Task exceptions - Phase 1 stubs."""
+from .base import UnrealOnError, UnrealOnTimeoutError
+from .validation import ValidationError
+
+class TaskError(UnrealOnError):
+    pass
+
+class TaskTimeoutError(UnrealOnTimeoutError):
+    pass
+
+class TaskValidationError(ValidationError):
+    pass

unrealon_core/exceptions/validation.py

@@ -0,0 +1,17 @@
+"""
+Validation exceptions for UnrealOn system.
+
+Phase 1: Basic validation exceptions
+"""
+
+from .base import UnrealOnError, UnrealOnConfigurationError
+
+
+class ValidationError(UnrealOnError):
+    """Validation error for invalid data."""
+    pass
+
+
+class ConfigurationError(UnrealOnConfigurationError):
+    """Configuration validation error."""
+    pass