"""Custom exceptions for MCA SDK.

This module defines exception classes used throughout the SDK for
error handling and validation failures.
"""

from typing import Optional


class MCASDKError(Exception):
    """Base exception class for all MCA SDK errors.

    Use this to catch any SDK-related exception.

    Examples:
        - Catching all SDK errors:
          try:
              client = MCAClient(...)
          except MCASDKError as e:
              print(f"SDK error: {e}")
    """


class ValidationError(MCASDKError):
    """Raised when validation fails.

    Attributes:
        missing_fields: List of missing required fields (if applicable)
        invalid_fields: Dict of invalid field names to error messages (if applicable)
        model_type: Model type being validated (if applicable)
        model_category: Model category being validated (if applicable)

    Examples:
        - Metric name doesn't follow naming conventions
        - Required resource attributes are missing
        - Invalid configuration values
    """

    def __init__(
        self,
        message: str,
        missing_fields: Optional[list] = None,
        invalid_fields: Optional[dict] = None,
        model_type: Optional[str] = None,
        model_category: Optional[str] = None,
    ):
        """Initialize ValidationError with optional field details.

        Args:
            message: Error message
            missing_fields: List of missing required field names
            invalid_fields: Dict mapping field names to validation error messages
            model_type: Model type being validated (e.g., "regression", "generative")
            model_category: Model category being validated (e.g., "internal", "vendor")
        """
        super().__init__(message)
        self.missing_fields = missing_fields or []
        self.invalid_fields = invalid_fields or {}
        self.model_type = model_type
        self.model_category = model_category


class BufferingError(MCASDKError):
    """Raised when buffering operations fail.

    Examples:
        - Queue is full and cannot accept more items
        - Disk persistence failure
        - Background worker thread failure
    """


class ConfigurationError(MCASDKError):
    """Raised when configuration is invalid or incomplete.

    Examples:
        - Missing required configuration fields
        - Invalid configuration file format
        - Conflicting configuration values
    """


class RegistryError(MCASDKError):
    """Base exception for registry operations.

    Examples:
        - Registry communication failures
        - Invalid registry responses
        - Registry configuration errors
    """


class RegistryConnectionError(RegistryError):
    """Raised when unable to connect to the registry.

    Examples:
        - Network timeout
        - DNS resolution failure
        - Connection refused
    """


class RegistryConfigNotFoundError(RegistryError):
    """Raised when model configuration not found in registry.

    Examples:
        - Model ID does not exist
        - Deployment ID not found
        - Version not available
    """


class RegistryAuthError(RegistryError):
    """Raised when registry authentication fails.

    Examples:
        - Invalid or expired token
        - Missing authentication credentials
        - Insufficient permissions
    """


class SecurityError(MCASDKError):
    """Raised when security validation fails.

    Examples:
        - Insecure file permissions on private key
        - Missing security credentials
        - Security policy violations
    """


class CertificateError(SecurityError):
    """Base exception for certificate operations.

    Examples:
        - Certificate loading failures
        - Certificate validation errors
        - Certificate rotation issues
    """


class CertificateLoadError(CertificateError):
    """Raised when certificate cannot be loaded from disk.

    Examples:
        - File not found
        - Invalid PEM format
        - Malformed certificate data
    """


class CertificateValidationError(CertificateError):
    """Raised when certificate validation fails.

    Examples:
        - Private key doesn't match certificate
        - Certificate chain validation failure
        - Invalid certificate format
    """


class CertificateExpiredError(CertificateError):
    """Raised when certificate has expired.

    Examples:
        - Certificate not_valid_after date has passed
        - Attempting to use expired certificate
    """


class CertificateNotLoadedError(CertificateError):
    """Raised when certificate operation requires loaded certificate.

    Examples:
        - Calling get_ssl_context() before certificate loaded
        - Certificate manager not initialized
    """
