1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
//! The WIRE ERROR CONTRACT: the stable word a refusal is recognised by, and the vocabulary it is
//! drawn from.
//!
//! ```text
//! { "errors": [ { "message": "…for a human…",
//! "extensions": { "code": "REPEATED_ORDER_SUBJECT" } } ] }
//! ```
//!
//! # The CODE is the contract and the message is not
//!
//! A refusal's sentence is written for a person reading it, and every sentence in this framework is
//! free to get better: a clearer wording, a named term where a position used to be, a fact the
//! refusal learned to carry. None of that may break a client, so none of it can be what a client
//! matches on. [`ErrorCode`] is what it matches on instead — one word per refusal, chosen once and
//! then kept.
//!
//! # The vocabulary is DERIVED, and the derivation is the rule a new word is added under
//!
//! One word per TYPED REFUSAL that can reach the wire, named after WHAT WAS REFUSED. Two clauses,
//! and each is doing work:
//!
//! - **per typed refusal**, so the vocabulary is a projection of the named-refusal culture rather
//! than a second list somebody keeps in step. A refusal type that reaches a resolver has a word;
//! one that cannot, has none. Nothing is minted for a case no code path produces — so the words
//! here are the order decode's, the page request's, the ENGINE LANE's and the TRANSPORT's, those
//! being the doors a refusal reaches a client through.
//! [`SqlWriteError`](crate::query::sql::SqlWriteError) still has no word, and its absence is that
//! rule holding after the mutation door landed: a declared exchange's handler does its own writing
//! through the resource it was granted, so that refusal is the HANDLER's and reaches a client as
//! the failure its declaration named. Nothing in this framework raises it on a resolver's behalf.
//! - **named after what was refused, never after who refused it.** A code naming a backend would be
//! a wire contract that varied with a deployment's storage choice, which is the same thing
//! [`GraphqlInput::Filter`](crate::GraphqlInput::Filter) refuses one type per database for. Two
//! families refusing one thing share the word.
//!
//! Growth is ADDITIVE by construction: a new refusal adds a word, and an existing word is never
//! re-pointed at a different refusal. The enum is `#[non_exhaustive]` so that a client of THIS crate
//! matching on it keeps compiling when the next round adds one.
//!
//! # It is a closed enum, and that does not contradict the open-surface rule
//!
//! Every extension seam in this framework is a trait, because the thing behind it is a downstream
//! crate's to write. This is the other kind: a wire vocabulary is the FRAMEWORK's, exactly as
//! [`OrderDirection`](crate::OrderDirection) and the cursor frame's own bytes are, and a word a
//! third party could mint would be a word no client could have been told about. What a declarer
//! contributes reaches the wire through the refusal it rides on — a declared crossing that fails is
//! the framework's crossing refusing — so the open half is where the FACTS come from and the closed
//! half is what they are announced under.
//!
//! # The vocabulary is UNGATED and the attachment is not
//!
//! Generated code lives in the DECLARING crate and cannot spell a feature of this one, so anything
//! an expansion may name has to exist in every build — the split
//! [`ToSubjectPath`](crate::ToSubjectPath) already carries. [`ErrorCode`] and [`ToErrorCode`] are
//! therefore unconditional; [`refused`] and [`refused_input`], which name async-graphql's own error
//! types, ride the binding.
use Display;
/// The stable word one wire refusal is recognised by — the value of `extensions.code`.
///
/// # What each word means to a client, and what it should do about it
///
/// | code | the client's own fix |
/// |---|---|
/// | `REPEATED_ORDER_SUBJECT` | delete the second term naming that subject |
/// | `AMBIGUOUS_PAGE_DIRECTION` | keep the page arguments of ONE direction |
/// | `UNUSABLE_CURSOR` | drop the cursor and start the page again |
/// | `UNSUPPORTED_FILTER` | ask the column a question this deployment's store can answer |
/// | `UNRENDERABLE_ORDER` | drop the term this store cannot sort by |
/// | `UNPAGEABLE_ORDER` | page by terms a cursor can hold — a collection column is not one |
/// | `UNREADABLE_ROW` | none: retry later, and tell whoever owns the schema |
/// | `OVERSIZED_SKIP` | ask for a smaller `skip`, or page with a cursor instead |
/// | `UNUSABLE_ADDRESS` | name a row by an id of the form this schema publishes |
/// | `UNWRITTEN_ARTIFACT` | retry later, or poll: the pipeline has not written that object yet |
/// | `STORE_REFUSED` | none: retry later |
/// | `UNREACHABLE_SOURCE` | none: the change was MADE and not applied — reconcile, do not repeat |
/// | `UNREACHABLE_NODE` | none: nothing ran, so tell whoever owns the deployment |
/// | `REQUEST_DROPPED` | retry: something gave up without answering |
/// | `REQUEST_TIMED_OUT` | retry with a longer deadline, or poll: it may still be running |
///
/// Most of them are a QUERY a client wrote and can rewrite, which is what this vocabulary is for.
/// The rest are the exception and they are worth having anyway: a client that can tell *my query is
/// wrong* from *the server could not answer it* knows whether to retry, and that is an action even
/// where rewriting is not. The transport's four are the sharpest case of it — one of them says the
/// EFFECT HAPPENED and nothing applied it, which is a thing no rewrite and no retry addresses.
///
/// Two of them come from ONE refusal type, and that is the derivation rule's second reading rather
/// than an exception to it: [`PageError`](crate::PageError)'s arms refuse two different things and
/// ask a client for two different fixes, so a word each is what makes the code worth matching on. A
/// sum whose arms ask for ONE fix — [`CursorError`](crate::CursorError)'s seven ways of not being a
/// cursor — answers with one.
///
/// # A word that LEFT, and why the vocabulary is still additive
///
/// `UNORDERED_PAGE` stood here and refused a page whose query wrote no `orderBy`. The key default
/// superseded the refusal — an absent argument is the record's key ascending now, which is a total
/// order — so the refusal it named cannot be raised. Growth is still additive in the sense that
/// matters: no word was RE-POINTED at a different refusal, which is the thing a client cannot
/// survive. A word whose refusal has stopped existing is a word nothing can send, and keeping it
/// would contradict this module's own rule that a refusal which cannot reach the wire has none.
///
/// # The word is the REFUSAL's and never the backend's
///
/// `STORE_REFUSED` rather than `SQLX_ERROR`, `UNSUPPORTED_FILTER` rather than
/// `SQLITE_LOWERING_ERROR`. A code naming a backend would be a wire contract that varied with a
/// deployment's storage choice — the same thing
/// [`GraphqlInput::Filter`](crate::GraphqlInput::Filter) refuses one type per database for. When the
/// document family grows a wire door, its own refusals join these words rather than minting a
/// parallel set: two families refusing one thing share it.
/// The code one typed refusal announces itself under.
///
/// Implemented BY the refusal rather than read off a table beside it, for the reason
/// [`ToSubjectPath`](crate::ToSubjectPath) is a trait: the fact belongs to the type that has it, so
/// a refusal that grows a variant cannot leave a mapping somewhere else out of date. A refusal with
/// no impl is a refusal that does not reach the wire, which is a state this trait makes visible.
///
/// A method rather than an associated constant, because a refusal may be a sum whose arms differ:
/// nothing today does, and an enum whose variants ever want two words answers here without the
/// trait changing shape.
/// The wire form of a typed refusal: its own sentence, and its code in `extensions`.
///
/// The ONE place a code is attached to a resolver's refusal, so there is no path to an error that
/// carries a message and no word. A resolver hands over the refusal it holds and never assembles
/// the error itself.
/// The wire form of a refusal raised by the WIRE CROSSING — a stored row that will not become its
/// output object.
///
/// A second entry point because such a refusal is the DECLARER's type: `graphql(output(<db>(error =
/// "…")))` names it, or the framework boxes one, and neither can implement
/// [`ToErrorCode`] — a word is the framework's to choose and a declaration's error has no business
/// choosing one. So the word is chosen HERE, and it is
/// [`UnreadableRow`](ErrorCode::UnreadableRow): the row read fine and does not become what a client
/// asked for, which is the same fact one layer over and asks the same nothing of the client.
///
/// It shares [`refused`]'s attachment, which is what keeps the module's own rule true — one place
/// where a code meets an error, whichever of the two doors the refusal came through.
/// The wire form of a refusal raised by the ADDRESS crossing — an id a client wrote that this
/// record's own `ToGraphqlInput` row will not read.
///
/// [`refused_row`]'s reason one position over: the refusal is the DECLARER's type, which can
/// implement no [`ToErrorCode`], so the word is chosen here. It shares the same attachment, which is
/// what keeps this module's one-place rule true whichever of the three doors a refusal came through.
/// The one attachment: a sentence, and the word beside it.
/// The wire form of a refusal raised by the FILTER crossing — an operand a client wrote that this
/// record's own crossing into the store's comparison will not take.
///
/// [`refused_row`]'s reason a third time: the refusal is the DECLARER's type — `graphql(input(
/// comparison(<db>(error = "…"))))` names it, or the framework boxes one — so it can implement no
/// [`ToErrorCode`] and the word is chosen here.
///
/// The word is [`UnsupportedFilter`](ErrorCode::UnsupportedFilter), which is the one it already
/// meant. That code's own row reads *a predicate this deployment's store has no spelling for*, and an
/// operand the store cannot hold is that fact one layer earlier: the SCHEMA is backend-neutral by
/// design, so it offers operands a compiled backend may refuse, and whether the refusal lands at the
/// crossing or at the lowering is an implementation detail of WHERE it was noticed. The client's fix
/// is the same sentence either way — ask the column a question this deployment's store can answer —
/// which is the whole test the derivation rule's second clause applies.
/// The wire form of a DECLARED failure — a mutation exchange's own, rendered under the heading its
/// declaration wrote.
///
/// # The one-code-head law, which is what this function IS
///
/// `error(…, code = "…")` is a HEADING and it is optional, so there are two renderings and not one:
///
/// | written | what a client reads |
/// |---|---|
/// | `error(type = "E", code = "ADD_FAILED")` | `ADD_FAILED: <whatever E renders as>` |
/// | `error(type = "E")` | `<whatever E renders as>` |
/// | `error(message = "…", code = "NOT_OURS")` | `NOT_OURS: …` |
/// | `error(message = "…")` | `…` |
///
/// One function for both failure shapes, because the heading is orthogonal to which shape a field is
/// in: a CANNED failure hands its declaration's own sentence and a RICH one hands the value the
/// handler returned, and from here they are the same thing — something that renders.
///
/// # It attaches NO extension, and that is a ruling rather than an omission
///
/// Every other door in this module sets `extensions.code`, because the word it sets is
/// [`ErrorCode`]'s — the FRAMEWORK's closed vocabulary, chosen once and kept. A declared code is the
/// APPLICATION's, drawn from the open space this framework deliberately left it, and putting it in
/// the same slot would publish two vocabularies under one key with nothing telling a client which
/// one a given word came from. So the declared heading rides the MESSAGE, which is the rendering the
/// declaration's own grammar promises, and `extensions.code` for declared failures is recorded as a
/// later refinement rather than forged now.
///
/// # A rich failure's `source()` chain is untouched
///
/// Nothing here boxes, erases or re-types the value: the handler returned its own error type, this
/// borrows it to render, and the caller still holds whatever it was. What a client reads is the
/// sentence that error renders, exactly as every other refusal in this module.
/// The same, for a refusal raised while DECODING an argument.
///
/// A second entry point because async-graphql's input errors are a type of their own —
/// [`InputValueError`](async_graphql::InputValueError) carries the input's type name into the
/// message and is positioned at the argument the value was written in, which a plain
/// [`Error`](async_graphql::Error) raised from a resolver body cannot be. The EXTENSIONS survive
/// [`propagate`](async_graphql::InputValueError::propagate), so a code set at an inner decode still
/// reaches the client through an outer one.