Error Handling

class PluginError(Exception):
    """Base plugin framework exception for technical errors

    Used for: Plugin failures, configuration errors, infrastructure issues
    Behavior: Can be ignored in permissive mode, blocks in enforce mode
    """
    def __init__(self, message: str, error: Optional[PluginErrorModel] = None):
        self.error = error                     # Structured error details
        super().__init__(message)

class PluginViolationError(PluginError):
    """Plugin policy violation exception

    Used for: Security violations, policy breaches, content violations
    Behavior: Always blocks requests (except in permissive mode with logging)
    """
    def __init__(self, message: str, violation: Optional[PluginViolation] = None):
        self.violation = violation             # Structured violation details
        super().__init__(message)

class PluginTimeoutError(Exception):
    """Plugin execution timeout exception

    Used for: Plugin execution exceeds configured timeout
    Behavior: Treated as technical error, handled by plugin mode
    """
    pass

class PayloadSizeError(ValueError):
    """Payload size exceeds limits exception

    Used for: Request payloads exceeding size limits (default 1MB)
    Behavior: Immediate request rejection, security protection
    """
    pass

# Technical error example
try:
    result = await external_service_call()
except ConnectionError as e:
    error_model = PluginErrorModel(
        message="Failed to connect to external service",
        code="CONNECTION_FAILED",
        details={"service_url": service_url, "timeout": 30},
        plugin_name=self.name
    )
    raise PluginError("External service unavailable", error=error_model)

# Policy violation example
if contains_pii(content):
    violation = PluginViolation(
        reason="Personal information detected",
        description="Content contains Social Security Numbers",
        code="PII_SSN_DETECTED",
        details={"pattern_count": 2, "confidence": 0.95}
    )
    raise PluginViolationError("PII violation", violation=violation)

# System protection example
if len(payload_data) > MAX_PAYLOAD_SIZE:
    raise PayloadSizeError(f"Payload size {len(payload_data)} exceeds limit {MAX_PAYLOAD_SIZE}")

class PluginErrorModel(BaseModel):
    """Structured technical error information"""
    message: str                               # Human-readable error description
    code: Optional[str] = ""                   # Machine-readable error code
    details: Optional[dict[str, Any]] = Field(default_factory=dict) # Additional context
    plugin_name: str                           # Plugin that generated error

class PluginViolation(BaseModel):
    """Plugin policy violation details"""
    reason: str                                # High-level violation category
    description: str                           # Detailed human-readable description
    code: str                                  # Machine-readable violation code
    details: dict[str, Any]                    # Structured violation context
    _plugin_name: str = PrivateAttr(default="") # Plugin attribution (set by manager)

    @property
    def plugin_name(self) -> str:
        """Get plugin name that detected violation"""
        return self._plugin_name

    @plugin_name.setter
    def plugin_name(self, name: str) -> None:
        """Set plugin name (used by plugin manager)"""
        self._plugin_name = name

# Comprehensive technical error
technical_error = PluginErrorModel(
    message="OpenAI API request failed with rate limit error",
    code="EXTERNAL_API_RATE_LIMITED",
    details={
        "api_endpoint": "https://api.openai.com/v1/moderations",
        "response_code": 429,
        "retry_after": 60,
        "request_id": "req_abc123",
        "usage_info": {
            "requests_this_minute": 60,
            "limit_per_minute": 60
        }
    },
    plugin_name="OpenAIModerationPlugin"
)

# Detailed policy violation
security_violation = PluginViolation(
    reason="Suspicious file access attempt",
    description="User attempted to access system configuration file outside allowed directory",
    code="PATH_TRAVERSAL_BLOCKED",
    details={
        "requested_path": "../../../etc/passwd",
        "normalized_path": "/etc/passwd",
        "user_id": "user_12345",
        "allowed_paths": ["/app/data", "/tmp/uploads"],
        "risk_level": "HIGH",
        "detection_method": "path_validation"
    }
)
# plugin_name set automatically by PluginManager

class PluginSettings(BaseModel):
    fail_on_plugin_error: bool = False         # Continue on plugin errors globally
    plugin_timeout: int = 30                   # Per-plugin timeout in seconds

# Error handling logic varies by plugin mode
if plugin.mode == PluginMode.ENFORCE:
    # Both violations and errors block requests
    if violation or error:
        raise PluginViolationError("Request blocked")

elif plugin.mode == PluginMode.ENFORCE_IGNORE_ERROR:
    # Violations block, errors are logged and ignored
    if violation:
        raise PluginViolationError("Policy violation")
    if error:
        logger.error(f"Plugin error ignored: {error}")

elif plugin.mode == PluginMode.PERMISSIVE:
    # Log violations and errors, continue processing
    if violation:
        logger.warning(f"Policy violation (permissive): {violation}")
    if error:
        logger.error(f"Plugin error (permissive): {error}")

elif plugin.mode == PluginMode.DISABLED:
    # Plugin is loaded but never executed
    return PluginResult()  # Skip plugin entirely

# Global setting overrides plugin mode for technical errors
if global_settings.fail_on_plugin_error and technical_error:
    # Override plugin mode - always fail on technical errors
    raise PluginError("Global fail_on_plugin_error enabled")

# Plugin mode still controls violation handling
if plugin.mode == PluginMode.PERMISSIVE and violation:
    # Log violation but don't block (plugin mode takes precedence)
    logger.warning(f"Policy violation in permissive mode: {violation}")

# Timeout handling respects plugin mode
if execution_time > global_settings.plugin_timeout:
    timeout_error = PluginTimeoutError(f"Plugin {plugin.name} timed out")
    # Handle timeout according to plugin mode
    if plugin.mode == PluginMode.ENFORCE:
        raise timeout_error
    else:
        logger.error(f"Timeout in {plugin.name} (mode: {plugin.mode})")

async def execute(self, plugins: list[PluginRef], ...) -> tuple[PluginResult[T], PluginContextTable]:
    combined_metadata = {}

    for plugin in plugins:
        try:
            result = await self._execute_with_timeout(plugin, ...)

            # Process successful result
            if result.modified_payload:
                payload = result.modified_payload

        except asyncio.TimeoutError:
            logger.error(f"Plugin {plugin.name} timed out")
            if self.config.fail_on_plugin_error or plugin.mode == PluginMode.ENFORCE:
                raise PluginError(f"Plugin timeout: {plugin.name}")
            # Continue with next plugin

        except PluginViolationError:
            raise  # Re-raise violations

        except Exception as e:
            logger.error(f"Plugin {plugin.name} failed: {e}")
            if self.config.fail_on_plugin_error or plugin.mode == PluginMode.ENFORCE:
                raise PluginError(f"Plugin error: {plugin.name}")
            # Continue with next plugin