"""Storage exception types — import from here, never redefine elsewhere."""
from __future__ import annotations


class CloudConnectionError(Exception):
    """Raised when a cloud provider signals a non-retryable connection problem.

    Attributes:
        reason: "token_expired"  — access token expired; API layer can refresh and retry.
                "invalid_grant" — refresh token revoked; user must reconnect.

    The backend never updates the DB. The API layer (_call_cloud_op in cloud.py)
    catches this exception, performs the DB state transition, and decides whether
    to retry or surface a 503 to the client (B2 design, D-05/D-06).
    """

    def __init__(self, msg: str = "", *, reason: str = "") -> None:
        super().__init__(msg)
        self.reason = reason  # "token_expired" | "invalid_grant"