"""BlackAnt SDK exception classes.

Central exception hierarchy for all BlackAnt SDK errors.
"""


class BlackAntException(Exception):
    """Base exception for all BlackAnt SDK errors.

    All SDK-specific exceptions inherit from this base class
    to allow catching all SDK errors with a single handler.
    """


class BlackAntAuthenticationError(BlackAntException):
    """Authentication and authorization related errors.

    Raised when:
    - Login credentials are invalid
    - Keycloak authentication fails
    - Bearer token is missing or expired
    - Authorization is denied
    """


class BlackAntDockerError(BlackAntException):
    """Docker operation related errors.

    Raised when:
    - Docker API calls fail
    - Container operations encounter issues
    - Image operations fail
    - Registry communication errors
    """


class BlackAntConnectionError(BlackAntException):
    """Network and connection related errors.

    Raised when:
    - HTTP requests timeout
    - Network connection fails
    - API endpoints are unreachable
    """


class BlackAntConfigurationError(BlackAntException):
    """Configuration related errors.

    Raised when:
    - Required environment variables are missing
    - Configuration files are invalid
    - Service configuration is incorrect
    """


# =============================================================================
# Keycloak & Role Assignment Exceptions
# =============================================================================


class KeycloakError(BlackAntException):
    """Base exception for Keycloak-related errors.

    All Keycloak-specific exceptions inherit from this base class
    to allow catching all Keycloak errors with a single handler.
    """


class KeycloakConnectionError(KeycloakError):
    """Raised when connection to Keycloak server fails.

    This can occur due to:
    - Network connectivity issues
    - Incorrect server URL
    - Firewall blocking connection
    - Keycloak server being down
    """


class KeycloakAuthenticationError(KeycloakError):
    """Raised when Keycloak authentication fails.

    This can occur due to:
    - Invalid service account credentials
    - Expired client secret
    - Incorrect client ID
    - Insufficient permissions for service account
    """


class RoleAssignmentError(KeycloakError):
    """Raised when role assignment operation fails.

    This can occur due to:
    - Role does not exist in realm
    - User does not exist
    - Insufficient permissions to assign role
    - Keycloak API error during assignment
    """


class TokenValidationError(BlackAntException):
    """Raised when JWT token validation fails.

    This can occur due to:
    - Invalid token format
    - Missing required claims (sub, etc.)
    - Expired token
    - Token signature validation failure
    """
