reportable 0.1.5

Classify errors for internal reporting or delivery to the caller
Documentation
# reportable

Declare who should receive an error's diagnostic details: your operators or the caller.

`reportable` provides `ReportTo`, the `Reportable` trait, and a derive macro for error
structs and nested error enums. It works alongside `thiserror` and does not depend on a logging framework,
HTTP library, or error tracker. The runtime crate supports `no_std` without allocation.

## Installation

Requires Rust 1.85 or later. Add `reportable = "0.1"` to your dependencies.
The derive macro is included. `thiserror = "2"` is optional and used in the example below.

## Usage

```rust
use reportable::{ReportTo, Reportable};

#[derive(Debug, thiserror::Error, Reportable)]
enum RepositoryError {
    #[error("Record not found")]
    #[reportable(caller)]
    NotFound,

    #[error("Database unavailable")]
    #[reportable(internal)]
    Unavailable,
}

#[derive(Debug, thiserror::Error, Reportable)]
enum UpdateError {
    #[error("Invalid input: {0}")]
    #[reportable(caller)]
    InvalidInput(String),

    #[error(transparent)]
    #[reportable(transparent)]
    Repository(#[from] RepositoryError),

    #[error("Required record missing: {0}")]
    #[reportable(internal)]
    Invariant(RepositoryError),
}

let error = UpdateError::from(RepositoryError::NotFound);
assert_eq!(error.report_to(), ReportTo::Caller);

let error = UpdateError::Invariant(RepositoryError::NotFound);
assert_eq!(error.report_to(), ReportTo::Internal);
```

## Classification rules

- `#[reportable(caller)]`: an expected failure for the caller to handle.
- `#[reportable(internal)]`: a failure for operators to investigate.
- `#[reportable(transparent)]`: delegate to the wrapped field's `Reportable` implementation.

Every variant needs exactly one annotation, either directly or inherited from an enum-level
annotation. A variant-level annotation overrides the enum-level one:

```rust
use reportable::Reportable;

#[derive(Reportable)]
#[reportable(caller)]
enum Thing {
    A, // caller
    #[reportable(internal)]
    B, // internal
}
```

A struct takes a single type-level annotation:

```rust
use reportable::Reportable;

#[derive(Debug, thiserror::Error, Reportable)]
#[error("Could not load the \"{0}\" integration configuration: {1}")]
#[reportable(caller)]
pub struct ConfigLoadError(&'static str, std::io::Error);
```

Explicit classifications accept unit, tuple, and named-field structs and variants and do not require
their fields to implement `Reportable`. Transparent structs and variants require exactly one field,
named or unnamed, whose type implements `Reportable`. Generic bounds are generated for
delegated field types. References to `Reportable` values also implement the trait.

Classification describes the destination of diagnostic details. An internal failure can
still return a generic error response to the caller. HTTP status and retry behavior are
separate decisions. A parent can explicitly classify a wrapped error differently when
its context changes the meaning of that failure.

Implement `Reportable` manually if the destination depends on a field's value.
The trait does not require `std::error::Error`.

## Reporting with tracing and Sentry

The application owns reporting. With `tracing` and `sentry-tracing`, classify the typed
error before passing it to the logging framework:

```rust,ignore
use reportable::{ReportTo, Reportable};
use std::error::Error;

fn report_error<E: Error + Reportable + 'static>(error: &E) {
    match error.report_to() {
        ReportTo::Caller => tracing::info!(error = %error),
        ReportTo::Internal => tracing::error!(error = error as &dyn Error),
    }
}
```

The [Sentry tracing layer](https://docs.rs/sentry-tracing/latest/sentry_tracing/)
captures `ERROR` events by default; expected errors logged at
`INFO` do not create issues. They may become breadcrumbs depending on layer configuration.
Passing `&dyn Error` preserves the error's source chain.

Call this once where an operation finishes: an Actix `ResponseError::error_response`
implementation or a worker's job handler. Lower layers should return errors without also
reporting them. Avoid a second capture through `#[instrument(err)]`, middleware, or
`sentry::capture_error` on the same path. Retry policy belongs to the application.

## Compile-time checks

An unclassified variant is rejected:

```rust,compile_fail
use reportable::Reportable;

#[derive(Reportable)]
enum Error {
    Unclassified,
}
```

Delegation requires a `Reportable` field:

```rust,compile_fail
use reportable::Reportable;

#[derive(Reportable)]
enum Error {
    #[reportable(transparent)]
    Foreign(std::io::Error),
}
```

Transparent variants cannot silently select one of several fields:

```rust,compile_fail
use reportable::Reportable;

#[derive(Reportable)]
enum Error {
    #[reportable(transparent)]
    Ambiguous(u8, u8),
}
```

## Development

```sh
cargo test --workspace --locked
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo doc --workspace --no-deps --locked
```

CI tests stable Rust and Rust 1.85, checks a target without `std`, and verifies both crate archives.

## License

MIT.