AirLibrary/Vine/
Error.rs

1//! # Vine Error Handling (Air)
2//!
3//! Air's Vine errors. Re-exports the canonical [`Vine::Error::VineError`]
4//! and provides a thin compatibility layer ([`AirCompat`]) that maps Air's
5//! variant-name aliases onto the canonical variants.
6//!
7//! ## Canonical variants
8//!
9//! [`VineError`] exposes:
10//!
11//! - `ClientNotConnected(String)` - sidecar absent from pool
12//! - `ConnectionFailed { SideCarIdentifier, Address, Reason }`
13//! - `ConnectionLost(String)`
14//! - `RPCError(String)` - generic gRPC failure
15//! - `RequestTimeout { SideCarIdentifier, MethodName, TimeoutMilliseconds }`
16//! - `RequestCanceled { SideCarIdentifier, MethodName }`
17//! - `SerializationError(serde_json::Error)`
18//! - `MessageTooLarge { ActualSize, MaxSize }`
19//! - `InvalidMessageFormat(String)`
20//! - `TonicTransportError(tonic::transport::Error)`
21//! - `InternalLockError(String)`
22//! - `InvalidState(String)`
23//! - `InvalidUri(http::uri::InvalidUri)`
24//! - `AddressParseError(std::net::AddrParseError)`
25//!
26//! Plus [`VineError::IsRecoverable`] / [`VineError::ToTonicStatus`] and
27//! `From` impls for every transport / serialization error in the stack.
28//!
29//! ## Air-flavour aliases
30//!
31//! [`AirCompat`] exposes constructor helpers under Air's prior variant
32//! names (`Transport` / `Serialization` / `ClientNotConnected` / `Timeout`
33//! / `Authentication` / `Authorization` / `Internal`) that build the
34//! equivalent canonical [`VineError`] value. Use the canonical
35//! constructors directly when adding new code; the aliases exist so
36//! older call sites continue to compile.
37
38/// Canonical Vine error type, re-exported from the `Vine` crate.
39///
40/// New code should construct this directly. The [`AirCompat`] helpers
41/// below remain available for callers that prefer Air's prior variant
42/// names.
43/// Canonical Vine error enum, surfaced through Air's `Vine::Error` path.
44pub type VineError = ::Vine::Error::VineError;
45
46/// `Result<T, VineError>` convenience alias.
47pub type Result<T> = ::Vine::Error::Result<T>;
48
49/// Air-flavour compatibility constructors for the canonical [`VineError`].
50///
51/// Each method builds a canonical [`VineError`] value under Air's prior
52/// variant name.
53pub struct AirCompat;
54
55impl AirCompat {
56	/// Builds [`VineError::RPCError`] tagged with a `transport:` prefix.
57	/// Use [`VineError::TonicTransportError`] directly when constructing
58	/// from a `tonic::transport::Error` source.
59	pub fn Transport(Message:impl Into<String>) -> VineError {
60		VineError::RPCError(format!("transport: {}", Message.into()))
61	}
62
63	/// Builds [`VineError::RPCError`] tagged with a `serialization:`
64	/// prefix. Use [`VineError::SerializationError`] directly when
65	/// constructing from a `serde_json::Error` source.
66	pub fn Serialization(Message:impl Into<String>) -> VineError {
67		VineError::RPCError(format!("serialization: {}", Message.into()))
68	}
69
70	/// Same shape as the canonical variant.
71	pub fn ClientNotConnected(Identifier:impl Into<String>) -> VineError {
72		VineError::ClientNotConnected(Identifier.into())
73	}
74
75	/// Builds [`VineError::RequestTimeout`] with `SideCarIdentifier` and
76	/// `TimeoutMilliseconds` set to placeholder defaults; the message is
77	/// stored in `MethodName`.
78	pub fn Timeout(Message:impl Into<String>) -> VineError {
79		VineError::RequestTimeout {
80			SideCarIdentifier:"unknown".to_string(),
81
82			MethodName:Message.into(),
83
84			TimeoutMilliseconds:0,
85		}
86	}
87
88	/// Builds [`VineError::RPCError`] tagged with an `auth:` prefix so log
89	/// greps still hit.
90	pub fn Authentication(Message:impl Into<String>) -> VineError {
91		VineError::RPCError(format!("auth: {}", Message.into()))
92	}
93
94	/// Builds [`VineError::RPCError`] tagged with an `authz:` prefix.
95	pub fn Authorization(Message:impl Into<String>) -> VineError {
96		VineError::RPCError(format!("authz: {}", Message.into()))
97	}
98
99	/// Maps onto [`VineError::InvalidState`].
100	pub fn Internal(Message:impl Into<String>) -> VineError { VineError::InvalidState(Message.into()) }
101}
AirLibrary/Vine/Error.rs

AirLibrary/Vine/
Error.rs
