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

unrealon_core/enums/status.py

@@ -0,0 +1,216 @@
+"""
+Status enums for UnrealOn system.
+
+These enums define all possible status values for different
+components in the system. Using enums ensures type safety
+and prevents invalid status values.
+
+Phase 1: Foundation status enums
+"""
+
+from enum import Enum
+
+
+class DriverStatus(str, Enum):
+    """
+    Driver connection and operational status.
+    
+    Used to track the current state of driver connections
+    and their ability to process tasks.
+    """
+    
+    # Connection states
+    DISCONNECTED = "disconnected"    # Driver is not connected
+    CONNECTING = "connecting"        # Driver is attempting to connect
+    CONNECTED = "connected"          # Driver is connected and idle
+    
+    # Operational states  
+    BUSY = "busy"                   # Driver is processing a task
+    READY = "ready"                 # Driver is ready to receive tasks
+    
+    # Error states
+    ERROR = "error"                 # Driver encountered an error
+    TIMEOUT = "timeout"             # Driver connection timed out
+    
+    # Maintenance states
+    MAINTENANCE = "maintenance"     # Driver is in maintenance mode
+    SHUTDOWN = "shutdown"           # Driver is shutting down
+    
+    def is_connected(self) -> bool:
+        """Check if driver is in a connected state."""
+        return self in [
+            DriverStatus.CONNECTED,
+            DriverStatus.BUSY, 
+            DriverStatus.READY
+        ]
+    
+    def is_available(self) -> bool:
+        """Check if driver is available for new tasks."""
+        return self in [
+            DriverStatus.CONNECTED,
+            DriverStatus.READY
+        ]
+    
+    def is_error_state(self) -> bool:
+        """Check if driver is in an error state."""
+        return self in [
+            DriverStatus.ERROR,
+            DriverStatus.TIMEOUT
+        ]
+
+
+class TaskStatus(str, Enum):
+    """
+    Task execution status throughout its lifecycle.
+    
+    Tracks a task from creation through completion,
+    including error and retry states.
+    """
+    
+    # Initial states
+    CREATED = "created"             # Task created but not queued
+    PENDING = "pending"             # Task queued, waiting for assignment
+    ASSIGNED = "assigned"           # Task assigned to a driver
+    
+    # Execution states
+    RUNNING = "running"             # Task is being executed
+    PAUSED = "paused"              # Task execution paused
+    
+    # Completion states
+    COMPLETED = "completed"         # Task completed successfully
+    FAILED = "failed"              # Task failed permanently
+    CANCELLED = "cancelled"        # Task was cancelled
+    
+    # Retry states
+    RETRYING = "retrying"          # Task is being retried
+    RETRY_FAILED = "retry_failed"  # All retries exhausted
+    
+    # Timeout states
+    TIMEOUT = "timeout"            # Task execution timed out
+    
+    def is_active(self) -> bool:
+        """Check if task is actively being processed."""
+        return self in [
+            TaskStatus.ASSIGNED,
+            TaskStatus.RUNNING,
+            TaskStatus.RETRYING
+        ]
+    
+    def is_completed(self) -> bool:
+        """Check if task has reached a final state."""
+        return self in [
+            TaskStatus.COMPLETED,
+            TaskStatus.FAILED,
+            TaskStatus.CANCELLED,
+            TaskStatus.RETRY_FAILED,
+            TaskStatus.TIMEOUT
+        ]
+    
+    def is_successful(self) -> bool:
+        """Check if task completed successfully."""
+        return self == TaskStatus.COMPLETED
+    
+    def can_retry(self) -> bool:
+        """Check if task can be retried."""
+        return self in [
+            TaskStatus.FAILED,
+            TaskStatus.TIMEOUT
+        ]
+
+
+class ProxyStatus(str, Enum):
+    """
+    Proxy server health and availability status.
+    
+    Used to track proxy server health and determine
+    which proxies should be used for requests.
+    """
+    
+    # Operational states
+    ACTIVE = "active"              # Proxy is healthy and available
+    INACTIVE = "inactive"          # Proxy is temporarily unavailable
+    
+    # Health states
+    HEALTHY = "healthy"            # Proxy is responding normally
+    DEGRADED = "degraded"          # Proxy is slow but functional
+    
+    # Error states
+    BANNED = "banned"              # Proxy is banned/blocked
+    TIMEOUT = "timeout"            # Proxy is not responding
+    ERROR = "error"                # Proxy returned errors
+    
+    # Testing states
+    TESTING = "testing"            # Proxy is being health-checked
+    UNKNOWN = "unknown"            # Proxy status is unknown
+    
+    def is_usable(self) -> bool:
+        """Check if proxy can be used for requests."""
+        return self in [
+            ProxyStatus.ACTIVE,
+            ProxyStatus.HEALTHY,
+            ProxyStatus.DEGRADED
+        ]
+    
+    def is_healthy(self) -> bool:
+        """Check if proxy is in good health."""
+        return self in [
+            ProxyStatus.ACTIVE,
+            ProxyStatus.HEALTHY
+        ]
+    
+    def needs_health_check(self) -> bool:
+        """Check if proxy needs a health check."""
+        return self in [
+            ProxyStatus.UNKNOWN,
+            ProxyStatus.TIMEOUT,
+            ProxyStatus.ERROR
+        ]
+
+
+class LogLevel(str, Enum):
+    """
+    Logging levels for the UnrealOn system.
+    
+    Standard logging levels with additional
+    system-specific levels for better categorization.
+    """
+    
+    # Standard levels
+    DEBUG = "debug"                # Detailed debugging information
+    INFO = "info"                  # General information
+    WARNING = "warning"            # Warning messages
+    ERROR = "error"                # Error messages
+    CRITICAL = "critical"          # Critical system errors
+    
+    # System-specific levels
+    TRACE = "trace"                # Very detailed tracing
+    PERFORMANCE = "performance"    # Performance-related logs
+    SECURITY = "security"          # Security-related logs
+    AUDIT = "audit"               # Audit trail logs
+    
+    def get_numeric_level(self) -> int:
+        """Get numeric level for comparison."""
+        levels = {
+            LogLevel.TRACE: 5,
+            LogLevel.DEBUG: 10,
+            LogLevel.INFO: 20,
+            LogLevel.PERFORMANCE: 25,
+            LogLevel.WARNING: 30,
+            LogLevel.ERROR: 40,
+            LogLevel.SECURITY: 45,
+            LogLevel.CRITICAL: 50,
+            LogLevel.AUDIT: 60,
+        }
+        return levels.get(self, 20)
+    
+    def is_at_least(self, other: 'LogLevel') -> bool:
+        """Check if this level is at least as severe as another."""
+        return self.get_numeric_level() >= other.get_numeric_level()
+    
+    @classmethod
+    def from_string(cls, level_str: str) -> 'LogLevel':
+        """Create LogLevel from string, with fallback to INFO."""
+        try:
+            return cls(level_str.lower())
+        except ValueError:
+            return cls.INFO

