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

unrealon_core/__init__.py

@@ -0,0 +1,160 @@
+"""
+UnrealOn Core Package
+
+Core models, enums, and exceptions for the UnrealOn RPC system.
+This package provides the foundational data structures and utilities
+used across all UnrealOn components.
+
+Phase 1: Bedrock Foundation
+- Base Pydantic models with strict validation
+- Core enums and constants
+- Custom exceptions hierarchy
+- 100% test coverage required
+"""
+
+# Import unified version system
+from unrealon_core.version import get_rpc_version, get_version_info
+
+__version__ = get_rpc_version()
+__author__ = "UnrealOn Team"
+
+# Import main components for easy access
+from .models.base import UnrealOnBaseModel, TimestampedModel, IdentifiedModel, StatusModel
+from .models.arq_context import (
+    ARQWorkerContext, ARQWorkerStats, TaskAssignmentParams, TaskResultParams,
+    LogEntryParams, DriverRegistrationParams, HeartbeatParams
+)
+from .models.arq_responses import (
+    TaskAssignmentResponse, TaskResultResponse, LogEntryResponse,
+    DriverRegistrationResponse, HeartbeatResponse, PingResponse
+)
+from .models.typed_responses import (
+    HealthCheckResult, StatusInfo, SessionInfo, ProxyStats,
+    ThreadStats, CacheStats, BatchStats
+)
+from .models.communication import (
+    MessageType as WebSocketMessageType, WebSocketMessage, 
+    DriverRegistrationMessage, RegistrationResponseMessage,
+    TaskAssignmentMessage, TaskResultMessage,
+    LogEntryMessage, LogBatchMessage,
+    HeartbeatMessage, ConfigurationUpdateMessage,
+    ErrorMessage, AckMessage,
+    create_error_message, create_ack_message,
+    # Data models for strict typing
+    TaskAssignmentData, TaskResultData,
+    DriverRegistrationData, HeartbeatData, LogEntryData, LogContext
+)
+from .enums.status import DriverStatus, TaskStatus, ProxyStatus, LogLevel
+from .enums.types import MessageType, ProxyType, TaskPriority
+from .exceptions.base import UnrealOnError
+from .exceptions.validation import ValidationError as UnrealOnValidationError
+from .exceptions.communication import CommunicationError
+
+# Error handling system
+from .error_handling import (
+    RetryConfig, RetryStrategy, RetryResult,
+    ExponentialBackoff, LinearBackoff, FixedBackoff,
+    retry_async, retry_sync,
+    CircuitBreakerConfig, CircuitBreakerState,
+    CircuitBreaker, circuit_breaker,
+    ErrorContext, ErrorSeverity,
+    create_error_context, format_error_context,
+    RecoveryStrategy, RecoveryAction,
+    AutoRecovery, recovery_handler
+)
+
+# Monitoring system
+from .monitoring import (
+    HealthStatus, HealthCheckResult, ComponentHealth,
+    HealthChecker, health_check_decorator,
+    MetricType, MetricValue, Metric,
+    MetricsCollector, counter, gauge, histogram, timer,
+    AlertSeverity, AlertRule, Alert,
+    AlertManager, alert_on_condition,
+    DashboardData, SystemStatus,
+    MonitoringDashboard, get_system_overview
+)
+
+# Configuration system
+from .config import (
+    EnvironmentConfig, URLConfig,
+    get_environment_config, get_url_config
+)
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__", 
+    "__phase__",
+    
+    # Base models
+    "UnrealOnBaseModel",
+    "TimestampedModel", 
+    "IdentifiedModel",
+    "StatusModel",
+    
+    # WebSocket Communication models
+    "WebSocketMessageType",
+    "WebSocketMessage",
+    "DriverRegistrationMessage",
+    "RegistrationResponseMessage", 
+    "TaskAssignmentMessage",
+    "TaskResultMessage",
+    "LogEntryMessage",
+    "LogBatchMessage",
+    "HeartbeatMessage",
+    "ConfigurationUpdateMessage",
+    "ErrorMessage",
+    "AckMessage",
+    "create_error_message",
+    "create_ack_message",
+    
+    # Data models for strict typing
+    "TaskAssignmentData",
+    "TaskResultData", 
+    "DriverRegistrationData",
+    "HeartbeatData",
+    "LogEntryData",
+    "LogContext",
+    
+    # Status enums
+    "DriverStatus",
+    "TaskStatus",
+    "ProxyStatus", 
+    "LogLevel",
+    
+    # Type enums
+    "MessageType",
+    "ProxyType",
+    "TaskPriority",
+    
+    # Exceptions
+    "UnrealOnError",
+    "UnrealOnValidationError",
+    "CommunicationError",
+    
+    # Error handling system
+    "RetryConfig", "RetryStrategy", "RetryResult",
+    "ExponentialBackoff", "LinearBackoff", "FixedBackoff",
+    "retry_async", "retry_sync",
+    "CircuitBreakerConfig", "CircuitBreakerState",
+    "CircuitBreaker", "circuit_breaker",
+    "ErrorContext", "ErrorSeverity",
+    "create_error_context", "format_error_context",
+    "RecoveryStrategy", "RecoveryAction",
+    "AutoRecovery", "recovery_handler",
+    
+    # Monitoring system
+    "HealthStatus", "HealthCheckResult", "ComponentHealth",
+    "HealthChecker", "health_check_decorator",
+    "MetricType", "MetricValue", "Metric",
+    "MetricsCollector", "counter", "gauge", "histogram", "timer",
+    "AlertSeverity", "AlertRule", "Alert",
+    "AlertManager", "alert_on_condition",
+    "DashboardData", "SystemStatus",
+    "MonitoringDashboard", "get_system_overview",
+    
+    # Configuration system
+    "EnvironmentConfig", "URLConfig",
+    "get_environment_config", "get_url_config",
+]

