ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/adapters/discord/discord_error_classifier.py

@@ -0,0 +1,302 @@
+"""
+Discord error classification and retry logic.
+
+Centralizes all discord.py specific error handling patterns.
+"""
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, Set
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorCategory(str, Enum):
+    """Categories of Discord errors."""
+
+    NETWORK = "network"
+    RATE_LIMIT = "rate_limit"
+    AUTHENTICATION = "authentication"
+    PERMISSION = "permission"
+    WEBSOCKET = "websocket"
+    SERVER = "server"
+    SSL_TLS = "ssl_tls"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ErrorClassification:
+    """Result of error classification."""
+
+    category: ErrorCategory
+    is_transient: bool
+    should_retry: bool
+    retry_delay: float
+    max_retries: int
+    description: str
+
+
+class DiscordErrorClassifier:
+    """
+    Classifies Discord errors and determines retry strategies.
+
+    Replaces hardcoded error string matching with structured classification.
+    """
+
+    # Network and connection errors - always retry
+    NETWORK_ERRORS: Set[str] = {
+        "Connection reset by peer",
+        "Connection refused",
+        "Network is unreachable",
+        "Temporary failure in name resolution",
+        "Connection timed out",
+        "Remote end closed connection",
+        "ECONNRESET",
+        "EPIPE",
+        "ETIMEDOUT",  # Socket timeout errors
+        "getaddrinfo failed",  # DNS lookup failures
+        "Name or service not known",  # DNS resolution errors
+    }
+
+    # WebSocket specific errors - always retry
+    WEBSOCKET_ERRORS: Set[str] = {
+        "Concurrent call to receive() is not allowed",
+        "WebSocket connection is closed.",
+        "Shard ID None has stopped responding to the gateway.",
+        "Session is closed",
+        "Cannot write to closing transport",
+    }
+
+    # HTTP server errors - retry with backoff
+    SERVER_ERRORS: Set[str] = {
+        "HTTP 502",
+        "HTTP 503",
+        "HTTP 504",
+        "CloudFlare",
+        "Cloudflare",
+    }
+
+    # Rate limiting - retry with longer delay
+    RATE_LIMIT_ERRORS: Set[str] = {
+        "rate limit",
+        "Rate limit",
+        "429",
+    }
+
+    # SSL/TLS errors - retry with caution
+    SSL_TLS_ERRORS: Set[str] = {
+        "SSL",
+        "TLS",
+        "certificate",
+    }
+
+    # Authentication errors - don't retry
+    AUTH_ERRORS: Set[str] = {
+        "401",
+        "403",
+        "Unauthorized",
+        "Forbidden",
+        "Invalid token",
+    }
+
+    # Permission errors - don't retry
+    PERMISSION_ERRORS: Set[str] = {
+        "Missing Permissions",
+        "Missing Access",
+        "Cannot send messages",
+    }
+
+    @classmethod
+    def classify_error(cls, error: Exception, reconnect_attempts: int = 0) -> ErrorClassification:
+        """
+        Classify a Discord error and determine retry strategy.
+
+        Args:
+            error: The exception that occurred
+            reconnect_attempts: Number of previous retry attempts
+
+        Returns:
+            ErrorClassification with retry strategy
+        """
+        error_str = str(error)
+        error_type = type(error).__name__
+
+        # First check by exception type (like existing logic)
+        if cls._is_connection_exception(error):
+            return ErrorClassification(
+                category=ErrorCategory.NETWORK,
+                is_transient=True,
+                should_retry=reconnect_attempts < 10,
+                retry_delay=min(5.0 * (2 ** max(0, reconnect_attempts - 1)), 60.0),  # Match existing formula
+                max_retries=10,
+                description=f"Connection exception ({error_type}): {error_str}",
+            )
+
+        # Check for aiohttp exceptions (like existing logic)
+        if error.__class__.__module__.startswith("aiohttp"):
+            return ErrorClassification(
+                category=ErrorCategory.NETWORK,
+                is_transient=True,
+                should_retry=reconnect_attempts < 8,
+                retry_delay=min(2.0**reconnect_attempts, 45.0),
+                max_retries=8,
+                description=f"Aiohttp error ({error_type}): {error_str}",
+            )
+
+        # Discord.py specific exceptions that should NOT retry
+        if cls._is_discord_non_retryable(error):
+            return ErrorClassification(
+                category=ErrorCategory.AUTHENTICATION,
+                is_transient=False,
+                should_retry=False,
+                retry_delay=0.0,
+                max_retries=0,
+                description=f"Discord auth error ({error_type}): {error_str}",
+            )
+
+        # Then check by string patterns
+        if cls._matches_any(error_str, cls.NETWORK_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.NETWORK,
+                is_transient=True,
+                should_retry=reconnect_attempts < 10,
+                retry_delay=min(5.0 * (2 ** max(0, reconnect_attempts - 1)), 60.0),  # Match existing formula
+                max_retries=10,
+                description=f"Network error: {error_str}",
+            )
+
+        if cls._matches_any(error_str, cls.WEBSOCKET_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.WEBSOCKET,
+                is_transient=True,
+                should_retry=reconnect_attempts < 15,
+                retry_delay=min(1.5**reconnect_attempts, 30.0),
+                max_retries=15,
+                description=f"WebSocket error: {error_str}",
+            )
+
+        if cls._matches_any(error_str, cls.SERVER_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.SERVER,
+                is_transient=True,
+                should_retry=reconnect_attempts < 8,
+                retry_delay=min(3.0 * (reconnect_attempts + 1), 120.0),  # Start at 3.0, not 3^0
+                max_retries=8,
+                description=f"Server error: {error_str}",
+            )
+
+        if cls._matches_any(error_str, cls.RATE_LIMIT_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.RATE_LIMIT,
+                is_transient=True,
+                should_retry=reconnect_attempts < 5,
+                retry_delay=60.0 + (reconnect_attempts * 30.0),  # Long delays for rate limits
+                max_retries=5,
+                description=f"Rate limit error: {error_str}",
+            )
+
+        if cls._matches_any(error_str, cls.SSL_TLS_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.SSL_TLS,
+                is_transient=True,
+                should_retry=reconnect_attempts < 3,
+                retry_delay=5.0 + (reconnect_attempts * 5.0),
+                max_retries=3,
+                description=f"SSL/TLS error: {error_str}",
+            )
+
+        if cls._matches_any(error_str, cls.AUTH_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.AUTHENTICATION,
+                is_transient=False,
+                should_retry=False,
+                retry_delay=0.0,
+                max_retries=0,
+                description=f"Authentication error: {error_str}",
+            )
+
+        if cls._matches_any(error_str, cls.PERMISSION_ERRORS):
+            return ErrorClassification(
+                category=ErrorCategory.PERMISSION,
+                is_transient=False,
+                should_retry=False,
+                retry_delay=0.0,
+                max_retries=0,
+                description=f"Permission error: {error_str}",
+            )
+
+        # Unknown error - retry cautiously
+        logger.warning(f"Unknown Discord error type: {error_type}, message: {error_str}")
+        return ErrorClassification(
+            category=ErrorCategory.UNKNOWN,
+            is_transient=True,
+            should_retry=reconnect_attempts < 3,
+            retry_delay=10.0,
+            max_retries=3,
+            description=f"Unknown error ({error_type}): {error_str}",
+        )
+
+    @staticmethod
+    def _matches_any(error_str: str, patterns: Set[str]) -> bool:
+        """Check if error string matches any pattern in set."""
+        return any(pattern.lower() in error_str.lower() for pattern in patterns)
+
+    @staticmethod
+    def _is_connection_exception(error: Exception) -> bool:
+        """Check if exception is a connection-related type (matches existing logic)."""
+        try:
+            import discord
+
+            connection_types = (
+                RuntimeError,
+                discord.ConnectionClosed,
+                discord.HTTPException,
+                discord.GatewayNotFound,
+                ConnectionError,
+                ConnectionResetError,
+                ConnectionAbortedError,
+                ConnectionRefusedError,
+                TimeoutError,
+                OSError,
+            )
+            return isinstance(error, connection_types)
+        except ImportError:
+            # Fallback if discord.py not available
+            builtin_types = (
+                RuntimeError,
+                ConnectionError,
+                ConnectionResetError,
+                ConnectionAbortedError,
+                ConnectionRefusedError,
+                TimeoutError,
+                OSError,
+            )
+            return isinstance(error, builtin_types)
+
+    @staticmethod
+    def _is_discord_non_retryable(error: Exception) -> bool:
+        """Check if exception is a Discord non-retryable type (matches existing logic)."""
+        try:
+            import discord
+
+            non_retryable_types = (
+                discord.LoginFailure,
+                discord.Forbidden,
+            )
+            return isinstance(error, non_retryable_types)
+        except ImportError:
+            return False
+
+    @classmethod
+    def log_error_classification(cls, classification: ErrorClassification, attempt: int) -> None:
+        """Log error classification with appropriate level."""
+        if classification.should_retry:
+            logger.warning(
+                f"Discord {classification.category.value} error (attempt {attempt}/{classification.max_retries}): "
+                f"{classification.description}. Retrying in {classification.retry_delay:.1f}s"
+            )
+        else:
+            logger.error(
+                f"Discord {classification.category.value} error (non-recoverable): " f"{classification.description}"
+            )

