eros

Eros is the swiss army knife of error handling approaches. It fits perfectly well into libraries and binaries.

Built on the following philosophy:

1. Error types only matter when the caller cares about the type, otherwise this just hinders ergonomics and creates unnecessary noise. Link
2. There should be no boilerplate needed when handling any number of typed errors - no need to create an error enum for each case. Link
3. Users should be able to seamlessly transition to and from fully typed errors. And handle any cases they care about. Link
4. Errors should always provided context of the operations in the call stack that lead to the error. Link
5. Error constructs should performant. Link

Philosophy In Action

Optional Typed Errors

Error types only matter when the caller cares about the type, otherwise this just hinders ergonomics and creates unnecessary noise. Thus, it should be easy for the developer to make the type opaque for developing fast composable apis. This is where TracedError helps.

use eros::{bail, TracedDyn};
use std::io::{Error, ErrorKind};

// The Error type is untracked and the underlying types are different.
// If one wanted to track the error this can be done - `eros::Result<(), _>`,
// since `eros::Result<()>` == `eros::Result<(), TracedError>`.
fn func1() -> eros::Result<()> {
    let val = func2()?;
    let val = func3()?;
    Ok(val)
}

fn func2() -> eros::Result<()> {
    bail!("Something went wrong")
}

fn func3() -> eros::Result<()> {
    return Err(Error::new(ErrorKind::AddrInUse, "message here")).traced_dyn();
}

fn main() {
    func1();
}

No Boilerplate

There should be no boilerplate needed when handling any number of typed error. This is where ErrorUnion helps.

use eros::{bail, Traced, IntoUnionResult, TE};
use std::io;

// Uses `ErrorUnion` to track each type. 
// `UnionResult<_,(..)>` == `Result<_,ErrorUnion<(..)>>`.
// Here `TracedError` remains untyped and `TracedError<Error>` is typed.
// `TE` is a type alias for `TracedError`.
fn func1() -> eros::UnionResult<(), (TE<io::Error>, TE)> {
    // Change the `eros::Result` type to an `UnionResult` type
    let val = func2().union()?; // TracedError
    let val = func3().union()?; // TracedError<Error>
    Ok(val)
}

// Error type not tracked
fn func2() -> eros::Result<()> {
    bail!("Something went wrong")
}

// Error type is tracked. Here the underlying error type is `std::io::Error`
fn func3() -> eros::Result<(), io::Error> {
    return Err(io::Error::new(io::ErrorKind::AddrInUse, "message here")).traced();
}

fn main() {
    func1();
}

The above code is precisely typed for what we care about and there was no need to create an error enum for each case.

UnionResult and the underlying UnionError, work with regular types as well, not just TracedError. Thus the error type could consist of non-traced errors as well. e.g.

fn func1() -> eros::UnionResult<(), (std::io::Error, my_crate::Error)>;

Seamless Transitions Between Error Types

Users should be able to seamlessly transition to and from fully typed errors. And handle any cases they care about.

use eros::{bail, ReshapeUnionResult, Traced, IntoUnionResult, TE};
use std::io;

fn func1() -> eros::UnionResult<(), (TE<io::Error>, TE)> {
    let val = func2().union()?;
    let val = func3().union()?;
    Ok(val)
}

fn func2() -> eros::Result<()> {
    bail!("Something went wrong")
}

fn func3() -> eros::Result<(), io::Error> {
    return Err(io::Error::new(io::ErrorKind::AddrInUse, "message here")).traced();
}

// Error type is no longer tracked, we handled internally.
fn func4() -> eros::Result<()> {
    // Narrow the `ErrorUnion` and handle to only handle `TracedError<Error>` case!
    match func1().narrow::<TE<io::Error>, _>() {
        Ok(traced_io_error) => {
            todo!("Handle `TracedError<std::io::Error>` case")
        }
        // The error type of the Result has been narrowed.
        // It is now a union with a single type (`ErrorUnion<(TracedError,)>`), 
        // thus we can convert into the inner traced type.
        // Note: Alternatively, we could just call `traced` on `result` to accomplish the same thing
        Err(result) => result.map_err(|e| e.into_inner()),
    }
}

fn main() {
    func4();
}

And to expand an ErrorUnion just call widen

use eros::{ReshapeUnionResult, IntoUnionResult};
use std::io;

fn func1() -> eros::UnionResult<(), (io::Error, String)> {
    Ok(())
}

fn func2() -> eros::UnionResult<(), (i32, u16)> {
    Ok(())
}

fn func3() -> Result<(), f64> {
    Ok(())
}

fn func4() -> eros::UnionResult<(), (io::Error, String, i32, u16, f64)> {
    func1().widen()?;
    func2().widen()?;
    func3().union()?;
    Ok(())
}

fn main() {
    func4();
}

Errors Have Context

Errors should always provided context of the operations in the call stack that lead to the error.

use eros::{
    bail, Context, IntoUnionResult, TE,
};
use std::io;