unrealon_core/enums/types.py

@@ -0,0 +1,240 @@
+"""
+Type enums for UnrealOn system.
+
+These enums define types for messages, proxies, tasks, and other
+system components. They ensure type safety and consistent
+categorization throughout the system.
+
+Phase 1: Foundation type enums
+"""
+
+from enum import Enum
+
+
+class MessageType(str, Enum):
+    """
+    WebSocket message types for driver communication.
+    
+    Defines all possible message types that can be sent
+    between the system and drivers via WebSocket.
+    """
+    
+    # Driver lifecycle messages
+    DRIVER_REGISTER = "driver_register"           # Driver registration request
+    DRIVER_REGISTER_RESPONSE = "driver_register_response"  # Registration response
+    DRIVER_HEARTBEAT = "driver_heartbeat"         # Driver heartbeat/ping
+    DRIVER_STATUS = "driver_status"               # Driver status update
+    DRIVER_DISCONNECT = "driver_disconnect"      # Driver disconnect notification
+    
+    # Task management messages
+    TASK_ASSIGN = "task_assign"                   # Assign task to driver
+    TASK_RESULT = "task_result"                   # Task result from driver
+    TASK_ERROR = "task_error"                     # Task error from driver
+    TASK_PROGRESS = "task_progress"               # Task progress update
+    TASK_CANCEL = "task_cancel"                   # Cancel task request
+    
+    # Command messages
+    COMMAND_START = "command_start"               # Start command
+    COMMAND_STOP = "command_stop"                 # Stop command
+    COMMAND_RESTART = "command_restart"           # Restart command
+    COMMAND_PAUSE = "command_pause"               # Pause command
+    COMMAND_RESUME = "command_resume"             # Resume command
+    COMMAND_CONFIG_UPDATE = "command_config_update"  # Update configuration
+    
+    # Proxy management messages
+    PROXY_REQUEST = "proxy_request"               # Request proxy from pool
+    PROXY_RESPONSE = "proxy_response"             # Proxy response
+    PROXY_HEALTH_REPORT = "proxy_health_report"  # Report proxy health
+    PROXY_ROTATION_REQUEST = "proxy_rotation_request"  # Request proxy rotation
+    PROXY_RELEASE = "proxy_release"              # Release proxy assignment
+    
+    # Logging messages
+    LOG_MESSAGE = "log_message"                   # Log message from driver
+    LOG_BATCH = "log_batch"                       # Batch of log messages
+    
+    # System messages
+    PING = "ping"                                 # Ping message
+    PONG = "pong"                                 # Pong response
+    ERROR = "error"                               # Error message
+    ACK = "ack"                                   # Acknowledgment
+    
+    def is_driver_lifecycle(self) -> bool:
+        """Check if message is related to driver lifecycle."""
+        return self in [
+            MessageType.DRIVER_REGISTER,
+            MessageType.DRIVER_REGISTER_RESPONSE,
+            MessageType.DRIVER_HEARTBEAT,
+            MessageType.DRIVER_STATUS,
+            MessageType.DRIVER_DISCONNECT
+        ]
+    
+    def is_task_related(self) -> bool:
+        """Check if message is related to task management."""
+        return self in [
+            MessageType.TASK_ASSIGN,
+            MessageType.TASK_RESULT,
+            MessageType.TASK_ERROR,
+            MessageType.TASK_PROGRESS,
+            MessageType.TASK_CANCEL
+        ]
+    
+    def is_command(self) -> bool:
+        """Check if message is a command."""
+        return self.value.startswith("command_")
+    
+    def requires_response(self) -> bool:
+        """Check if message type requires a response."""
+        return self in [
+            MessageType.DRIVER_REGISTER,
+            MessageType.PROXY_REQUEST,
+            MessageType.PING
+        ]
+
+
+class ProxyType(str, Enum):
+    """
+    Proxy server types supported by the system.
+    
+    Defines the different types of proxy servers
+    that can be used for web requests.
+    """
+    
+    HTTP = "http"                  # HTTP proxy
+    HTTPS = "https"                # HTTPS proxy
+    SOCKS4 = "socks4"             # SOCKS4 proxy
+    SOCKS5 = "socks5"             # SOCKS5 proxy
+    
+    def supports_https(self) -> bool:
+        """Check if proxy type supports HTTPS."""
+        return self in [ProxyType.HTTPS, ProxyType.SOCKS5]
+    
+    def is_socks(self) -> bool:
+        """Check if proxy is a SOCKS proxy."""
+        return self in [ProxyType.SOCKS4, ProxyType.SOCKS5]
+    
+    def get_default_port(self) -> int:
+        """Get default port for proxy type."""
+        ports = {
+            ProxyType.HTTP: 8080,
+            ProxyType.HTTPS: 8080,
+            ProxyType.SOCKS4: 1080,
+            ProxyType.SOCKS5: 1080,
+        }
+        return ports.get(self, 8080)
+
+
+class TaskPriority(str, Enum):
+    """
+    Task priority levels for queue management.
+    
+    Defines priority levels that determine the order
+    in which tasks are processed by drivers.
+    """
+    
+    LOW = "low"                    # Low priority task
+    NORMAL = "normal"              # Normal priority task (default)
+    HIGH = "high"                  # High priority task
+    URGENT = "urgent"              # Urgent priority task
+    CRITICAL = "critical"          # Critical priority task
+    
+    def get_numeric_priority(self) -> int:
+        """Get numeric priority for sorting (higher = more urgent)."""
+        priorities = {
+            TaskPriority.LOW: 1,
+            TaskPriority.NORMAL: 5,
+            TaskPriority.HIGH: 10,
+            TaskPriority.URGENT: 20,
+            TaskPriority.CRITICAL: 50,
+        }
+        return priorities.get(self, 5)
+    
+    def is_urgent(self) -> bool:
+        """Check if task has urgent or critical priority."""
+        return self in [TaskPriority.URGENT, TaskPriority.CRITICAL]
+    
+    @classmethod
+    def from_numeric(cls, priority: int) -> 'TaskPriority':
+        """Create TaskPriority from numeric value."""
+        if priority >= 50:
+            return cls.CRITICAL
+        elif priority >= 20:
+            return cls.URGENT
+        elif priority >= 10:
+            return cls.HIGH
+        elif priority >= 5:
+            return cls.NORMAL
+        else:
+            return cls.LOW
+
+
+class DriverType(str, Enum):
+    """
+    Driver types for categorization and capability matching.
+    
+    Defines different types of drivers based on their
+    primary functionality and target websites.
+    """
+    
+    # General purpose
+    UNIVERSAL = "universal"        # Universal driver for any site
+    GENERIC = "generic"           # Generic web scraping driver
+    
+    # E-commerce specific
+    ECOMMERCE = "ecommerce"       # E-commerce sites
+    MARKETPLACE = "marketplace"    # Online marketplaces
+    PRODUCT_CATALOG = "product_catalog"  # Product catalogs
+    
+    # Content specific
+    NEWS = "news"                 # News websites
+    BLOG = "blog"                 # Blog sites
+    SOCIAL_MEDIA = "social_media" # Social media platforms
+    
+    # Data specific
+    API = "api"                   # API-based data collection
+    DATABASE = "database"         # Database extraction
+    FILE = "file"                 # File processing
+    
+    def is_web_scraping(self) -> bool:
+        """Check if driver type involves web scraping."""
+        return self in [
+            DriverType.UNIVERSAL,
+            DriverType.GENERIC,
+            DriverType.ECOMMERCE,
+            DriverType.MARKETPLACE,
+            DriverType.PRODUCT_CATALOG,
+            DriverType.NEWS,
+            DriverType.BLOG,
+            DriverType.SOCIAL_MEDIA
+        ]
+    
+    def requires_browser(self) -> bool:
+        """Check if driver type typically requires a browser."""
+        return self in [
+            DriverType.ECOMMERCE,
+            DriverType.MARKETPLACE,
+            DriverType.SOCIAL_MEDIA
+        ]
+
+
+class ConfigType(str, Enum):
+    """
+    Configuration types for different system components.
+    
+    Used to categorize and validate different types
+    of configuration objects in the system.
+    """
+    
+    SYSTEM = "system"             # System-wide configuration
+    DRIVER = "driver"             # Driver-specific configuration
+    HTTP = "http"                 # HTTP client configuration
+    PROXY = "proxy"               # Proxy management configuration
+    BROWSER = "browser"           # Browser automation configuration
+    LOGGING = "logging"           # Logging configuration
+    CACHE = "cache"               # Cache configuration
+    THREAD = "thread"             # Threading configuration
+    DATABASE = "database"         # Database configuration
+    SECURITY = "security"         # Security configuration
+    
+    def get_config_schema(self) -> str:
+        """Get the schema identifier for this config type."""
+        return f"unrealon.config.{self.value}"