ciris_engine/logic/adapters/discord/discord_error_handler.py

@@ -0,0 +1,316 @@
+"""Discord error handling and recovery component."""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Awaitable, Callable, Optional, Union
+
+import discord
+from discord.errors import ConnectionClosed, Forbidden, HTTPException, LoginFailure, NotFound, RateLimited
+
+from ciris_engine.schemas.adapters.discord import DiscordErrorInfo
+from ciris_engine.schemas.adapters.discord import ErrorSeverity as SchemaErrorSeverity
+
+logger = logging.getLogger(__name__)
+
+
+# Use ErrorSeverity from schema
+ErrorSeverity = SchemaErrorSeverity
+
+
+class DiscordErrorHandler:
+    """Centralized error handling for Discord operations."""
+
+    def __init__(self, on_critical_error: Optional[Callable[[str, Exception], Awaitable[None]]] = None):
+        """Initialize error handler.
+
+        Args:
+            on_critical_error: Callback for critical errors
+        """
+        self.on_critical_error = on_critical_error
+        self._error_counts: dict[str, int] = {}
+        self._last_errors: dict[str, datetime] = {}
+        self._error_threshold = 5  # Errors before escalation
+        self._error_window = timedelta(minutes=5)  # Time window for error counting
+
+    def handle_channel_error(self, channel_id: str, error: Exception, operation: str = "unknown") -> DiscordErrorInfo:
+        """Handle channel-related errors.
+
+        Args:
+            channel_id: Discord channel ID
+            error: The exception that occurred
+            operation: What operation was being performed
+
+        Returns:
+            Error handling result with severity and suggested action
+        """
+        error_key = f"channel_{channel_id}_{type(error).__name__}"
+        severity = ErrorSeverity.MEDIUM
+        can_retry = True
+        fallback_action = None
+
+        if isinstance(error, NotFound):
+            severity = ErrorSeverity.HIGH
+            can_retry = False
+            fallback_action = "remove_channel"
+            message = f"Channel {channel_id} not found - it may have been deleted"
+
+        elif isinstance(error, Forbidden):
+            severity = ErrorSeverity.HIGH
+            can_retry = False
+            fallback_action = "check_permissions"
+            message = f"No permission to access channel {channel_id} for {operation}"
+
+        elif isinstance(error, HTTPException):
+            if error.status == 429:  # Rate limited
+                severity = ErrorSeverity.MEDIUM
+                can_retry = True
+                fallback_action = "wait_and_retry"
+                message = f"Rate limited on channel {channel_id}"
+            else:
+                severity = ErrorSeverity.MEDIUM
+                message = f"HTTP error {error.status} on channel {channel_id}: {error.text}"
+
+        else:
+            message = f"Unexpected error with channel {channel_id}: {str(error)}"
+
+        # Track error frequency
+        self._track_error(error_key, severity)
+
+        result = DiscordErrorInfo(
+            severity=severity,
+            message=message,
+            can_retry=can_retry,
+            fallback_action=fallback_action,
+            error_type=type(error).__name__,
+            channel_id=channel_id,
+            operation=operation,
+        )
+
+        logger.error(f"Channel error: {result.model_dump()}")
+        return result
+
+    def handle_message_error(
+        self, error: Exception, message_content: Optional[str] = None, channel_id: Optional[str] = None
+    ) -> DiscordErrorInfo:
+        """Handle message-related errors.
+
+        Args:
+            error: The exception that occurred
+            message_content: Content of the message (for context)
+            channel_id: Channel where message was being sent
+
+        Returns:
+            Error handling result
+        """
+        error_key = f"message_{type(error).__name__}"
+        severity = ErrorSeverity.LOW
+        can_retry = True
+        suggested_fix = None
+
+        if isinstance(error, HTTPException) and error.status == 400:
+            # Bad request - likely message too long or invalid
+            severity = ErrorSeverity.MEDIUM
+            can_retry = False
+            if message_content and len(message_content) > 2000:
+                suggested_fix = "split_message"
+                message = "Message too long (>2000 chars)"
+            else:
+                suggested_fix = "validate_content"
+                message = f"Invalid message content: {error.text}"
+
+        elif isinstance(error, Forbidden):
+            severity = ErrorSeverity.HIGH
+            can_retry = False
+            suggested_fix = "check_channel_permissions"
+            message = f"Cannot send message to channel {channel_id}"
+
+        else:
+            message = f"Message send error: {str(error)}"
+
+        self._track_error(error_key, severity)
+
+        result = DiscordErrorInfo(
+            severity=severity,
+            message=message,
+            can_retry=can_retry,
+            suggested_fix=suggested_fix,
+            error_type=type(error).__name__,
+            channel_id=channel_id,
+        )
+
+        logger.error(f"Message error: {result.model_dump()}")
+        return result
+
+    async def handle_connection_error(self, error: Exception) -> DiscordErrorInfo:
+        """Handle connection-related errors.
+
+        Args:
+            error: The connection error
+
+        Returns:
+            Error handling result
+        """
+        error_key = f"connection_{type(error).__name__}"
+        severity = ErrorSeverity.CRITICAL
+        recovery_action = "reconnect"
+
+        if isinstance(error, LoginFailure):
+            severity = ErrorSeverity.CRITICAL
+            recovery_action = "check_token"
+            message = "Failed to login - check bot token"
+
+        elif isinstance(error, ConnectionClosed):
+            severity = ErrorSeverity.HIGH
+            recovery_action = "reconnect"
+            message = f"Connection closed: {error.code} - {error.reason}"
+
+        else:
+            message = f"Connection error: {str(error)}"
+
+        self._track_error(error_key, severity)
+
+        # Notify critical error handler if available
+        if severity == ErrorSeverity.CRITICAL and self.on_critical_error:
+            await self.on_critical_error(message, error)
+
+        result = DiscordErrorInfo(
+            severity=severity,
+            message=message,
+            recovery_action=recovery_action,
+            error_type=type(error).__name__,
+            can_retry=True,  # Connection errors are generally retryable
+        )
+
+        logger.critical(f"Connection error: {result.model_dump()}")
+        return result
+
+    def handle_api_error(self, error: Exception, endpoint: str) -> DiscordErrorInfo:
+        """Handle Discord API errors.
+
+        Args:
+            error: The API error
+            endpoint: API endpoint that failed
+
+        Returns:
+            Error handling result
+        """
+        error_key = f"api_{endpoint}_{type(error).__name__}"
+        severity = ErrorSeverity.MEDIUM
+        retry_after = None
+
+        if isinstance(error, RateLimited):
+            severity = ErrorSeverity.LOW
+            retry_after = error.retry_after
+            message = f"Rate limited on {endpoint}, retry after {retry_after}s"
+
+        elif isinstance(error, HTTPException):
+            if 500 <= error.status < 600:
+                severity = ErrorSeverity.MEDIUM
+                message = f"Discord server error on {endpoint}: {error.status}"
+            else:
+                message = f"Discord API error on {endpoint}: {error.status} - {error.text}"
+
+        else:
+            message = f"API error on {endpoint}: {str(error)}"
+
+        self._track_error(error_key, severity)
+
+        result = DiscordErrorInfo(
+            severity=severity,
+            message=message,
+            retry_after=retry_after,
+            error_type=type(error).__name__,
+            endpoint=endpoint,
+            can_retry=True,  # API errors are generally retryable
+        )
+
+        logger.error(f"API error: {result.model_dump()}")
+        return result
+
+    def _track_error(self, error_key: str, severity: ErrorSeverity) -> None:
+        """Track error frequency and escalate if needed.
+
+        Args:
+            error_key: Unique key for this error type
+            severity: Error severity
+        """
+        now = datetime.now(timezone.utc)
+
+        # Clean old errors
+        cutoff = now - self._error_window
+        self._error_counts = {
+            k: v for k, v in self._error_counts.items() if k not in self._last_errors or self._last_errors[k] > cutoff
+        }
+
+        # Track this error
+        self._error_counts[error_key] = self._error_counts.get(error_key, 0) + 1
+        self._last_errors[error_key] = now
+
+        # Check for escalation
+        if self._error_counts[error_key] >= self._error_threshold:
+            logger.warning(
+                f"Error threshold reached for {error_key}: "
+                f"{self._error_counts[error_key]} errors in {self._error_window}"
+            )
+
+            # Escalate severity
+            if severity == ErrorSeverity.LOW:
+                severity = ErrorSeverity.MEDIUM
+            elif severity == ErrorSeverity.MEDIUM:
+                severity = ErrorSeverity.HIGH
+
+    def get_error_stats(self) -> dict[str, Union[dict[str, int], int, float]]:
+        """Get current error statistics.
+
+        Returns:
+            Error statistics
+        """
+        return {
+            "error_counts": self._error_counts.copy(),
+            "threshold": self._error_threshold,
+            "window_minutes": self._error_window.total_seconds() / 60,
+        }
+
+    def create_error_embed(self, error_info: DiscordErrorInfo) -> discord.Embed:
+        """Create a Discord embed for error reporting.
+
+        Args:
+            error_info: Error information dictionary
+
+        Returns:
+            Discord embed for the error
+        """
+        # Color based on severity
+        colors = {
+            ErrorSeverity.LOW: 0x3498DB,  # Blue
+            ErrorSeverity.MEDIUM: 0xF39C12,  # Orange
+            ErrorSeverity.HIGH: 0xE74C3C,  # Red
+            ErrorSeverity.CRITICAL: 0x992D22,  # Dark red
+        }
+
+        embed = discord.Embed(
+            title=f"⚠️ Error: {error_info.error_type}",
+            description=error_info.message,
+            color=colors.get(error_info.severity, 0x95A5A6),
+            timestamp=datetime.now(timezone.utc),
+        )
+
+        # Add fields
+        if error_info.operation:
+            embed.add_field(name="Operation", value=error_info.operation, inline=True)
+
+        if error_info.channel_id:
+            embed.add_field(name="Channel", value=f"<#{error_info.channel_id}>", inline=True)
+
+        embed.add_field(name="Severity", value=error_info.severity.value.upper(), inline=True)
+        embed.add_field(name="Retryable", value="Yes" if error_info.can_retry else "No", inline=True)
+
+        if error_info.suggested_fix:
+            embed.add_field(name="Suggested Fix", value=error_info.suggested_fix, inline=False)
+
+        if error_info.retry_after:
+            embed.add_field(name="Retry After", value=f"{error_info.retry_after} seconds", inline=True)
+
+        embed.set_footer(text="Discord Error Handler")
+
+        return embed