SNAFU

SNAFU is a Rust library that makes it easy to assign underlying errors into domain-specific error types while attaching context. Using a Snafu derive macro on an error enum, you describe each failure variant with a display message and the context it needs, and SNAFU generates the selectors and conversions to wrap source errors ergonomically at each call site.

The result is error handling that is both descriptive and low-boilerplate: callers use .context(...) to promote a low-level error into a meaningful application error carrying relevant data. SNAFU supports no_std, optional backtraces, futures integration, and a flexible whatever escape hatch for quick, string-based errors.

What You Get

• A Snafu derive macro that generates context selectors and error conversions
• Per-variant display messages that embed contextual data
• The .context() combinator to map source errors into domain errors ergonomically
• A whatever escape hatch for quick, string-based ad-hoc errors
• no_std support, optional backtraces, and futures integration

Common Use Cases

• Defining rich, domain-specific error enums for libraries and applications
• Adding context (paths, ids, operations) when propagating underlying errors
• Handling errors ergonomically in no_std or embedded Rust projects
• Attaching backtraces to errors for easier debugging

Under The Hood

Architecture - SNAFU splits into the runtime crate (src/) and the snafu-derive proc-macro crate. The derive parses your annotated enum and generates, per variant, a context selector struct plus IntoError/From implementations; the runtime crate provides the ResultExt/context() extension traits, the Whatever type (whatever.rs), backtrace abstractions (backtrace_impl_*.rs) selected by feature, boxed-error helpers, and futures adapters (futures/). An extensive prose guide/ is compiled into the docs as a user’s guide.

Tech Stack - Pure Rust (edition 2018, MSRV 1.65), dual runtime + proc-macro crate layout. It has no required third-party runtime dependencies for the core, with optional integrations (backtrace crate, futures) behind Cargo features, and supports std, alloc, and no_std configurations.

Code Quality - The repository is mature with a dedicated tests/ suite, compatibility-tests/ covering multiple feature/toolchain combinations, a CHANGELOG, and a pinned rust-toolchain. Feature-gated backtrace implementations are cleanly isolated into separate modules, and the guide doubles as living documentation and examples.

API Design - SNAFU’s API is a highlight: the derive-plus-.context() pattern reads naturally and keeps error-mapping explicit without verbose match arms. Context selectors are discoverable and type-checked, and the whatever! macro offers a quick path for prototyping. The comprehensive user’s guide flattens the learning curve, though mastering feature flags (backtraces, no_std) takes some study.