Crate ohno

Expand description

High-quality error handling for Rust.

Ohno combines error wrapping, enrichment messages stacking, backtrace capture, and procedural macros into one ergonomic crate for comprehensive error handling.

§Key Features

#[derive(Error)]: Derive macro for automatic std::error::Error, Display, Debug implementations
#[error]: Attribute macro for creating error types
#[enrich_err("...")]: Attribute macro for automatic error enrichment with file and line information.
ErrorExt: Trait that provides additional methods for ohno error types, it’s implemented automatically for all ohno error types
OhnoCore: Core error type that wraps source errors, captures backtraces, and holds enrichment entries
AppError: Application-level error type for general application errors

§Quick Start

use std::path::{Path, PathBuf};

#[ohno::error]
pub struct ConfigError(PathBuf);

#[ohno::enrich_err("failed to open file {}", path.as_ref().display())]
fn open_file(path: impl AsRef<Path>) -> Result<String, ConfigError> {
    std::fs::read_to_string(path.as_ref())
        .map_err(|e| ConfigError::caused_by(path.as_ref().to_path_buf(), e))
}

§Derive Macro

Derive macro for automatically implementing error traits.

When applied to a struct containing an OhnoCore field, this macro automatically implements std::error::Error, std::fmt::Display, std::fmt::Debug, and From conversions.

Note: From<std::convert::Infallible> is implemented by default and calls via unreachable! macro.

use ohno::{Error, OhnoCore};

#[derive(Error)]
pub struct MyError {
    inner_error: OhnoCore,
}

§`ohno::error`

The #[ohno::error] attribute macro is a convenience wrapper that automatically adds a OhnoCore field to the struct and applies #[derive(Error)]. This is the simplest way to create error types without manually managing the error infrastructure.

The attribute always adds that field and always generates the error representation from it, so no field may be marked with #[error]. Remove the marker to keep the field as data, or use #[derive(Error)] directly to place the core by hand.

A field of type OhnoCore may still be declared, and is then treated as data rather than as the error: it is passed to the generated constructors like any other field, appears in the generated Debug, and can be referenced from a #[display(...)] template — but it is never read for source(), the backtrace, or enrichment, which all come from the injected field.

// Simple error without extra fields
#[ohno::error]
pub struct ParseError;

// Error with multiple fields
#[ohno::error]
pub struct NetworkError {
    host: String,
    port: u16,
}

§How error text is rendered

Without a #[display("...")] attribute, the text an error renders depends on whether it has a cause — an error or a string handed to caused_by.

With a cause, the cause’s message is printed as it stands: no type name, and no caused by: line, so the wrapper leaves no trace in the message line. Enrichment and a backtrace, described below, are still written after it. A cause that is an error also stays in the source() chain, so a caller that walks the chain still finds it.

use std::io;

#[ohno::error]
pub struct ConfigError;

fn read_config() -> Result<String, ConfigError> {
    Err(ConfigError::caused_by(io::Error::new(
        io::ErrorKind::NotFound,
        "no such file: /etc/app.toml",
    )))
}

let error = read_config().unwrap_err();

println!("{error}");
// Output: no such file: /etc/app.toml

A cause given as a string renders the same way, but it does not join the chain: it is a message rather than an error, so source() returns None for it.

Wrapping therefore adds nothing to the text. A wrapper that should say what it was attempting — “failed to load the configuration”, say — has to be given a template; see Overriding error text.

Without a cause, there is no message to pass through, so the type’s own name is printed:

#[ohno::error]
pub struct ConfigError;

let error = ConfigError::new();

println!("{error}");
// Output: ConfigError

That is a symbol, not an explanation, so an error that renders as its own bare name is a sign that it needs either a cause or a template.

§Enrichment and backtraces

The message is only the first part of what Display writes — with a template and a cause it is already two lines. Each enrichment entry follows it on its own line, marked with > and tagged with the place it was added:

use std::io;

#[ohno::error]
pub struct ConfigError;

#[ohno::enrich_err("failed to load the service configuration")]
fn read_config() -> Result<String, ConfigError> {
    Err(ConfigError::caused_by(io::Error::new(
        io::ErrorKind::NotFound,
        "no such file: /etc/app.toml",
    )))
}

let error = read_config().unwrap_err();

println!("{error}");
// Output: no such file: /etc/app.toml
//         > failed to load the service configuration (at src/config.rs:6)

A captured backtrace comes last for that level, after that level’s enrichment:

no such file: /etc/app.toml
> failed to load the service configuration (at src/config.rs:6)

Backtrace:
   0: std::backtrace::Backtrace::capture
   1: ohno::backtrace::Backtrace::capture
   2: ohno::core::OhnoCore::from_source
   3: my_app::config::ConfigError::caused_by
   4: my_app::config::read_config
   ...

