aerro 0.6.2

Cross-service gRPC error framework for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

//! Cross-service gRPC errors for Rust.
//!
//! `aerro` gives every error a **typed identity**, a **bounded call trace**, and
//! a **structured wire encoding**. Derive [`Aerro`] on an error enum, call
//! [`IntoStatus`] to encode it into a `tonic::Status`, and [`TryFromStatus`]
//! on the client to recover the original variant — with the full chain of service
//! hops attached.
//!
//! # Quick Example
//!
//! ```rust
//! use aerro::{Aerro, IntoStatus, StatusIntoResultExt};
//! use aerro::wire::encode::EncodeOptions;
//!
//! #[derive(Debug, aerro::Aerro)]
//! pub enum CreateUserError {
//!     #[aerro(category = Business, code = AlreadyExists, error = "email already taken: {email}")]
//!     EmailTaken { email: String },
//!
//!     #[aerro(category = System, code = Internal, error = "db.unavailable")]
//!     DbUnavailable,
//! }
//!
//! // Server side
//! let err = CreateUserError::EmailTaken { email: "alice@example.com".into() };
//! let status = err.into_status(&EncodeOptions::default());
//!
//! // Client side — recover the typed variant
//! let recovered = status.into_aerro::<CreateUserError>().unwrap();
//! ```
//!
//! # Feature Flags
//!
//! | Flag | Default | Description |
//! |------|---------|-------------|
//! | `macro` | ✓ | [`Aerro`] derive macro |
//! | `tracing` | ✓ | Capture OTel trace/span IDs via the `tracing` subscriber |
//! # Key Types
//!
//! - [`Aerro`] — the trait every error type implements (derive or manual)
//! - [`ServiceFailure<E>`](crate::failure::ServiceFailure) — typed error + frames + trace
//! - [`RemoteError`] — type-erased fallback for errors from unknown services
//! - [`Frame`] — one hop in the call chain
//! - [`TraceContext`] — OTel trace/span IDs
//! - [`EncodeOptions`] — egress configuration (exposure tier, frame cap)

/// Current crate version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

pub mod any;
pub mod category;
pub mod error;
pub mod exposure;
pub mod failure;
pub mod frame;
pub mod remote;
pub mod trace;
pub mod traits;

#[cfg(test)]
pub(crate) mod test_support;

pub use any::render_chain;
pub use category::Category;
pub use error::{DecodeError, EncodeError};
pub use exposure::Exposure;
pub use failure::ServiceFailure;
pub use frame::Frame;
pub use remote::RemoteError;
pub use trace::TraceContext;
pub use traits::Aerro;

#[cfg(feature = "macro")]
pub use aerro_macros::Aerro;

pub mod ext;
pub mod wire;

pub use ext::{ResultIntoStatusExt, StatusIntoResultExt};
pub use traits::{IntoStatus, TryFromStatus};
pub use wire::decode::decode;
pub use wire::encode::{EncodeOptions, encode};

#[cfg(test)]
mod tests {
    #[test]
    fn exposes_crate_version() {
        assert_eq!(crate::VERSION, env!("CARGO_PKG_VERSION"));
    }
}