geospatial_types/
error.rs

1//! The typed error model shared across every crate and exposed over the
2//! binding layer.
3
4use serde::{Deserialize, Serialize};
5
6/// Underlying cause reported by [`SDKError::CacheOperationFailure`].
7#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
8pub enum CacheOperationFailureReason {
9    /// The backing store could not be opened or migrated.
10    StoreUnavailable,
11    /// A persisted record failed integrity validation.
12    RecordCorrupted,
13    /// A write or eviction could not complete within budget.
14    WriteRejected,
15}
16
17/// Underlying cause reported by [`SDKError::OfflineRoutingFailure`].
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19pub enum OfflineGraphInvalidReason {
20    /// The archive header or vector offsets are misaligned or truncated.
21    ArchiveMalformed,
22    /// The archive schema version is not understood by this SDK.
23    VersionUnsupported,
24    /// Referenced node or edge indices fall outside the archive bounds.
25    IndexOutOfRange,
26}
27
28/// Every failure path surfaced by the SDK. Serialized across the binding
29/// layer, so variants and field names are part of the frozen contract.
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
31pub enum SDKError {
32    /// A coordinate, bounding box or request option failed validation.
33    InvalidCoordinateInput(String),
34    /// The network transport failed (connection, timeout, or DNS).
35    NetworkRequestFailed(String),
36    /// The provider responded with a payload the parser could not use.
37    ResponseParsingFailure(String),
38    /// The provider returned a documented application-level failure status.
39    ProviderRequestRejected(String),
40    /// The token-bucket limiter is exhausted; retry after the next refill.
41    RateLimitExhausted,
42    /// No provider implementation is registered for the requested contract.
43    ProviderNotConfigured(String),
44    /// A cache read or write failed for the stated reason.
45    CacheOperationFailure(CacheOperationFailureReason),
46    /// The offline routing graph failed validation for the stated reason.
47    OfflineRoutingFailure(OfflineGraphInvalidReason),
48}
49
50impl std::fmt::Display for SDKError {
51    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        match self {
53            Self::InvalidCoordinateInput(detail) => {
54                write!(formatter, "invalid coordinate input: {detail}")
55            }
56            Self::NetworkRequestFailed(detail) => {
57                write!(formatter, "network request failed: {detail}")
58            }
59            Self::ResponseParsingFailure(detail) => {
60                write!(formatter, "response parsing failure: {detail}")
61            }
62            Self::ProviderRequestRejected(detail) => {
63                write!(formatter, "provider rejected request: {detail}")
64            }
65            Self::RateLimitExhausted => write!(formatter, "rate limit exhausted"),
66            Self::ProviderNotConfigured(contract_name) => {
67                write!(formatter, "no provider configured for {contract_name}")
68            }
69            Self::CacheOperationFailure(reason) => {
70                write!(formatter, "cache operation failure: {reason:?}")
71            }
72            Self::OfflineRoutingFailure(reason) => {
73                write!(formatter, "offline graph invalid: {reason:?}")
74            }
75        }
76    }
77}
78
79impl std::error::Error for SDKError {}
geospatial_types/error.rs

geospatial_types/
error.rs