fn func1() -> eros::UnionResult<(), (TE<io::Error>, TE)> {
    let val = func2()
        .with_context(|| format!("This is some more context"))
        .union()?;
    let val = func3()
        .context("This is some more context")
        .union()?;
    Ok(val)
}

fn func2() -> eros::Result<()> {
    bail!("Something went wrong")
}

fn func3() -> eros::Result<()> {
    return Err(io::Error::new(io::ErrorKind::AddrInUse, "message here"))
        // Trace the `Err` without the type (`TracedError`)
        // Note: Calling `.traced_dyn()` not needed. we can call `context` directly
        // .traced_dyn()
        .context("This is some context");
}

fn main() {
    // Can add context to `ErrorUnion` when the `min_specialization` feature flag is enabled
    // let out = func1().context("Last bit of context").unwrap_err();
    let out = func1();
    println!("{out:#?}");
}

Something went wrong

Context:
        - This is some more context
        - Last bit of context

Backtrace:
   0:     0x5561eb054735 - std::backtrace_rs::backtrace::libunwind::trace::hc389a5f23f39a50d
                               at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/../../backtrace/src/backtrace/libunwind.rs:117:9
   1:     0x5561eb054735 - std::backtrace_rs::backtrace::trace_unsynchronized::h6eca87dcd6d323d8
                               at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/../../backtrace/src/backtrace/mod.rs:66:14
   2:     0x5561eb054735 - std::backtrace::Backtrace::create::h1c21bf982658ba83
                               at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/backtrace.rs:331:13
   3:     0x5561eb054685 - std::backtrace::Backtrace::force_capture::h09cde9fcccebf215
                               at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/backtrace.rs:312:9
   4:     0x5561eb02e4e2 - eros::generic_error::TracedError<T>::new::h41e2123d6cf4fdd5
                               at /workspaces/eros/src/generic_error.rs:36:24
   5:     0x5561eafe8246 - x::func2::hc5bcba8eff1a9abd
                               at /workspaces/eros/tests/x.rs:17:5
   6:     0x5561eafe7f19 - x::func1::hc86226443a9fa2c0
                               at /workspaces/eros/tests/x.rs:7:15
   7:     0x5561eafe82dc - x::main::h6b82c0c63f51d406
                               at /workspaces/eros/tests/x.rs:28:15
...

Optimizations

Eros comes with the context and backtrace feature flags enabled by default. If this is disabled, backtrace and context tracking are removed from TracedError and all context methods become a no-opt. Thus, TracedError becomes a new type and may be optimized away by the compiler.

Additionally in this case, TracedError has the same effect as Box. Boxing errors is a common trick to increase performance and decrease memory usage in many cases. This is because boxing may decrease the size of the return type, e.g. Result<(),Box<u128>> is smaller than Result<(),u128>>.

See the Use In Libraries section as well.

Putting It All Together

use eros::{
    bail, Context, ReshapeUnionResult, Traced, TracedDyn, IntoUnionResult,
    TE,
};
use reqwest::blocking::{Client, Response};
use std::thread::sleep;
use std::time::Duration;

// Add tracing to an error by wrapping it in a `TracedError`.
// When we don't care about the error type we can use `eros::Result<_>` which has tracing.
// `eros::Result<_>` == `Result<_,TracedError>` == `TracedResult<_>`
// When we *do* care about the error type we can use `eros::Result<_,_>` which also has tracing but preserves the error type.
// `eros::Result<_,_>` == `Result<_,TracedError<_>>` == `TracedResult<_,_>`
// In the below example we don't preserve the error type.
fn handle_response(res: Response) -> eros::Result<String> {
    if !res.status().is_success() {
        // `bail!` to directly bail with the error message.
        // See `traced!` to create a `TracedError` without bailing.
        bail!("Bad response: {}", res.status());
    }

    let body = res
        .text()
        // Trace the `Err` without the type (`TracedError`)
        // Note: Calling `.traced_dyn()` not needed. we can call `context` directly
        // .traced_dyn()
        // Add context to the traced error if an `Err`
        .context("while reading response body")?;
    Ok(body)
}

// Explicitly handle multiple Err types at the same time with `UnionResult`.
// No new error enum creation is needed or nesting of errors.
// `UnionResult<_,_>` == `Result<_,ErrorUnion<_>>`
fn fetch_url(url: &str) -> eros::UnionResult<String, (TE<reqwest::Error>, TE)> {
    let client = Client::new();

    let res = client
        .get(url)
        .send()
        // Explicitly trace the `Err` with the type (`TracedError<reqwest::Error>`)
        .traced()
        // Add lazy context to the traced error if an `Err`
        .with_context(|| format!("Url: {url}"))
        // Convert the `TracedError<reqwest::Error>` into a `UnionError<_>`.
        // If this type was already a `UnionError`, we would call `widen` instead.
        .union()?;

    handle_response(res).union()
}