Whether a backtrace is captured at all is the standard library’s decision — see its environment variables. Use ErrorExt::message() to read the message without this level’s own enrichment or backtrace.

Every error owns its OhnoCore, and every core renders its own backtrace, so a chain of wrappers that all use the default rendering prints the message once and one backtrace block per level. The levels are written in turn, innermost first — a wrapper’s own enrichment and backtrace follow the complete rendering of the level it wraps, so an outer enrichment entry appears after the inner level’s Backtrace: block, not alongside the other enrichment:

no such file: /etc/app.toml

Backtrace:
   ... frames from where ConfigError wrapped the io::Error ...

Backtrace:
   ... frames from where StartupError wrapped the ConfigError ...

This follows from each type holding its own core, and is worth knowing before a type is wrapped several layers deep.

§Overriding error text

The #[display("...")] attribute replaces the rendered message with a template of its own, while still printing the cause after it. A cause that is an error also stays in the source() chain; a cause given as a string is printed the same way but does not join the chain, exactly as under the default rendering.

use std::path::PathBuf;

#[ohno::error]
#[display("Failed to read config with path: {path}")]
pub struct ConfigError {
    pub path: String,
}

// Usage
let error = ConfigError::caused_by("/etc/config.toml", "file not found");

// Output: "Failed to read config with path: /etc/config.toml\ncaused by: file not found"

The template string supports field interpolation using {field_name} syntax. Unlike the default rendering, the cause is never printed on its own: the custom message always leads, and the cause (if any) follows on the next line, after a caused by: label. If the error has no cause, only the custom message is displayed — the type name is never used once a template is given.

Fields of a tuple struct are interpolated by index, using {0}, {1}, and so on.

§Format Arguments

Anything that is not a plain field reference is passed as a positional argument, with format!’s placeholder and argument-counting semantics:

use std::path::PathBuf;

#[ohno::error]
#[display("failed to read config: {}", path.display())]
pub struct ConfigError {
    pub path: PathBuf,
}

Positional arguments are implicitly scoped to self, so a field is referenced by its bare name. Neither the self. prefix nor the leading-dot form is accepted:

Argument	Accepted
`path.display()`	yes
`self.path.display()`	no, the `self.` prefix is implicit
`.path.display()`	no, not a valid expression

§Automatic Constructors

By default, #[derive(Error)] automatically generates new() and caused_by() constructor methods:

#[ohno::error]
struct ConfigError {
    path: String,
}

// The derive macro automatically generates:
//
// impl ConfigError {
//     pub(crate) fn new(path: impl Into<String>) -> Self { ... }
//     pub(crate) fn caused_by(path: impl Into<String>, error: impl Into<Box<dyn Error...>>) -> Self { ... }
// }

let error = ConfigError::new("/etc/config.toml");
let error_with_cause = ConfigError::caused_by("/etc/config.toml", "File not found");

The generated constructors are pub(crate), regardless of the visibility of the error type itself. They are an implementation convenience for the crate that defines the error, not part of its public API, so a pub struct error exported from a library cannot be constructed with new() or caused_by() by a downstream crate. This is deliberate: it keeps the set of ways an error can be built under the control of the crate that owns it, so adding a field is not a breaking change for callers.

Disabling Automatic Constructors:

#[no_constructors] disables the generated constructors, leaving the names new and caused_by free for hand-written versions. It works only with #[derive(Error)], which requires the OhnoCore field to be declared explicitly — and that field is the one the hand-written constructor has to initialize:

use ohno::{Error, OhnoCore};

#[derive(Error)]
#[no_constructors]
struct CustomError {
    inner_error: OhnoCore,
}

impl CustomError {
    pub fn new(custom_logic: bool) -> Self {
        // Custom constructor logic here
        Self {
            inner_error: OhnoCore::default(),
        }
    }
}

§Automatic From Implementations

The #[from(Type1, Type2, ...)] attribute automatically generates From<Type> implementations for the specified types. Other fields in the struct are defaulted using Default::default().

#[ohno::error]
#[derive(Default)]
#[from(std::io::Error, std::fmt::Error)]
struct MyError {
    optional_field: Option<String>,
    code: i32,
}

// This generates:
// impl From<std::io::Error> for MyError { ... }
// impl From<std::fmt::Error> for MyError { ... }

let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "file not found");
let my_err: MyError = io_err.into(); // Works automatically
// optional_field = None, code = 0 (defaulted)

Note: Error’s fields must implement Default when using #[from] to ensure they can be properly initialized.

§Error Enrichment

