Expand description
The engine’s failure surface — one type, classified by what a caller can do about it.
Every public function in this crate returned anyhow::Result until #348.
For a binary that is fine; for a published library it means a consumer
cannot tell a bad key expression from a dead bus without matching on the
text of a sentence, and the one consumer that most needs to tell them
apart is zenctl, whose exit codes are a wire surface CI branches on.
§The classification is the point
RFC 13 §1 draws the line this enum is built around: a question that
could not be put is not the same as a question that was put and
answered badly. Error::Unaskable is the first; everything else is a
failure of an attempt that was actually made.
That distinction had a real cost while it was untyped. zenctl registry lint /nonexistent exited 1 — “asked, and the answer is a finding” —
telling CI that a registry had lint findings when in fact the directory
was not there. It exited 1 because exit::code_for walks the error chain
looking for zenctl’s own Unaskable marker, and an engine error carried
no marker at all. The engine knows perfectly well which of its failures
are refusals of the caller’s input; it just had nowhere to say so.
§What each variant means
| Variant | The caller should | zenctl exits |
|---|---|---|
Unaskable | fix the input | 2 — no verdict |
Bus | retry, or check the fleet | 1, or 2 on a verdict verb |
Io | check the path | 1, or 2 on a verdict verb |
Malformed | distrust the peer | 1 |
Internal | file a bug against this crate | 1 |
§How these render
Display says what failed; source() says why, and a renderer joins
them — zenctl::errors::render prints Error: … then an indented
Caused by: list, trimming zenoh’s build-machine source locations on the
way. So no variant’s Display repeats the text of its own source: doing
that once produced registry dir "/x": No such file immediately followed
by Caused by: No such file, which the CLI corpus caught.
The exception is deliberate. Unaskable inlines its
cause’s text and keeps no source, because those causes are one-line
refusals (“* may only be preceded by /”) whose entire content is
the sentence — there is nothing structured under them to reach for.
Enums§
- Error
- Why a fleet operation could not answer.
Functions§
- one_
line - This error and every cause beneath it, joined by
:— one line.
Type Aliases§
- Boxed
Cause - A cause from somewhere else, kept rather than flattened to text.
- Result
- This crate’s result type.