"""C12 ``FlightsApiClient`` error hierarchy (AZ-489).

Mapped 1:1 to the failure modes in the
``_docs/02_document/contracts/c12_operator_tooling/flights_api_client.md``
exception table.

FAC-INV-7 (auth-token redaction): ``FlightsApiAuthError`` overrides
``__str__`` and ``__repr__`` to never include the token even if the caller
constructs it with one. Other error classes never receive the token in the
first place.
"""

from __future__ import annotations

__all__ = [
    "EmptyWaypointsError",
    "FlightFileNotFoundError",
    "FlightNotFoundError",
    "FlightsApiAuthError",
    "FlightsApiError",
    "FlightsApiSchemaError",
    "FlightsApiUnreachableError",
    "WaypointSchemaError",
]


class FlightsApiError(Exception):
    """Base class for every :class:`FlightsApiClient` failure mode."""


class FlightsApiUnreachableError(FlightsApiError):
    """HTTPS connect failure or persistent 5xx after the single allowed retry.

    Operator should retry the online path once network recovers, or fall
    back to ``--flight-file`` (offline JSON).
    """


class FlightsApiAuthError(FlightsApiError):
    """HTTP 401 / 403 from the flights REST service.

    Never retried; never logs the offending token. The token field is
    deliberately excluded from ``__str__`` / ``__repr__`` so a caller
    ``repr()``-logging the exception cannot leak it.
    """


class FlightNotFoundError(FlightsApiError):
    """HTTP 404 — the supplied ``flight_id`` does not exist on the service."""


class FlightsApiSchemaError(FlightsApiError):
    """Response body (online) or JSON file (offline) violates the DTO schema."""


class FlightFileNotFoundError(FlightsApiError):
    """``--flight-file`` path does not exist on disk."""


class EmptyWaypointsError(FlightsApiError):
    """Resolved flight carries zero waypoints — operator must re-plan in the UI."""


class WaypointSchemaError(FlightsApiError):
    """A single waypoint inside the response is malformed.

    Examples: ``lat_deg`` out of ``[-90, 90]``; ``alt_m`` non-finite;
    negative ``ordinal``; a gap in the ordinal sequence.
    """