unrealon_core/config/__init__.py

@@ -0,0 +1,16 @@
+"""
+Configuration management for UnrealOn platform.
+
+This module provides centralized configuration management with support for
+development and production environments.
+"""
+
+from .environment import EnvironmentConfig, get_environment_config
+from .urls import URLConfig, get_url_config
+
+__all__ = [
+    "EnvironmentConfig",
+    "URLConfig", 
+    "get_environment_config",
+    "get_url_config",
+]

unrealon_core/config/environment.py

@@ -0,0 +1,98 @@
+"""
+Environment configuration management.
+
+Handles switching between development and production environments.
+"""
+
+import os
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class Environment(str, Enum):
+    """Environment types."""
+    DEVELOPMENT = "development"
+    PRODUCTION = "production"
+    TESTING = "testing"
+
+
+class EnvironmentConfig(BaseModel):
+    """Environment configuration settings."""
+    
+    model_config = ConfigDict(
+        # Add any specific config here if needed
+    )
+    
+    environment: Environment = Field(
+        default=Environment.DEVELOPMENT,
+        description="Current environment"
+    )
+    
+    debug: bool = Field(
+        default=True,
+        description="Enable debug mode"
+    )
+    
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level"
+    )
+    
+    @classmethod
+    def from_env(cls) -> "EnvironmentConfig":
+        """Create config from environment variables."""
+        env_name = os.getenv("UNREALON_ENV", "development").lower()
+        
+        # Map environment names
+        env_mapping = {
+            "dev": Environment.DEVELOPMENT,
+            "development": Environment.DEVELOPMENT,
+            "prod": Environment.PRODUCTION,
+            "production": Environment.PRODUCTION,
+            "test": Environment.TESTING,
+            "testing": Environment.TESTING,
+        }
+        
+        environment = env_mapping.get(env_name, Environment.DEVELOPMENT)
+        
+        return cls(
+            environment=environment,
+            debug=environment != Environment.PRODUCTION,
+            log_level=os.getenv("UNREALON_LOG_LEVEL", "DEBUG" if environment != Environment.PRODUCTION else "INFO")
+        )
+    
+    @property
+    def is_development(self) -> bool:
+        """Check if running in development mode."""
+        return self.environment == Environment.DEVELOPMENT
+    
+    @property
+    def is_production(self) -> bool:
+        """Check if running in production mode."""
+        return self.environment == Environment.PRODUCTION
+    
+    @property
+    def is_testing(self) -> bool:
+        """Check if running in testing mode."""
+        return self.environment == Environment.TESTING
+
+
+# Global config instance
+_environment_config: Optional[EnvironmentConfig] = None
+
+
+def get_environment_config() -> EnvironmentConfig:
+    """Get the global environment configuration."""
+    global _environment_config
+    
+    if _environment_config is None:
+        _environment_config = EnvironmentConfig.from_env()
+    
+    return _environment_config
+
+
+def set_environment_config(config: EnvironmentConfig) -> None:
+    """Set the global environment configuration."""
+    global _environment_config
+    _environment_config = config

