Errore

This library provides a framework to handle and trace errors across modules and crates.

At the moment errore is in development and breaking changes are to be expected.

Example

At first glance, errore its error definition looks quite similar to thiserror`s:

use errore::prelude::*;

use crate::auth;

/// Errors for account related operations.
#[derive(Error, Debug)]
pub enum Error {
    #[error(transparent)]
    Authentication(#[from] auth::Ec),
    #[error("Submitted captcha '{hash}' is wrong")]
    WrongCaptcha { hash: String },
    #[error("Captcha session '{session}' was not found or is expired")]
    InvalidCaptcha { session: String },
}

// Automatically generated:
// pub struct Ec(pub Span<Error>)

pub fn login(email: &str, password: &str) -> Result<(), Ec> {
    auth::verify(email, password)?;
    // errors can also be defined without err!() macro
    Err(Ec::new(Error::WrongCaptcha {
        hash: "abc123".into(),
    }))
}

However, it is possible to extract additional information from the error, as shown in this sample error output:

Error: example_basic::account::Authentication
├─▶ <example_basic::auth::ReadPassword> Invalid email or password
│   ├╴ examples/basic/src/auth.rs:20:8
│   ╰╴ examples/basic/src/auth.rs:24:8
│
╰─▶ <example_basic::account::Authentication>
    ╰╴ examples/basic/src/account.rs:20:5

Trace records:
<example_basic::auth::ReadPassword> Invalid email or password at examples/basic/src/auth.rs:20:8
<example_basic::auth::ReadPassword> Invalid email or password at examples/basic/src/auth.rs:24:8
<example_basic::account::Authentication> Invalid email or password at examples/basic/src/account.rs:20:5

Error display:
example_basic::account::Authentication: Invalid email or password
    at examples/basic/src/auth.rs:20:8

Error extraction with 'match':
OS error code 2: entity not found

Error extraction with 'get()':
OS error code 2: entity not found

The complete example can be seen here. For other examples please see here.

Features

Tracing capability with rich metadata such as file location and line number without backtrace
Generates trait implementations for metadata and error conversion
Customizable Subscriber and Formatter interface
Support for user attached data with Extensions at subscriber
Partial API compatibility with thiserror that allows to optionally enable errore in public distributed libraries on stable rust. See example
Usable in application and library code
no-std support & wasmcompatible

Limitations & Disadvantages

Invasive code changes with Result instrumentation are required
Nightly compiler is required
Only one error per module can be defined
No recursive or self-referencing fields
Error conversion with attribute macro #from requires a trait implementation of std::error::Error for the type
Generics with traits in error fields need to be declared with the where keyword
Some edge cases cannot be expressed with generics (for e.g. nesting)
No anyhow support (shouldn't be a problem if errore is used)

Recommendations

For public libraries an optional feature flag for errore is advisable. For the best results thiserror should be used. See Example
For private libraries errore can be used as is. Errors can be declared on a per module basis or as one global type. See Example
For general best-practices with errore the various examples can serve as a good foundation

Feature flags

ctor: Utilizes link_sections provided by the ctor and inventory crates to offer a better implementation of the metadata and subscriber relevant code. The fallback implementation is based on lazy static variables. This feature can be disabled at no-std projects on build failures.
debug-no-std: Enables internal logging with the defmt crate to debug errore itself.
debug-std: Enables internal logging with the log crate to debug errore itself.
std: Enables standard library support. If the std feature is not enabled, the alloc crate is required.

Thanks to

@dtolnay - Maintainer of several great crates including thiserror which is used as errore`s foundation
tracing / error-stack / error_set maintainers & contributors for the inspiring codebase and ideas