Skip to main content

ice_rpc_rx/
error.rs

1//! Technical RPC errors.
2
3use rkyv::{Archive, Deserialize, Serialize};
4
5/// Technical RPC error, categorized so callers can choose a policy
6/// (retry / fallback / log / fatal) via [`RpcError::is_retryable`].
7#[derive(Debug, Clone, PartialEq, Eq, Archive, Serialize, Deserialize)]
8pub enum RpcError {
9    /// Payload serialization/deserialization failure.
10    SerializationError,
11    /// iceoryx2 transport failure (loan, send, receive, port creation).
12    TransportError(String),
13    /// Waiting deadline exceeded.
14    Timeout,
15    /// The call was cancelled by a global shutdown (Ctrl+C).
16    Cancelled,
17    /// Unexpected internal error / invariant violation.
18    Internal(String),
19    /// The service on the bus is not the one this build asks for.
20    ProtocolMismatch(String),
21    /// The provider has no method of that name on the requested service.
22    ///
23    /// Answered immediately by the provider instead of leaving the call to time
24    /// out, so a typo or a stale client is diagnosable.
25    UnknownMethod(String),
26    /// No service is registered under the requested id on that channel.
27    UnknownService(String),
28    /// The provider's service interface version differs from the requested one.
29    ///
30    /// Emitted by the provider before dispatching, so the caller learns the
31    /// contract mismatch instead of waiting for a timeout. No amount of retrying
32    /// resolves it: both peers must be rebuilt with the same `#[service(version)]`.
33    IncompatibleVersion {
34        /// Interface version the provider was built with.
35        expected: u16,
36        /// Interface version the request asked for.
37        actual: u16,
38    },
39}
40
41impl RpcError {
42    /// Returns `true` when retrying the same call may succeed.
43    ///
44    /// Transient failures (transport, timeout) are retryable; serialization
45    /// failures, internal errors, [`RpcError::ProtocolMismatch`],
46    /// [`RpcError::IncompatibleVersion`], [`RpcError::UnknownMethod`] and
47    /// [`RpcError::UnknownService`] — which no amount of retrying resolves — are
48    /// not.
49    pub fn is_retryable(&self) -> bool {
50        matches!(self, RpcError::TransportError(_) | RpcError::Timeout)
51    }
52}
53
54impl std::fmt::Display for RpcError {
55    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
56        match self {
57            RpcError::SerializationError => f.write_str("RPC error: serialization failure"),
58            RpcError::TransportError(message) => write!(f, "RPC transport error: {message}"),
59            RpcError::Timeout => f.write_str("RPC error: timeout exceeded"),
60            RpcError::Cancelled => f.write_str("RPC error: call cancelled"),
61            RpcError::Internal(message) => write!(f, "RPC internal error: {message}"),
62            RpcError::ProtocolMismatch(message) => {
63                write!(f, "RPC error: incompatible service on the bus: {message}")
64            }
65            RpcError::UnknownMethod(method) => {
66                write!(f, "RPC error: unknown method '{method}'")
67            }
68            RpcError::UnknownService(id) => write!(f, "RPC error: unknown service id {id}"),
69            RpcError::IncompatibleVersion { expected, actual } => write!(
70                f,
71                "RPC error: incompatible service version: provider is v{expected}, requested v{actual}"
72            ),
73        }
74    }
75}
76
77impl std::error::Error for RpcError {}