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>;