CanWrapError
Attach a piece of detail to an error the context already holds, enriching it as it propagates.
Overview
In Context-Generic Programming (CGP), CanWrapError<Detail> enriches an error as it
travels up a call stack. CGP enables pluggable trait implementations in Rust, and CanWrapError is
the component that lets a context plug in how detail is folded into its error. Where
CanRaiseError converts a foreign error into the context's abstract
error, CanWrapError takes an error the context already holds and folds a piece of Detail
into it, a message, a span, a path, producing an enriched Self::Error. The context is the type the
implementation runs against, and it decides how detail is combined with an existing error. Together
the two components cover the common error-handling motions in CGP: raise a foreign error in, then
wrap context onto it as it bubbles up.
Because the trait is parameterized by Detail, one context can attach many kinds of detail, each
through its own provider, all onto the same abstract error. Like its companion, CanWrapError builds on
HasErrorType, which supplies the Self::Error it takes and returns.
Definition
CanWrapError is defined as:
#[cgp_component(ErrorWrapper)]
#[prefix(@cgp.core.error in DefaultNamespace)]
#[derive_delegate(UseDelegate<Detail>)]
#[use_type(HasErrorType.Error)]
pub trait CanWrapError<Detail> {
#[track_caller]
fn wrap_error(error: Error, detail: Detail) -> Error;
}
Its attributes:
#[cgp_component]— turns the trait into a component: its argument names the provider traitErrorWrapperthat implementations target and the wiring keyErrorWrapperComponent, whileCanWrapErrorstays the consumer trait callers use.#[prefix]— registers the component inDefaultNamespaceunder the path@cgp.core.error, so a context that joins that namespace binds its provider at@cgp.core.error.ErrorWrapperComponent.Stringrather than at the bare key.#[derive_delegate]— generates aUseDelegateprovider that dispatches on theDetailtype, so a context can route eachDetailto its own provider; theopenstatement is the modern sugar for the same dispatch.#[use_type]— addsHasErrorTypeas a supertrait and rewrites the bareErrorto<Self as HasErrorType>::Error.
Usage
CanWrapError is in the prelude. Its method is an associated function that takes the context's current
error plus a detail and returns a new error with the detail folded in:
fn wrap_error(error: Error, detail: Detail) -> Error;
A context gains the operation by wiring ErrorWrapperComponent, whose key lives under
cgp::core::error, to a provider. The trait dispatches per detail type, so the natural wiring is a
table keyed on Detail, most idiomatically an open statement:
delegate_components! {
App {
open ErrorWrapperComponent;
@ErrorWrapperComponent.String: AppendDetail,
@ErrorWrapperComponent.u64: DisplayError,
}
}
AppendDetail is a provider of the application's own that folds a String detail into the error;
Examples defines it. DisplayError formats any
Display detail into a String and forwards it to the context's own CanWrapError<String>, so here a
u64 detail reaches AppendDetail too. The forwarding is why DisplayError cannot serve the String
entry itself: @ErrorWrapperComponent.String: DisplayError sends the lookup back to the same entry, and
the check overflows:
error[E0275]: overflow evaluating the requirement `App: IsProviderFor<ErrorWrapperComponent, App, String>`
The error providers supply the strategies that satisfy it, and the
standalone backend crates (cgp-error-anyhow, cgp-error-eyre, cgp-error-std) wire wrapping for
common detail types, so an application usually plugs in a backend rather than writing wrap logic itself.
Because wrap_error is an associated function, generic code calls it on the context type,
Context::wrap_error(err, detail), without borrowing a context value.
Calling it on a concrete context by its bare name, as App::wrap_error(…), is ambiguous when the
provider trait ErrorWrapper is also in scope, because a context implements the provider trait too.
The compiler reports error[E0034]: multiple applicable items in scope. Name the consumer trait
in that case, as <App as CanWrapError<String>>::wrap_error(…), or leave ErrorWrapper unimported.
wrap_error carries #[track_caller], and the attribute survives every layer of forwarding.
Rust applies #[track_caller] on a trait method declaration to every implementation of that method,
and #[cgp_component] keeps it on the provider trait's declaration. It therefore covers the
consumer and provider blanket implementations, the UseDelegate, RedirectLookup, and UseContext
implementations, and every provider. An error library that records Location::caller(), such as
eyre with its track-caller feature, records the line that called wrap_error, whether the
component is wired directly, with open, through a namespace path, or through a UseDelegate
table. The location survives only while every call between that line and the library is
#[track_caller]: a generic helper function without the attribute records its own line instead.
Examples
A provider wraps a message onto an error as it propagates:
use cgp::core::error::{
ErrorRaiserComponent, ErrorTypeProviderComponent, ErrorWrapper, ErrorWrapperComponent,
};
use cgp::extra::error::RaiseFrom;
use cgp::prelude::*;
#[cgp_component(Loader)]
#[use_type(HasErrorType.Error)]
pub trait CanLoad {
fn load(&self, path: &str) -> Result<String, Error>;
}
#[cgp_impl(new LoadOrFail)]
#[uses(CanRaiseError<String>, CanWrapError<String>)]
#[use_type(HasErrorType.Error)]
impl Loader {
fn load(&self, path: &str) -> Result<String, Error> {
if path.is_empty() {
let err = Self::raise_error("empty path".to_owned());
return Err(Self::wrap_error(err, format!("while loading {path}")));
}
Ok(format!("contents of {path}"))
}
}
#[cgp_impl(new AppendDetail)]
#[use_type(HasErrorType.{Error = String})]
impl ErrorWrapper<String> {
fn wrap_error(error: Error, detail: String) -> Error {
format!("{detail}: {error}")
}
}
pub struct App;
delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
ErrorRaiserComponent: RaiseFrom,
ErrorWrapperComponent: AppendDetail,
LoaderComponent: LoadOrFail,
}
}
check_components! {
App {
LoaderComponent,
}
}
App.load("") returns Err("while loading : empty path"). AppendDetail pins the abstract error to
String with the equality form of #[use_type], since it builds a
String directly.
The provider LoadOrFail first raises a String into the context's abstract error with
CanRaiseError, then wraps a further message onto it with CanWrapError. Both
dependencies are declared with #[uses], so neither appears on the public
CanLoad signature, and any context that satisfies them makes load produce enriched errors in its own
error type. App here satisfies them with RaiseFrom and AppendDetail. The context is an environmental context, and the component targets it.
When to use it
Reach for CanWrapError<D> when a provider should add context to an error before returning it. It
is how a CGP program builds the equivalent of an error chain or a .context(...) message without
committing to a concrete error library, and it pairs naturally with
CanRaiseError in a provider that both converts and enriches. Declare it with
#[uses(CanWrapError<D>)] so the dependency stays off the consumer trait.
Do not reach for it when there is no detail worth attaching, where raising the error is enough, or when the context's error type already captures the surrounding context by other means.
Related constructs
CanRaiseError— the companion that converts a foreign error into the abstract one.HasErrorType— the supertrait supplying theSelf::Errorthis enriches.- Error providers — the strategies that satisfy this component.
#[derive_delegate]— generates theUseDelegatedispatch this uses.#[uses]— the idiomatic way a provider declares this dependency.
The ideas behind it:
- Modular error handling — the error type, its construction, and its detail as three independent wiring decisions.
Source
- The trait:
can_wrap_error.rs - The abstract error it builds on:
has_error_type.rs - The pluggable providers that implement it:
standalone/error/
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.