The #[enrich_err("message")] attribute macro adds error enrichment with file and line info to function errors.

Functions annotated with #[enrich_err("message")] automatically wrap any returned Result. If the function returns an error, the macro injects a message, including file and line information, into the error chain.

Requirements:

The function must return a type that implements the map_err method (such as Result or Poll)
The error type must implement the Enrichable trait (automatically implemented for all ohno error types)

Supported syntax patterns:

Simple string literals:

#[enrich_err("failed to process request")]
fn process() -> Result<(), MyError> { /* ... */ }

Parameter interpolation:

#[enrich_err("failed to read file: {path}")]
fn read_file(path: &str) -> Result<String, MyError> { /* ... */ }

Complex expressions with method calls:

use std::path::Path;

#[enrich_err("failed to read file: {}", path.display())]
fn read_file(path: &Path) -> Result<String, MyError> { /* ... */ }

Multiple expressions and calculations:

#[enrich_err("processed {} items with total size {} bytes", items.len(), total_size)]
fn process_items(items: &[String], total_size: usize) -> Result<(), MyError> { /* ... */ }

Mixed parameter interpolation and format expressions:

#[enrich_err("user {user} failed operation with {} items", items.len())]
fn user_operation(user: &str, items: &[String]) -> Result<(), MyError> { /* ... */ }

All patterns include file and line information automatically:

#[ohno::error]
struct MyError;

#[ohno::enrich_err("failed to open file")]
fn open_file(path: &str) -> Result<String, MyError> {
    std::fs::read_to_string(path).map_err(MyError::caused_by)
}
// Error output will include: "failed to open file (at src/main.rs:42)"

§AppError

For applications that need a simple, catch-all error type, use AppError. It automatically captures backtraces and can wrap any error type.

To avoid accidental usage in libraries, AppError is only available when the app-err feature is enabled.

Example usage:

use ohno::AppError;

fn process() -> Result<(), AppError> {
    std::fs::read_to_string("file.txt")?; // Automatically converts errors
    Ok(())
}

§Error Labeling

ErrorLabel is a low-cardinality string label for errors, intended for use as a metric tag or structured log field. Labels must be chosen from a small, bounded set known at development time to avoid high-cardinality metric series.

use ohno::ErrorLabel;

let label: ErrorLabel = ErrorLabel::from_static("timeout");
assert_eq!(label, "timeout");

let label = ErrorLabel::from_parts(["http", "client", "timeout"]);
assert_eq!(label, "http.client.timeout");

Use ErrorLabel::from_error_chain to walk an error’s source chain and build a dotted label from recognized errors:

use ohno::ErrorLabel;

let io_err = std::io::Error::new(std::io::ErrorKind::ConnectionRefused, "refused");
let label = ErrorLabel::from_error_chain(&io_err, |e| {
    e.downcast_ref::<std::io::Error>()
        .map(|io| ErrorLabel::from(io.kind()))
});
assert_eq!(label, "connection_refused");

Types that carry an ErrorLabel can implement the Labeled trait to expose it uniformly via Labeled::label.

Modules§

test_utiltest-util: Test utilities for the ohno crate.

Macros§

app_errapp-err: Construct an AppError in place.
assert_error_messagetest-util: Assert that an error message matches the expected value, accounting for potential backtraces.
bailapp-err: Return early with an AppError.

Structs§

AppErrorapp-err: Application-level error type that wraps any error.
EnrichmentEntry: An enrichment entry containing a message and its source location.
ErrorLabel: A low-cardinality label for an error, useful for metrics and logging.
Location: Source location information (file and line).
OhnoCore: Core error type that wraps source errors, captures backtraces, and holds enrichment entries.

Traits§

Enrichable: Base trait for adding error enrichment to error types.
EnrichableExt: Extension trait providing ergonomic error enrichment methods.
ErrorExt: Extension trait providing additional functionality for ohno error types.
IntoAppErrorapp-err: Transforms Result and Option types into AppError with additional message.
Labeled: Trait for errors that carry an ErrorLabel.

Attribute Macros§

enrich_err: Attribute macro for adding error enrichment with file and line info to function errors.
error: Attribute macro that adds the OhnoCore field to a struct and derives the error traits.

Derive Macros§

Error: Derive macro for automatically implementing error traits.

Crate ohno

Crate ohno Copy item path

§Key Features

§Quick Start

§Derive Macro

§ohno::error

§How error text is rendered

§Enrichment and backtraces

§Overriding error text

§Format Arguments

§Automatic Constructors

§Automatic From Implementations

§Error Enrichment

§AppError

§Error Labeling

Modules§

Macros§

Structs§

Traits§

Attribute Macros§

Derive Macros§

Crate ohno

§`ohno::error`