pub struct HookError(/* private fields */);Expand description
Boxed hook callback error which preserves the concrete source for downcast.
§Effect on the Run
Returning one of these is a decision that the Run should not continue, not a hint that something went wrong. Reef never retries a callback, substitutes a default decision, or carries on with the remaining registrations: the failing boundary short-circuits, and whatever it had composed, staged, or planned is discarded rather than half-applied. Peers registered after the failure are not called, and peers that already ran do not have their contributions kept.
The failure always reaches the caller with the failing registration’s name
attached, as an AttributedError. Where it surfaces depends only on which
boundary was running:
- At Run admission, as
StartError::Prepare. The Session lease and Agent attachment are rolled back, so admission having failed means nothing was committed and no Run exists. - At every other boundary, by ending the Run: its
TerminalreportsOutcome::Failedwith theFailureKindof the boundary that was running —Hookfor most,TranscriptorToolCommitfor a failed reservation, according to which mutation it was reserving. The retained failure is reachable from the terminal, and the registration name survives the whole chain.
A cancellation observed at the same boundary ends the Run as
Cancelled instead; a real
callback error is never downgraded to a cancellation.
This is why a degradation the Run can survive should not be reported this way.
A mutating scope’s emit_error method publishes a non-fatal fact and leaves
the Run running, which is the right shape for a hook whose optional work
failed. HookError is for the case where continuing would be wrong.
Implementations§
Trait Implementations§
Source§impl Debug for HookError
impl Debug for HookError
Source§fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
Renders every link of the retained chain, each one through Display.
Printing only the outermost link would discard the chain that
source_ref retains: a callback error that wraps its own cause reads
as a single sentence, and the reason underneath it — the one a reader is
usually after — never appears. Walking source states the whole chain.
Display rather than the link’s own Debug, because the cause is
whatever a hook handed back: arbitrary text this crate neither writes
nor reviews. Display is the rendering those types are contracted to
produce, and it is what every other boxed failure in reef prints.
Source§impl Error for HookError
impl Error for HookError
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()