fn fetch_with_retry(url: &str, retries: usize) -> eros::Result<String> {
    let mut attempts = 0;

    loop {
        attempts += 1;

        // Handle one of the error types explicitly with `narrow`!
        match fetch_url(url).narrow::<TE<reqwest::Error>, _>() {
            Ok(request_error) => {
                if attempts < retries {
                    sleep(Duration::from_millis(200));
                    continue;
                } else {
                    return Err(request_error.traced_dyn().context("Retries exceeded"));
                }
            }
            // `result` is now `UnionResult<String,(TracedError,)>`, so we convert the `Err` type
            // into `TracedError`. Thus, we now have a `Result<String,TracedError>`.
            Err(result) => return result.map_err(|e| e.into_inner()),
        }
    }
}

fn main() {
    match fetch_with_retry("https://badurl214651523152316hng.com", 3).context("Fetch failed") {
        Ok(body) => println!("Ok Body:\n{body}"),
        Err(err) => eprintln!("Error:\n{err:?}"),
    }
}

Output:

Error:
error sending request

Context:
        - Url: https://badurl214651523152316hng.com
        - Retries exceeded
        - Fetch failed

Backtrace:
   0: eros::generic_error::TracedError<T>::new
             at ./src/generic_error.rs:47:24
   1: <E as eros::generic_error::Traced<eros::generic_error::TracedError<E>>>::traced
             at ./src/generic_error.rs:211:9
   2: <core::result::Result<S,E> as eros::generic_error::Traced<core::result::Result<S,eros::generic_error::TracedError<E>>>>::traced::{{closure}}
             at ./src/generic_error.rs:235:28
   3: core::result::Result<T,E>::map_err
             at /usr/local/rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/result.rs:914:27
   4: <core::result::Result<S,E> as eros::generic_error::Traced<core::result::Result<S,eros::generic_error::TracedError<E>>>>::traced
             at ./src/generic_error.rs:235:14
   5: x::fetch_url
             at ./tests/x.rs:39:10
   6: x::fetch_with_retry
             at ./tests/x.rs:56:15
   7: x::main
             at ./tests/x.rs:74:11
...

TracedError

TracedError (type alias TE) allows adding context to an error throughout the callstack with the context or with_context methods. This context may be information such as variable values or ongoing operations while the error occurred. If the error is handled higher in the stack, then this can be disregarded (no log pollution). Otherwise you can log it (or panic), capturing all the relevant information in one log. A backtrace is captured and added to the log if RUST_BACKTRACE is set. Use TracedError if the underlying error type does not matter. Otherwise, the type can be specified with TracedError<T>.

ErrorUnion

ErrorUnion is an open sum type. It differs from an enum in that you do not need to define any actual new type in order to hold some specific combination of variants, but rather you simply describe the ErrorUnion as holding one value out of several specific possibilities, defined by using a tuple of those possible variants as the generic parameter for the ErrorUnion.

For example, a ErrorUnion<(String, u32)> contains either a String or a u32. The benefit of this over creating specific enums for each function become apparent in larger codebases where error handling needs to occur in different places for different errors. As such, ErrorUnion allows you to quickly specify a function's return value as involving a precise subset of errors that the caller can clearly reason about. Providing maximum composability with no boilerplate.

Use In Libraries

eros's flexibility and optimizations make it a the perfect option for both libraries and binaries.

Libraries should consider disabling default features and allowing downstream crates to enable this. This can then be enabled for tests only in the library.

Suggested Route

Exposing TracedError, or ErrorUnion in a public api is perfectly fine and usually preferred. It allows multiple crates to use the power of these constructs together. see the Optimizations section for more info. Just make sure to re-export these constructs if exposed.

Alternatives

Wrapper Error Types

An alternative to exposing TracedError is a wrapper type like a new type - MyErrorType(TracedError). If such a route is taken, consider implementing Deref/DerefMut. That way, a downstream can also add additional context. Additionally/alternatively, consider adding an into_traced method as a way to to convert to the underlying TracedError. That way, if a downstream uses Eros they can get the TracedError rather than wrapping it in another TracedError.

The downside is wrapping/nesting TracedError may still unintentionally occur, that is why exposing the TracedError in the api is usually preferred, since TracedError cannot be nested within itself. Additionally the into_traced api can no longer be used across api boundaries (example) which limits composability.

Non-Wrapper Error Types

If one wants to add their own custom error type for all public api's without exposing constructs like TracedError, use the into_inner method at these boundaries.

use eros::{AnyError, TracedError};

#[derive(Debug)]
struct MyErrorType(Box<dyn AnyError>);

impl std::fmt::Display for MyErrorType {
    fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(fmt, "MyErrorType: {}", self.0)
    }
}

impl std::error::Error for MyErrorType {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.0)
    }
}

fn internal_api() -> eros::Result<()> {
    Err(TracedError::boxed(std::io::Error::new(std::io::ErrorKind::Other, "io error")))
}

pub fn public_api() -> Result<(), MyErrorType> {
    // Replace `TracedError` with your custom error type
    internal_api().map_err(|e| MyErrorType(e.into_inner()))
}

Special Thanks

Special thank you to the authors and contributors of the following crates that inspired eros:

• anyhow
• terrors
• error_set
• thiserror