Eros is the swiss army knife of error handling approaches. It fits perfectly well into libraries and applications. Eros is heavily inspired by:
Eros is built on the following philosophy:
- Error types only matter when the caller cares about the type, otherwise this just hinders ergonomics and creates unnecessary noise.
- There should be no boilerplate needed when handling single or multiple typed errors - no need to create another error enum
- Users should be able to seamlessly transition to and from fully typed errors.
- Errors should always provided context of the operations in the call stack that lead to the error.
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.
use eros::{bail, IntoDynTracedError};
use std::io::{Error, ErrorKind};
// The Error type is untracked and the underlying types are different
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();
}There should be no boilerplate needed when handling single or multiple typed error.
use eros::{bail, IntoConcreteTracedError, IntoUnionResult, TracedError};
use std::io::{Error, ErrorKind};
// Uses `ErrorUnion` to track each type. `TracedError` remains untyped and
// `TracedError<Error>` is typed.
fn func1() -> eros::UnionResult<(), (TracedError<Error>, TracedError)> {
// widen the `TracedResult` type to an `UnionResult` type
let val = func2().union()?;
let val = func3().union()?;
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<(), Error> {
return Err(Error::new(ErrorKind::AddrInUse, "message here")).traced();
}
fn main() {
func1();
}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)>;Users should be able to seamlessly transition to and from fully typed errors.
use eros::{bail, ReshapeUnionResult, IntoConcreteTracedError, IntoUnionResult, TracedError};
use std::io::{Error, ErrorKind};
fn func1() -> eros::UnionResult<(), (TracedError<Error>, TracedError)> {
let val = func2().union()?;
let val = func3().union()?;
Ok(val)
}
fn func2() -> eros::Result<()> {
bail!("Something went wrong")
}
fn func3() -> eros::Result<(), Error> {
return Err(Error::new(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::<TracedError<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::Error;
fn func1() -> eros::UnionResult<(), (Error, String)> {
Ok(())
}
fn func2() -> eros::UnionResult<(), (i32, u16)> {
Ok(())
}
fn func3() -> Result<(), f64> {
Ok(())
}
fn func4() -> eros::UnionResult<(), (Error, String, i32, u16, f64)> {
func1().widen()?;
func2().widen()?;
func3().union()?;
Ok(())
}
fn main() {
func4();
}Errors should always provided context of the operations in the call stack that lead to the error.
use eros::{
bail, Context, IntoUnionResult, TracedError,
};
use std::io::{Error, ErrorKind};
fn func1() -> eros::UnionResult<(), (TracedError<Error>, TracedError)> {
let val = func2()
.with_context(|| format!("This is some more context"))
.union()?;
let val = func3()
.context(format!("This is some more context"))
.union()?;
Ok(val)
}
fn func2() -> eros::Result<()> {
bail!("Something went wrong")
}
fn func3() -> eros::Result<()> {
return Err(Error::new(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
8: 0x5561eafea397 - x::main::{{closure}}::h9ec95e65e08ea0a5
at /workspaces/eros/tests/x.rs:27:10
9: 0x5561eafe6bc6 - core::ops::function::FnOnce::call_once::h89665ff874f9aff0
at /usr/local/rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/function.rs:253:5
10: 0x5561eb02945b - core::ops::function::FnOnce::call_once::he7780dbaf3819be9
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/ops/function.rs:253:5
11: 0x5561eb02945b - test::__rust_begin_short_backtrace::he52f6244ba5ffadb
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:648:18
12: 0x5561eb02862e - test::run_test_in_process::{{closure}}::h4b5580962b2f03a8
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:671:74
13: 0x5561eb02862e - <core::panic::unwind_safe::AssertUnwindSafe<F> as core::ops::function::FnOnce<()>>::call_once::h19cb5d2621bd88eb
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/panic/unwind_safe.rs:272:9
14: 0x5561eb02862e - std::panicking::catch_unwind::do_call::hea0162f6125d4c37
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:589:40
15: 0x5561eb02862e - std::panicking::catch_unwind::h58eff26629cdc5e5
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:552:19
16: 0x5561eb02862e - std::panic::catch_unwind::haee4559c8279658f
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panic.rs:359:14
17: 0x5561eb02862e - test::run_test_in_process::hd400bd155f277427
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:671:27
18: 0x5561eb02862e - test::run_test::{{closure}}::h0d9903d185102994
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:592:43
19: 0x5561eafec3a4 - test::run_test::{{closure}}::hc4b5b0598a6862e8
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:622:41
20: 0x5561eafec3a4 - std::sys::backtrace::__rust_begin_short_backtrace::ha7ee3160b6c13598
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/sys/backtrace.rs:158:18
21: 0x5561eafefc6a - std::thread::Builder::spawn_unchecked_::{{closure}}::{{closure}}::hbaba1875801144df
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/thread/mod.rs:559:17
22: 0x5561eafefc6a - <core::panic::unwind_safe::AssertUnwindSafe<F> as core::ops::function::FnOnce<()>>::call_once::heb48e77784f0385f
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/panic/unwind_safe.rs:272:9
23: 0x5561eafefc6a - std::panicking::catch_unwind::do_call::he0ffef791c49aaef
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:589:40
24: 0x5561eafefc6a - std::panicking::catch_unwind::h99d55591c3b90bdb
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:552:19
25: 0x5561eafefc6a - std::panic::catch_unwind::h4ea92e4fa0439888
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panic.rs:359:14
26: 0x5561eafefc6a - std::thread::Builder::spawn_unchecked_::{{closure}}::h03c8861180b28db2
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/thread/mod.rs:557:30
27: 0x5561eafefc6a - core::ops::function::FnOnce::call_once{{vtable.shim}}::h00b23c1a00a0e90a
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/ops/function.rs:253:5
28: 0x5561eb0619d7 - <alloc::boxed::Box<F,A> as core::ops::function::FnOnce<Args>>::call_once::hcd81d65010c14a3e
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/alloc/src/boxed.rs:1971:9
29: 0x5561eb0619d7 - <alloc::boxed::Box<F,A> as core::ops::function::FnOnce<Args>>::call_once::h96a52a5b098b326a
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/alloc/src/boxed.rs:1971:9
30: 0x5561eb0619d7 - std::sys::pal::unix::thread::Thread::new::thread_start::hd5dce28806973ef9
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/sys/pal/unix/thread.rs:97:17
31: 0x7f20d33eaaa4 - <unknown>
32: 0x7f20d3477c3c - <unknown>
33: 0x0 - <unknown>use eros::{
bail, Context, ReshapeUnionResult, IntoConcreteTracedError, IntoDynTracedError, IntoUnionResult,
TracedError,
};
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, (TracedError<reqwest::Error>, TracedError)> {
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::<TracedError<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::IntoConcreteTracedError<eros::generic_error::TracedError<E>>>::traced
at ./src/generic_error.rs:211:9
2: <core::result::Result<S,E> as eros::generic_error::IntoConcreteTracedError<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::IntoConcreteTracedError<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
8: x::main::{{closure}}
at ./tests/x.rs:73:10
9: core::ops::function::FnOnce::call_once
at /usr/local/rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/function.rs:253:5
10: core::ops::function::FnOnce::call_once
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/ops/function.rs:253:5
11: test::__rust_begin_short_backtrace
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:648:18
12: test::run_test_in_process::{{closure}}
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:671:74
13: <core::panic::unwind_safe::AssertUnwindSafe<F> as core::ops::function::FnOnce<()>>::call_once
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/panic/unwind_safe.rs:272:9
14: std::panicking::catch_unwind::do_call
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:589:40
15: std::panicking::catch_unwind
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:552:19
16: std::panic::catch_unwind
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panic.rs:359:14
17: test::run_test_in_process
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:671:27
18: test::run_test::{{closure}}
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:592:43
19: test::run_test::{{closure}}
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/test/src/lib.rs:622:41
20: std::sys::backtrace::__rust_begin_short_backtrace
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/sys/backtrace.rs:158:18
21: std::thread::Builder::spawn_unchecked_::{{closure}}::{{closure}}
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/thread/mod.rs:559:17
22: <core::panic::unwind_safe::AssertUnwindSafe<F> as core::ops::function::FnOnce<()>>::call_once
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/panic/unwind_safe.rs:272:9
23: std::panicking::catch_unwind::do_call
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:589:40
24: std::panicking::catch_unwind
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panicking.rs:552:19
25: std::panic::catch_unwind
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/panic.rs:359:14
26: std::thread::Builder::spawn_unchecked_::{{closure}}
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/thread/mod.rs:557:30
27: core::ops::function::FnOnce::call_once{{vtable.shim}}
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/core/src/ops/function.rs:253:5
28: <alloc::boxed::Box<F,A> as core::ops::function::FnOnce<Args>>::call_once
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/alloc/src/boxed.rs:1971:9
29: <alloc::boxed::Box<F,A> as core::ops::function::FnOnce<Args>>::call_once
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/alloc/src/boxed.rs:1971:9
30: std::sys::pal::unix::thread::Thread::new::thread_start
at /rustc/8f08b3a32478b8d0507732800ecb548a76e0fd0c/library/std/src/sys/pal/unix/thread.rs:97:17
31: <unknown>
32: <unknown>TracedError 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>.
Eros is perfect for libraries and applications. It is also optimized for binary size and performance.
Eros comes with the traced feature flag 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. Libraries should consider disabling this by default and allowing downstream crates to enable this. This can also be disabled when attempting to optimize the binary in release mode.
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. Though, if one wants to add their own custom error type for all public api's, use the map 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)
}
}
pub fn public_api() -> eros::Result<(), MyErrorType> {
let error: TracedError =
TracedError::boxed(std::io::Error::new(std::io::ErrorKind::Other, "io error"));
let error: TracedError<MyErrorType> = error.map(MyErrorType);
Err(error)
}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. But 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.
If one does not want to expose any tracing details of the library and only use TracedError internally for testing, they should by default disable the traced feature flag so all tracing operations become a no opt. This can then be enabled for tests only. Then at the api boundary one can easily just call into_inner to get the inner T in TracedError<T>. Thus no constructs of this library will be exposed to downstream crates and there is no performance impact.