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 {}