pamoja_core/
error.rs

1//! The error model shared by every pamoja crate.
2//!
3//! A single [`Error`] type keeps failure handling uniform across capabilities and
4//! maps cleanly onto each language binding's native error idiom, such as
5//! exceptions or rejected promises.
6
7use alloc::string::String;
8use core::fmt;
9
10/// The error type returned by all fallible pamoja operations.
11///
12/// This enum is `#[non_exhaustive]`: new variants may be added in future releases
13/// without a breaking change, so downstream `match` expressions must include a
14/// wildcard arm.
15#[derive(Debug)]
16#[non_exhaustive]
17pub enum Error {
18    /// A transport-level failure while connecting, sending, or receiving.
19    ///
20    /// The payload is a human-readable description provided by the transport.
21    Transport(String),
22
23    /// A device or peripheral input/output operation failed.
24    ///
25    /// The payload is a human-readable description of the I/O fault.
26    Io(String),
27
28    /// A payload could not be encoded or decoded.
29    ///
30    /// The payload describes the encoding or decoding fault.
31    Codec(String),
32
33    /// The operation targeted a resource that is closed or disconnected.
34    Closed,
35
36    /// A security check failed, such as an invalid identity or a bad signature.
37    ///
38    /// The payload describes the authentication or integrity fault.
39    Auth(String),
40
41    /// The requested capability is not compiled into this build.
42    ///
43    /// The payload names the missing capability, for example `"mqtt"`.
44    Unsupported(&'static str),
45}
46
47impl fmt::Display for Error {
48    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
49        match self {
50            Self::Transport(message) => write!(f, "transport error: {message}"),
51            Self::Io(message) => write!(f, "io error: {message}"),
52            Self::Codec(message) => write!(f, "codec error: {message}"),
53            Self::Closed => f.write_str("resource is closed"),
54            Self::Auth(message) => write!(f, "authentication error: {message}"),
55            Self::Unsupported(capability) => {
56                write!(f, "unsupported capability: {capability}")
57            }
58        }
59    }
60}
61
62#[cfg(feature = "std")]
63impl std::error::Error for Error {}
64
65/// A specialized [`core::result::Result`] whose error type is fixed to [`Error`].
66pub type Result<T> = core::result::Result<T, Error>;
pamoja_core/error.rs

pamoja_core/
error.rs
