Error backends
The error backends are three opt-in crates that make one concrete type a context's abstract error:
cgp-error-anyhow for anyhow::Error, cgp-error-eyre for eyre::Report, and cgp-error-std for
Box<dyn core::error::Error + Send + Sync>. Each supplies a provider that sets the error type and
providers that raise errors into it and wrap detail onto it. Load this reference when wiring a
backend, choosing a provider for a source type, or reading an error from backend wiring. The
components themselves are covered in error handling.
The crates are separate dependencies, not part of the cgp crate. Import the wiring keys from
cgp::core::error and the providers from the backend crate:
use cgp::core::error::{ErrorRaiserComponent, ErrorTypeProviderComponent, ErrorWrapperComponent};
use cgp::prelude::*;
use cgp_error_anyhow::{DisplayAnyhowError, RaiseAnyhowError, UseAnyhowError};
The four providers each backend exports
Every backend exports one provider per role, and the roles are the same across the crates. Only the concrete type and the library call that builds or extends it change:
| Role | anyhow | eyre | std |
|---|---|---|---|
Set the error type (ErrorTypeProviderComponent) | UseAnyhowError | UseEyreError | UseBoxedStdError |
| Raise a standard error intact; wrap a detail | RaiseAnyhowError | RaiseEyreError | RaiseBoxedStdError |
Raise or wrap any Debug value as a message | DebugAnyhowError | DebugEyreError | DebugBoxedStdError |
Raise or wrap any Display value as a message | DisplayAnyhowError | DisplayEyreError | DisplayBoxedStdError |
The last three implement both ErrorRaiser and ErrorWrapper, so each can be wired to either
component. Each of the three pins the context's error to its crate's type through
#[use_type(HasErrorType.{Error = ...})], so it works only on a context whose error is that type,
usually set by the same crate's type provider. Each crate re-exports its error type as Error, for example
cgp_error_anyhow::Error.
The raise providers keep the source error: downcast_ref still finds it, and it is the first link
of the error chain. The Debug and Display providers format the value into a new error and keep
only the message, which is how they accept values that are not standard errors at all, such as a
String or a #[derive(Debug)] struct.
Wiring a backend
A context wires the type provider, then routes each source type with open. This wiring raises a
standard error intact, raises a String as a message, and wraps any 'static detail:
pub struct App;
delegate_components! {
App {
open ErrorRaiserComponent;
ErrorTypeProviderComponent: UseAnyhowError,
@ErrorRaiserComponent.std::io::Error: RaiseAnyhowError,
@ErrorRaiserComponent.String: DisplayAnyhowError,
ErrorWrapperComponent: RaiseAnyhowError,
}
}
check_components! {
App {
ErrorRaiserComponent: [std::io::Error, String],
ErrorWrapperComponent: &'static str,
}
}
With this wiring, App::wrap_error(App::raise_error(std::io::Error::other("disk full")), "while saving")
prints while saving with {} and while saving: disk full with {:#}. A context whose sources
are all standard errors can use one entry without open,
[ErrorRaiserComponent, ErrorWrapperComponent]: RaiseAnyhowError. The same code works for eyre or
std by swapping the three names.
A context that joins DefaultNamespace wires the same providers by path, because the error
components register under @cgp.core.error:
delegate_components! {
App {
namespace DefaultNamespace;
@cgp.core.error.ErrorTypeProviderComponent: UseAnyhowError,
@cgp.core.error.ErrorRaiserComponent.std::io::Error: RaiseAnyhowError,
@cgp.core.error.ErrorRaiserComponent.String: DisplayAnyhowError,
}
}
Routing each source type
Route each source or detail type to the provider that keeps the most information about it. The table uses each crate's own provider names:
| Source or detail | Raise with | Wrap with |
|---|---|---|
A standard error, such as std::io::Error or ParseIntError | Raise… | — |
String, &'static str, or another message | Display… | Display… or Raise… |
A type with only Debug | Debug… | Debug… |
A borrowed detail, such as &'a str | — | Display… or Debug… |
| The context's own error, raised again | the generic RaiseFrom or ReturnError | — |
Prefer Display… for a message, because Debug… quotes a string: raising "bad input" produces the
message "bad input" with the quotation marks. Neither anyhow::Error, eyre::Report, nor a boxed
dyn Error is itself a standard error, so re-raising the context's own error needs RaiseFrom,
which accepts it through the reflexive From<T> for T.
The raise providers require E: StdError + Send + Sync + 'static, and the anyhow and eyre raise
providers used as wrappers require Detail: Display + Send + Sync + 'static. The 'static bound
rejects a detail borrowed from a function argument; wire the wrapper to Display… or Debug…,
which copy the detail into a string. RaiseBoxedStdError's wrapper needs only Detail: Display.
When a backend is not needed
The generic providers in cgp-error-extra already cover two of the four roles.
UseType<anyhow::Error> sets the error type exactly as UseAnyhowError does, and RaiseFrom
raises a standard error exactly as RaiseAnyhowError does. A context that only raises standard
errors and never wraps them needs no backend. A context whose errors form a closed set is often
better served by its own error enum with UseType<AppError> and RaiseFrom, which keeps every
variant matchable.
A backend adds what the generic providers lack. Its wrappers attach a detail to the error, where the
generic DiscardDetail drops it and the generic DebugError/DisplayError forward it to
CanWrapError<String>. Its Debug…/Display… providers build the concrete error from a string
directly, so they can serve as the context's String provider.
Per-crate behavior
The crates differ in a few facts that affect wiring and output:
cgp-error-anyhowisno_stdand builds anyhow without itsstdfeature.{:?}prints the outermost message followed by aCaused by:list.cgp-error-eyreneedsstd, because eyre does. It enables eyre'sauto-installfeature, so eyre's default handler is installed on the first report; installcolor-eyreor another handler witheyre::set_hookbefore raising anything, sinceset_hookreturns an error once a handler exists. It also enablestrack-caller, so a report'sLocation:section names the line that calledraise_error:raise_erroris#[track_caller]through every impl, and wrapping keeps the location. The default handler appends a backtrace to{:?}whenRUST_BACKTRACEorRUST_LIB_BACKTRACEis set.cgp-error-stdisno_stdand needs onlyalloc. Its formatting raisers produce aStringError, and every wrapper produces aWrapError, which returns the wrapped error fromsource().WrapErrorprints only its detail with{}, so a reporter that walkssource()prints each message once, and prints the whole chain joined by": "with{:#}or{:?}.
Diagnosing backend wiring
Most backend errors come from a source routed to a provider whose bounds it does not meet. List the
source types in a check_components! block and run cargo cgp check; each mistake below then fails
at the check entry:
- A message through the raise provider.
ErrorRaiserComponent: RaiseAnyhowErrorchecked forStringfails withE0277, "the trait boundString: Erroris not satisfied". RouteStringtoDisplayAnyhowError. - A raiser without its error type. Wiring
RaiseAnyhowErrorwith noErrorTypeProviderComponententry fails with[CGP-E001], whose root cause[CGP-E113]names the missingErrorTypeProviderComponent. AddUseAnyhowError. - Two backends on one context.
UseBoxedStdErrorwithRaiseAnyhowErrorfails withE0271tagged[CGP-E005]: the abstractErrorisBox<dyn std::error::Error + Send + Sync>, butcgp_error_anyhow::Error, the crate's re-export ofanyhow::Error, is required. Use the raiser from the crate that sets the type. - A
Stringrouted back to itself.@ErrorRaiserComponent.String: DebugError, using the genericDebugError, fails withE0275tagged[CGP-E020], becauseDebugErrorforStringneedsCanRaiseError<String>again. RouteStringto a backend'sDisplay…orDebug…provider. - A borrowed detail. A provider that uses
for<'a> CanWrapError<&'a str>on a context wired toErrorWrapperComponent: RaiseAnyhowErrorfails with a plainE0477, "the type&'a strdoes not fulfill the required lifetime". Wire the wrapper toDisplayAnyhowError.
When a downstream project depends on a backend from crates.io, test it against a local change
through [patch.crates-io], overriding cgp together with the backend. Patching the backend alone
leaves two copies of the CGP crates in the graph, and the wiring fails with E0599 and a rustc note
about multiple versions of cgp_error.
Related documentation
Consult the online knowledge base for each provider's exact bounds and output, the tests that pin them, and the per-crate open issues: