Skip to main content

Module error

Module error 

Source
Expand description

The LEAF ERROR’s model — an application’s own failure type, dressed to render under its code. THE LEAF ERROR’s midwife: an application’s own failure type, dressed to render.

ⓘ
#[ingraph::mutation_error]
pub enum WatchError {
  #[ingraph(code = "NOT_A_DIRECTORY", error = "`{0}` is not a directory")]
  NotADirectory(PathBuf),
}

emits Display, core::error::Error and one reading — code() — and NOTHING ELSE. The enum stays the author’s: its arms, its payloads, its derives and its visibility are echoed untouched.

§IT IS A CONVENIENCE AND NOT A SEAM, which is the ruling and not a hedge

A hand-written error is exactly as legal here as a generated one. Nothing in this framework asks a failure type for anything but a Display — error(type = "…")’s own rendering, and the assembled face’s error sum, both spend that and no more — so a type that implements Display by hand, or through somebody else’s derive, is a first-class declared failure. What this macro buys is the CODE DISCIPLINE below, which a hand-written error simply does not get checked for.

§ONE CODE PER VARIANT, and the code IS the head of the sentence

Every variant writes a code, and the rendering is CODE: message. That is the one-code-head law, and it is why the code is mandatory rather than optional: a leaf error’s whole job at the wire is to be recognised, and a variant with no word is a refusal a client cannot tell from its neighbour.

It is also why a declaration that heads such an error a SECOND time is a mistake. A declared error(type = "…", code = "…") puts its own heading in front of whatever the value renders as, so an error minted here — which already carries one — is declared WITHOUT the code word. Two headings on one message is two vocabularies with nothing telling a reader which is which.

§THE CODE SPACE IS OPEN, and the framework’s own words are RESERVED

An application mints whatever SCREAMING_SNAKE_CASE words it likes: this framework cannot enumerate everybody’s failures and does not try. What it does hold is its OWN vocabulary — the ErrorCode table, one word per typed refusal that can reach the wire — and a declaration that mints one of those words is refused. A client matching on UNREACHABLE_SOURCE would otherwise be told the change was made and not applied by an application error that meant something else entirely.

RESERVED is that table’s words, carried here because a proc macro cannot depend on the crate it generates code for. The two lists are pinned EQUAL by ingraph’s own graphql::code fixture — the file a round that adds a word already has to touch, which is what makes the pin catch that round rather than merely catch a rename.

§WHAT THE DECLARATION OWES

A Debug, because core::error::Error has it as a supertrait — and nothing here emits one, because a Debug this emission wrote would collide with the derive most error types already carry. A Display on every field a template RENDERS; nothing at all on a field it never names, which is bound as _.

§THE TEMPLATE is a format string over the variant’s own fields

{0} and {} name a tuple variant’s fields by position; {name} names a struct variant’s by name. What is emitted is ONE write_str-or-write! per arm with the head folded in at expansion time, and every argument passed EXPLICITLY by name — implicit capture is the declaring crate’s edition to have, and an expansion does not get to assume one.

Structs§

Binding
ONE field a template referred to.
ErrorModel
A validated leaf-error declaration, ready to emit.
Rendering
A variant’s message, as the emission spends it.
VariantModel
ONE variant of a leaf error: what it is called, what it is recognised by, and what it says.

Enums§

BindingAt
Where a bound field sits in its variant.
ErrorRoad
WHICH ROAD an error was minted for — the word an author wrote, carried for the sentence.
VariantShape
A variant’s fields, as a pattern has to spell them.

Constants§

RESERVED
The FRAMEWORK’s own wire vocabulary, as words.