Crate erra 

erra

A lightweight, no_std-compatible library for adding call-site context to Result<T, E> without erasing or boxing the underlying error type.

Motivation

Rust’s ? operator is great at propagating errors, but it does not preserve much context about the path that led there. If a production service surfaces something like Os { code: 2, kind: NotFound }, you know what failed, but not which operation triggered it or what the code was trying to do at the time.

The usual ways of adding context all involve trade-offs:

• map_err with format! is repetitive, allocates eagerly, and usually collapses a structured error into a String.
• anyhow and eyre are a good fit for applications, but they erase the concrete error type behind dyn Error, which makes them a weaker fit for library APIs that want to preserve typed errors.
• thiserror works well for defining boundary error types, but it is too heavy for routine call-site annotation inside a module or subsystem.

erra sits in the middle: it lets you attach context where the error happens while keeping the original error type available for matching and propagation. On the Ok path, it adds no allocation overhead.

Quick start

Bring ResultExt into scope to annotate any Result<T, E>:

use erra::ResultExt;
use std::fs;

fn load_config(path: &str) -> core::result::Result<String, erra::Error<std::io::Error>> {
    fs::read_to_string(path)
        .annotate("failed to read application config layout")
}

If you prefer shorter signatures, use the crate’s Result alias:

use erra::{Result, ResultExt};
use std::fs;

fn load_config(path: &str) -> Result<String, std::io::Error> {
    fs::read_to_string(path)
        .annotate("failed to read application config layout")
}

For dynamic messages, use ResultExt::annotate_with. The closure runs only on the Err path:

use erra::{Result, ResultExt};

fn fetch_data(id: u64) -> Result<Vec<u8>, std::io::Error> {
    std::fs::read(format!("/data/{id}"))
        .annotate_with(|| format!("failed to pull record for id={id}"))
}

Inspecting errors

erra::Error<E> preserves the concrete type E, so callers can inspect the wrapped error directly without downcasting:

use erra::{Result, ResultExt};
use std::io;

fn run() -> Result<(), io::Error> {
    std::fs::read_to_string("missing.toml").annotate("reading setup file")?;
    Ok(())
}

if let Err(err) = run() {
    match err.source.kind() {
        io::ErrorKind::NotFound => println!("file was missing"),
        _ => eprintln!("system error: {err}"),
    }
}

Nested context

Annotations compose naturally. Multiple layers of .annotate() produce nested wrappers such as Error<Error<E>>.

With std enabled, std::error::Error::source walks that chain in the usual way, so generic reporters and logging infrastructure can traverse it without any special integration.

Design notes

No From<E>

erra deliberately does not implement From<E> for Error<E>. If it did, the ? operator could wrap errors implicitly without adding any message, which would defeat the purpose of explicit call-site annotation.

Display and source()

Display is meant for people: it formats the error as a readable outer-to- inner message chain, such as "outer context: inner context: underlying error".

source() is meant for tools: it exposes the wrapped error through the standard error-chain interface.

Feature flags

• std (default): implements std::error::Error for Error<E>. Implies alloc.
• alloc: enables owned context strings and ResultExt::annotate_with.

With default-features = false, erra still works in no_std builds using static string context only.

Modules

prelude

The erra prelude.

Structs

Error

An error type that pairs a concrete error with a context string.

Traits

ResultExt

Adds context to Result<T, E>.

Type Aliases

Result

Shorthand for core::result::Result<T, erra::Error<E>>.