unrealon_core/error_handling/__init__.py

@@ -0,0 +1,45 @@
+"""
+Error Handling Package
+
+Comprehensive error handling and retry logic for UnrealOn RPC system.
+Following critical requirements - max 500 lines, 100% Pydantic v2.
+
+Phase 2: Core Systems - Error Handling
+"""
+
+from .retry import (
+    RetryConfig, RetryStrategy, RetryResult,
+    ExponentialBackoff, LinearBackoff, FixedBackoff,
+    retry_async, retry_sync
+)
+from .circuit_breaker import (
+    CircuitBreakerConfig, CircuitBreakerState,
+    CircuitBreaker, circuit_breaker, get_circuit_breaker
+)
+from .error_context import (
+    ErrorContext, ErrorSeverity,
+    create_error_context, format_error_context
+)
+from .recovery import (
+    RecoveryStrategy, RecoveryAction,
+    AutoRecovery, recovery_handler
+)
+
+__all__ = [
+    # Retry system
+    'RetryConfig', 'RetryStrategy', 'RetryResult',
+    'ExponentialBackoff', 'LinearBackoff', 'FixedBackoff',
+    'retry_async', 'retry_sync',
+    
+    # Circuit breaker
+    'CircuitBreakerConfig', 'CircuitBreakerState',
+    'CircuitBreaker', 'circuit_breaker', 'get_circuit_breaker',
+    
+    # Error context
+    'ErrorContext', 'ErrorSeverity',
+    'create_error_context', 'format_error_context',
+    
+    # Recovery system
+    'RecoveryStrategy', 'RecoveryAction',
+    'AutoRecovery', 'recovery_handler',
+]