Skip to main content

mutation_error

Attribute Macro mutation_error 

Source
#[mutation_error]
Expand description

Dress an application’s own failure type to RENDER — a declared exchange’s error, given a code and a sentence.

ⓘ
#[ingraph::mutation_error]
pub enum WatchError {
  #[ingraph(code = "NOT_A_DIRECTORY", error = "`{0}` is not a directory")]
  NotADirectory(PathBuf),
  #[ingraph(code = "ALREADY_WATCHED", error = "{root} is already watched, as watch {id}")]
  AlreadyWatched { root: String, id: u64 },
}

§A CONVENIENCE AND NOT A SEAM

A hand-written error is exactly as legal. Nothing in this framework asks a failure type for more than a Display — that is all error(type = "…")’s rendering spends, and all the assembled face’s error sum spends — so an error that implements it by hand, or through somebody else’s derive, is a first-class declared failure. What this word buys is the CODE DISCIPLINE, which nothing checks for a hand-written one.

§Attributes, per VARIANT, and neither is optional

  • code = "SCREAMING_SNAKE_CASE" — what a client MATCHES ON, and the head of everything this variant renders as.
  • error = "…" — what a person READS. A format string over the variant’s own fields: {0} and {} by position, {name} by name, {{ for a literal brace.

§What it emits

itemcontent
the author’s enum, echoedunchanged but for the markers this macro consumed
impl Display"CODE: message", one arm per variant, from one literal apiece
impl core::error::Errorthe defaulted source, this macro having no way to know which field is a cause
<Error>::codethe word this variant is recognised by

The declaration is otherwise untouched: its arms, its payloads, its derives, its visibility.

§THE ENUM OWES A Debug, and it is the author’s to write

core::error::Error has Debug as a supertrait, so a declaration wears #[derive(Debug)] — or an impl of its own. Nothing here emits one, and the omission is the point: a Debug this macro wrote would collide with the derive most error types already carry (E0119), and choosing between them by scanning attributes would make the emission depend on which way an author happened to spell it. What an author sees if they forget is rustc naming Debug under required by a bound in Error, at the enum.

A field the template RENDERS owes a Display; one it never names owes nothing at all, being bound as _.

§THE CODE HEADS THE MESSAGE, so a declaration does not head it again

An exchange declaring error(type = "…", code = "…") puts its own heading in front of whatever the value renders as. An error minted here already carries one, so such an exchange writes error(type = "…") and NO code word — two headings on one message is two vocabularies with nothing telling a reader which is which.

§Refusals

writtenrefused because
a variant with no codethe code is what a client matches on, and a variant without one is a refusal it cannot tell from its neighbour
a variant with no errora code with no message under it says nothing to a person
code = "notScreaming"a code is a machine-read constant, in GraphQL’s own convention for one
two variants under one codea vocabulary is a contract only while it is injective
a code that is one of the framework’s owna client matching it is asking about a refusal this framework raises
{name} naming no field, or {7} past the last onethe template reads the variant’s own fields
a struct or a unionan error’s VARIANTS are the ways it can fail
a generic parameterthe expansion writes ONE Display over ONE type
any argument on the attribute itselfevery word is written on a variant