n0-error

n0-error is a Rust error-handling library, built by the n0/iroh team, that combines the ergonomics of structured, derivable error types with automatic tracking of the call-site location where each error originated. It aims to give you the best of both worlds: thiserror-style typed errors for library APIs and anyhow-style flexible dynamic errors for applications, while recording where errors are created and propagated so you get meaningful backtraces without extra boilerplate.

Through derive macros and extension traits, n0-error attaches source-code locations as errors bubble up through ?, making it far easier to pinpoint failures in complex async and distributed systems. It offers an optional anyhow compatibility feature and a companion procedural-macro crate for its derives.

What You Get

• Derive macros for defining structured error types with minimal boilerplate
• Automatic capture of call-site locations as errors are created and propagated
• A dynamic, anyhow-style error type for application-level error handling
• Extension traits for adding context and location while using the ? operator
• Optional anyhow interoperability behind a feature flag

Common Use Cases

• Adding precise, location-aware error reporting to Rust libraries and applications
• Diagnosing failures in async and distributed systems where stack traces are unhelpful
• Migrating between typed (thiserror-like) and dynamic (anyhow-like) error styles in one crate

Under The Hood

Architecture - The crate is split between runtime support in src and derive logic in the n0-error-macros workspace member. src/error.rs and src/any.rs define the typed and dynamic error representations, src/meta.rs carries call-site location metadata, src/ext.rs provides the extension traits used with ?, and src/macros.rs wires the derive-generated code to the runtime.

Tech Stack - Rust on the 2024 edition, organized as a Cargo workspace with a companion proc-macro crate. It depends on spez for autoref-based specialization tricks and offers an optional anyhow dependency for interoperability.

Code Quality - The repository shows disciplined engineering: an in-tree tests module and integration tests, cargo-deny (deny.toml) for dependency and license auditing, git-cliff (cliff.toml) for changelog generation, a cargo-make task runner, and a maintained CHANGELOG at a 1.0 release.

API Design - Ergonomics are the core goal: derive an error type, use provided extension methods to add context during propagation, and locations are captured automatically. Dual typed/dynamic support and optional anyhow compatibility keep the migration path smooth for existing codebases.