aerro 0.6.4

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
91
92
93
94

# aerro

[![Crates.io](https://img.shields.io/crates/v/aerro.svg)](https://crates.io/crates/aerro)
[![docs.rs](https://img.shields.io/docsrs/aerro)](https://docs.rs/aerro)
[![CI](https://github.com/ae2rs/aerro/actions/workflows/ci.yml/badge.svg)](https://github.com/ae2rs/aerro/actions/workflows/ci.yml)
[![License](https://img.shields.io/crates/l/aerro.svg)](LICENSE-MIT)

Cross-service gRPC error framework for Rust.

`aerro` gives every error a **typed identity**, a **bounded call trace**, and a
**structured wire encoding** — so the client that receives a `tonic::Status` can
recover the original variant, read the chain of service hops it passed through,
and decide whether to surface the message to the end user.

## Features

- **Typed errors** — derive `Aerro` on any enum; each variant carries a category,
  gRPC status code, and structured message template
- **Bounded call traces** — every hop appends a `Frame`; frames are elided to a
  configurable cap on the wire so large fan-outs stay bounded
- **Exposure control** — `Internal`, `Trusted`, and `Public` tiers redact system
  errors and strip call traces automatically at the egress point
- **Zero allocations on the happy path** — no heap work when there is no error

## Quick Start

Add `aerro` to your `Cargo.toml`:

```toml
[dependencies]
aerro = "0.2"
```

Define your errors, encode them into a `tonic::Status`, and recover them on the
other side:

```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 — convert a typed failure to a tonic::Status.
let err = CreateUserError::EmailTaken { email: "alice@example.com".into() };
let status = err.into_status(&EncodeOptions::default());

// Client side — recover the original typed variant.
let recovered = status.into_aerro::<CreateUserError>().unwrap();
```

## Examples

| Example | What it shows |
|---------|---------------|
| [`basic`](crates/aerro/examples/basic.rs) | Minimum viable usage — one enum, one wire round-trip |
| [`trace_chain`](crates/aerro/examples/trace_chain.rs) | 3-hop trace accumulation across service boundaries |
| [`exposure`](crates/aerro/examples/exposure.rs) | `Internal` / `Trusted` / `Public` redaction tiers |

Run any example with:

```
cargo run --example basic --features macro
```

## Feature Flags

| Flag | Default | Description |
|------|---------|-------------|
| `macro` | ✓ | `#[derive(Aerro)]` proc-macro |
| `tracing` | ✓ | Capture OTel trace/span IDs from the active `tracing` span |

## Status

**Alpha.** The core wire format and derive macros are functional and the API is
stabilising, but has not yet been used in production. Expect minor breaking
changes in the 0.x series.

Feedback, issues, and PRs are welcome.

## License

Licensed under either of:

- [Apache License, Version 2.0](LICENSE-APACHE)
- [MIT license](LICENSE-MIT)

at your option.