Crate 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

Modules

formatter

global

prelude

result

span

subscriber

Macros

err

Shorthand macro for Result::Err in order to create an error context from a related enum or struct type.

formatter

Sets a global formatter for errors.

subscriber

Registers an error subscriber. Multiple subscribers can be submitted.

Structs

Downcasted

A construct to represent a reference to a downcasted error.

Extensions

An immutable, read-only reference to a Context’s extensions.

ExtensionsMut

An mutable reference to a Context’s extensions.

Id

Represents an identifier hash.

Location

A struct containing information about the location of the caller.

TraceContext

A context for holding data used for error tracing.

TraceContextBuilder

This builder allows to configure an TraceContext object.

TraceRecord

The record represents an entity where an error was created, propagated or converted in the error chain.

Traits

Extension

Marks an object as extendable with user supplied extensions.

Extract

Provides access to the trace context for an object.

Extractable

Marker trait for extractable errors.

Metadata

Defines the metadata for an error type.

TraceAccess

Interface to interact with the collected traces.

Traceable

Interface to implement tracing related functionality.

Derive Macros

Display

The display derive macro implements only a simple Display trait with an empty Error trait.

Error