Skip to main content

arcadedb_protocol/
error.rs

1//! The client-facing error type: every fallible [`ArcadeDbClient`](crate::ArcadeDbClient)
2//! / [`DatabaseClient`](crate::DatabaseClient) call returns
3//! [`Result<T, ArcadeDbError>`](Result) instead of an opaque error.
4//! Matching on the failure category distinguishes transport vs.
5//! server-rejected vs. decode vs. client-side validation errors, and the
6//! gRPC [`tonic::Code`] stays inspectable.
7
8use crate::record::RecordDecodeError;
9
10/// The error type for all client operations.
11///
12/// Variants are grouped by failure category; see each variant.
13#[derive(Debug, thiserror::Error)]
14#[non_exhaustive]
15pub enum ArcadeDbError {
16    /// The connect retry loop exhausted its attempts (cold server that never
17    /// came up, wrong address, …). `source` is the last transport error when
18    /// at least one attempt got that far.
19    #[error("failed to connect to ArcadeDB gRPC at {addr} after {attempts} attempts")]
20    Connect {
21        /// The `host:port` that was retried.
22        addr: String,
23        /// How many connect attempts were made.
24        attempts: u32,
25        /// The last underlying transport error, if any attempt produced one.
26        #[source]
27        source: Option<tonic::transport::Error>,
28    },
29
30    /// The endpoint string could not be parsed into a gRPC endpoint.
31    #[error("invalid gRPC endpoint {addr}")]
32    InvalidEndpoint {
33        /// The rejected endpoint string.
34        addr: String,
35        /// Why the URI parser rejected it.
36        #[source]
37        source: http::uri::InvalidUri,
38    },
39
40    /// A gRPC call failed at the transport/status layer. The full
41    /// [`tonic::Status`] is preserved — use [`ArcadeDbError::code`] to branch
42    /// on the gRPC code (e.g. retry on `Unavailable`, fail fast on
43    /// `Unauthenticated`).
44    #[error("{operation} failed: {status} (in: {detail})")]
45    Rpc {
46        /// What the client was doing, e.g. `"query"`, `"commit transaction"`.
47        operation: String,
48        /// The operation's subject — the SQL text, rid, database name, … —
49        /// empty when the operation has no natural subject.
50        detail: String,
51        /// The underlying gRPC status (code, message, metadata).
52        #[source]
53        status: tonic::Status,
54    },
55
56    /// The server rejected the operation because the target already exists
57    /// (database, type, property, index). Normalized from both transport
58    /// failures and `success = false` responses — the engine reports this
59    /// only through the error *message* (no structured gRPC code yet), so the
60    /// client detects it once at its boundary; matching this variant is the
61    /// stable consumer-facing contract.
62    #[error("{what}: {message}")]
63    AlreadyExists {
64        /// What the client was doing, e.g. `"create database"`.
65        what: String,
66        /// The server's own explanation.
67        message: String,
68    },
69
70    /// The server processed the request but answered `success = false`.
71    #[error("command failed: {message}")]
72    CommandFailed {
73        /// What the client was doing, e.g. `"commit transaction"`.
74        operation: String,
75        /// The server's own explanation.
76        message: String,
77        /// Records the server reported as affected, when it reports a count.
78        affected: Option<i64>,
79    },
80
81    /// A typed decode of a returned record failed (e.g. the `TryFrom<&GrpcRecord>`
82    /// in [`lookup`](crate::ArcadeDbClient::lookup)).
83    #[error("decode {what}")]
84    Decode {
85        /// What was being decoded, e.g. `"lookup record #12:0"`.
86        what: String,
87        /// The typed decode failure — missing field, type mismatch, ….
88        #[source]
89        source: RecordDecodeError,
90    },
91
92    /// A read that was expected to return at least one row returned none
93    /// ([`fetch_one`](crate::ArcadeDbClient::fetch_one),
94    /// [`QueryResult::one`](crate::QueryResult::one),
95    /// [`upsert_returning`](crate::ArcadeDbClient::upsert_returning)).
96    /// Distinct from `Rpc` — the transport and the command both succeeded;
97    /// the empty result *is* the answer.
98    #[error("no rows returned by {operation} (expected at least one: {detail})")]
99    NotFound {
100        /// What was reading, e.g. `"fetch_one"`.
101        operation: String,
102        /// The query or subject that came up empty.
103        detail: String,
104    },
105
106    /// Client-side validation rejected the call before it hit the wire
107    /// (e.g. a `bulk_upsert_dtos` DTO without `#[record(key)]` columns).
108    #[error("{message}")]
109    InvalidInput {
110        /// What was rejected and why.
111        message: String,
112    },
113}
114
115impl ArcadeDbError {
116    /// The gRPC status code, when this error carries a [`tonic::Status`]
117    /// (only [`Rpc`](ArcadeDbError::Rpc) does). Useful for retry/fail-fast
118    /// branching without matching the variant structure.
119    pub fn code(&self) -> Option<tonic::Code> {
120        match self {
121            ArcadeDbError::Rpc { status, .. } => Some(status.code()),
122            _ => None,
123        }
124    }
125
126    /// The server's own error message, when there is one
127    /// ([`ArcadeDbError::Rpc`], [`ArcadeDbError::CommandFailed`], and
128    /// [`ArcadeDbError::AlreadyExists`] carry it).
129    pub fn server_message(&self) -> Option<&str> {
130        match self {
131            ArcadeDbError::Rpc { status, .. } => Some(status.message()),
132            ArcadeDbError::CommandFailed { message, .. } => Some(message),
133            ArcadeDbError::AlreadyExists { message, .. } => Some(message),
134            _ => None,
135        }
136    }
137}
138
139/// The crate-wide result alias: every fallible client operation returns it.
140pub type Result<T, E = ArcadeDbError> = std::result::Result<T, E>;