unrealon_core/config/urls.py

@@ -0,0 +1,93 @@
+"""
+URL configuration management.
+
+Provides centralized URL management with environment-specific endpoints.
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field, HttpUrl, ConfigDict
+from .environment import get_environment_config, Environment
+
+
+class URLConfig(BaseModel):
+    """URL configuration for different services."""
+    
+    model_config = ConfigDict(
+        # Add any specific config here if needed
+    )
+    
+    # Scanner/Detection URLs
+    scanner_url: str = Field(
+        description="URL for browser detection and stealth testing"
+    )
+    
+    # Cloud platform URLs  
+    cloud_base_url: str = Field(
+        description="Base URL for UnrealOn Cloud platform"
+    )
+    
+    # API endpoints
+    api_base_url: str = Field(
+        description="Base URL for API endpoints"
+    )
+    
+    @classmethod
+    def for_environment(cls, environment: Optional[Environment] = None) -> "URLConfig":
+        """Create URL config for specific environment."""
+        if environment is None:
+            environment = get_environment_config().environment
+        
+        if environment == Environment.PRODUCTION:
+            return cls(
+                scanner_url="https://cloud.unrealon.com/scanner",
+                cloud_base_url="https://cloud.unrealon.com",
+                api_base_url="https://api.unrealon.com"
+            )
+        elif environment == Environment.TESTING:
+            return cls(
+                scanner_url="https://staging.unrealon.com/scanner", 
+                cloud_base_url="https://staging.unrealon.com",
+                api_base_url="https://api-staging.unrealon.com"
+            )
+        else:  # Development
+            return cls(
+                scanner_url="http://localhost:3000/scanner",
+                cloud_base_url="http://localhost:3000", 
+                api_base_url="http://localhost:8000"
+            )
+    
+    @property
+    def stealth_test_url(self) -> str:
+        """Get the URL for stealth testing (replaces bot.sannysoft.com)."""
+        return self.scanner_url
+    
+    @property
+    def detection_test_url(self) -> str:
+        """Get the URL for browser detection testing."""
+        return self.scanner_url
+
+
+# Global config instance
+_url_config: Optional[URLConfig] = None
+
+
+def get_url_config() -> URLConfig:
+    """Get the global URL configuration."""
+    global _url_config
+    
+    if _url_config is None:
+        _url_config = URLConfig.for_environment()
+    
+    return _url_config
+
+
+def set_url_config(config: URLConfig) -> None:
+    """Set the global URL configuration."""
+    global _url_config
+    _url_config = config
+
+
+def reset_url_config() -> None:
+    """Reset URL config to reload from environment."""
+    global _url_config
+    _url_config = None

unrealon_core/enums/__init__.py

@@ -0,0 +1,24 @@
+"""
+UnrealOn Core Enums
+
+All enums and constants used across the UnrealOn system.
+These provide type safety and consistent values throughout the codebase.
+
+Phase 1: Foundation enums with strict validation
+"""
+
+from .status import DriverStatus, TaskStatus, ProxyStatus, LogLevel
+from .types import MessageType, ProxyType, TaskPriority
+
+__all__ = [
+    # Status enums
+    "DriverStatus",
+    "TaskStatus", 
+    "ProxyStatus",
+    "LogLevel",
+    
+    # Type enums
+    "MessageType",
+    "ProxyType",
+    "TaskPriority",
+]

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