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
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
//! THE THIRD DOOR: where a resolver that has to say WHERE a blob is gets the store to ask.
//!
//! ```text
//! Schema::build(root, …).data(BlobDoor::opened(store)) // the application, once
//! │
//! ▼
//! ctx.data::<BlobDoor<LocalFsStore>>()? → door.store() → handle.locate(…) // every locate field
//! ```
//!
//! [`SqlDoor`](super::SqlDoor)'s pattern, third instance: a seam an application answers with its own
//! provider, a concrete KEY a resolver looks the seam up under, and one act — [`install`] — that
//! says which. What differs is what is behind it, and everything that differs follows from one fact:
//! a blob store's connection-manager is a plain shared handle, where a SQL door exists to work
//! around a `Send`-bound wall in `sqlx::Acquire`.
//!
//! # ONE DOOR PER STORE TYPE, and the parameter IS the routing
//!
//! `BlobDoor<LocalFsStore>` and `BlobDoor<S3Store>` are two types, so an application serving
//! artifacts out of two stores installs two doors and each locate field reaches the one its own
//! family declared. No registry, no name, and no way for a family to read the wrong store — the same
//! sentence the SQL door earns from its `Db` parameter.
//!
//! # It has NO blocking twin, and that is the criterion answering rather than an omission
//!
//! The dual-mode law twins a seam where the underlying ACT can happen natively blocking. This door
//! performs no act: it holds a handle and hands out a borrow of it, which is neither blocking nor
//! async, so an `AsyncBlobDoor` beside it would be two names for one synchronous accessor. What the
//! door is instead is MODE-BLIND — `S` is bounded by neither [`AsyncBlobStore`](crate::AsyncBlobStore)
//! nor [`BlobStore`](crate::BlobStore), so a store of either face installs through it unchanged, and
//! the bound is spent where the store is actually USED. That is the stronger form of the same
//! guarantee: not two doors, but one that never had a mode to be wrong about.
//!
//! # What is NOT built here, and it is a seam rather than a decision
//!
//! The design has this door AUTO-INSTALLED where a launch creates the store through the compiler
//! path — a store opened by the emitted launch is a store the emission can register, so an
//! application that went through the compiler never writes the line. That half has nothing to attach
//! to yet: the emitted launch opens NO store of any kind today (it spends `Creation::node`,
//! `Creation::declared_resource` and `Creation::unwind`, and nothing that mints a slot), and there is
//! no path from a launch to a schema builder anywhere in this crate. When the emission opens
//! declared stores, this is the type it will install; until then every application installs its own,
//! which is what the hand-assembled road does in the finished design too.
use Arc;
// The two free walks below are the only items here that name an artifact family, and they ride the
// wire gate — so the imports do too, rather than the module carrying three names a build without
// async-graphql has nothing to spend them on.
use crate::;
/// WHERE an artifact family's addresses are resolved — the seam an application answers with its own
/// store.
///
/// # Object-safe, and unbounded on `S`
///
/// Object safety is forced by what the door is FOR: `ctx.data::<T>` is a `TypeId` lookup, so the key
/// has to be a concrete type and the openness has to live inside it behind a trait object.
///
/// `S` carries no bound NAMING A STORE FACE, and that is the mode-blindness the module note
/// describes made structural. Bounding it on [`AsyncBlobStore`](crate::AsyncBlobStore) would have shut the door
/// on every blocking-only backend the dual-mode birth order exists to make first-class; bounding it
/// on both would have demanded a face nobody needs in order to open a door. What `S` must be is
/// whatever the resolver that borrows it needs, asked at that resolver's own bound.
///
/// The one bound `S` does carry — `'static`, on the door rather than here — is a TRAIT OBJECT's own
/// requirement (`Arc<dyn BlobSource<S>>` is only well-formed where `S` outlives it) and not a
/// judgement about stores. It is also what `ctx.data` would have demanded anyway.
/// The SHIPPED provider: the store itself, held by [`BlobDoor::opened`].
///
/// # Why a private newtype and not a blanket `impl<S> BlobSource<S> for S`
///
/// [`SqlSource`](super::SqlSource) blankets over the CONCRETE `sqlx::Pool<Db>`, which is a targeted
/// impl wearing a generic's clothes. There is no single concrete store type here to do the same
/// over, so the honest translation would have been a blanket across ALL types — and that was
/// measured and rejected on two counts. It makes every `Send + Sync + 'static` type a source of
/// ITSELF, including `Arc<dyn BlobSource<S>>`, so `self.source.store()` inside the door resolves to
/// the Arc's own blanket impl rather than through it (`E0308`, found
/// `&Arc<dyn BlobSource<S>>` — the compiler said so before this note did). And it would foreclose a
/// downstream `impl<T: TheirMarker> BlobSource<TheirStore> for T`, which overlaps at
/// `T = TheirStore`.
///
/// The newtype has neither problem and costs nothing an application can observe: the store is MOVED
/// in, so there is still exactly one handle and nothing to go out of step with.
;
/// The DOOR a locate field takes from a request's context — one per store a schema serves.
///
/// Cloneable and cheap: the source is behind an [`Arc`], so installing a door costs a refcount rather
/// than an open.
/// Written out rather than derived, for the reason every parameterised handle in this crate writes
/// its own: a derive would bound `S: Clone`, which a connection-manager need not be — what is cloned
/// is the [`Arc`] around it.
/// Written out because a trait object carries no [`Debug`](core::fmt::Debug), and a connection-manager
/// is not a value worth printing. What a reader wants from this line is WHICH door it is, which the
/// store's own name answers.
/// THE WHOLE OF WHAT AN EMITTED LOCATE FIELD DOES — the door lookup, the suffix, and the address.
///
/// # Written here rather than in the emission, and the rule is the emitter's own
///
/// *A walk asked for twice is a walk two answers can disagree about.* Every located family's field
/// does exactly these three things in exactly this order, and an emitter that wrote them inline
/// would put one body per artifact position into every record's expansion — where a fix to the
/// refusal, to the order or to the borrow is a divergence rather than an edit. What the emission
/// keeps is what actually differs between two fields: the FAMILY, the WORD and the KEY.
///
/// # The door lookup is FIRST, ahead of the suffix
///
/// A request that is wrong in two ways reads the door's refusal, which is the one its operator can
/// act on: a schema missing an `install` line is a deployment fact, where a row outside its family's
/// fence is a data fact and the person who can fix it is someone else. The single query leg already
/// orders its two refusals this way and for this reason.
///
/// # ABSENCE COMES BACK AS A VALUE, and it is a different thing from every refusal below
///
/// [`None`] is the store saying *nothing is written there yet*, which is the ordinary state of an
/// artifact whose pipeline has not reached this entity — see
/// [`ArtifactStore::locate`](crate::ArtifactStore::locate), where each store draws that split for
/// itself. A bare position publishes it as `null`; a position whose declaration signed `required`
/// takes the other walk, [`locate_signed_artifact`], which is the one place absence becomes an
/// error.
///
/// # Errors
///
/// An unaddressed door — no [`BlobDoor`] onto this family's store is installed on the schema —
/// carries the family, the word it was mounted under and the store type, which are the three facts
/// an operator needs to know which line is missing. A row outside its family's fence carries
/// [`UnfencedSuffix`](crate::UnfencedSuffix)'s own sentence, and a store that could not answer where
/// the object is carries the backend's.
///
/// Both of the latter attach [`ErrorCode::UnreadableRow`](crate::ErrorCode::UnreadableRow), through
/// [`refused_row`](super::refused_row). It is the shared-word rule's second clause rather than a
/// borrowed name: that code is *the one code that is nobody's query* — a client cannot rewrite its
/// way past it — and a row whose address will not render is the same fact one layer over, asking the
/// same nothing of whoever sent the document.
/// THE SIGNED WALK — [`locate_artifact`], and then the author's own word spent on what came back.
///
/// A position that wrote `required` publishes a NON-NULL address, which is a promise about a
/// deployment: *by the time a client reads this row, the object is there*. The walk is the same walk
/// — one authority, one order, one set of refusals — and the whole of what the word adds is at the
/// end of it, where an [`Option`] the bare field publishes as `null` has nowhere to go inside a type
/// that cannot hold one.
///
/// # A SECOND ENTRY POINT rather than a flag on the first
///
/// The two positions differ in their RETURN TYPE, which no parameter can decide: the bare field
/// answers `Option<Location>` and the signed one answers `Location`. An emitter choosing between two
/// functions is making the choice it already made when it emitted the two signatures, where a
/// `required: bool` would have had both fields return one type and moved the fork into a branch
/// nobody can see from the field.
///
/// # Errors
///
/// Every refusal [`locate_artifact`] raises, and [`UnwrittenArtifact`] where the store answered that
/// there is no object — the refusal that exists only at a SIGNED spelling, on this road and on the
/// bytes road beside it ([`read_signed_artifact`]).
/// AN OBJECT THAT IS NOT THERE, at a position whose declaration signed for it.
///
/// The refusal quotes the WORD the author wrote, because that word is the whole reason this is an
/// error at all: the same store answering the same absence one position over is a `null`, and what
/// separates them is a promise somebody made in a declaration. So the sentence names the promise,
/// the position it was made at and the family it was made about — which is what turns *a field
/// failed* into *this signature is not true of this deployment*, the only form of it anybody can act
/// on.
///
/// # ONE refusal for BOTH store-mediated roads
///
/// The address's `required` and the bytes' `data(required)` sign the same promise about the same
/// object, so an absence at either is the same fact and reaches a client under the same sentence and
/// the same word. A second refusal type per road would have told a reader which FIELD noticed, which
/// is not something anybody can act on differently.
///
/// # It is the FRAMEWORK's own refusal, so it carries its own code
///
/// Unlike the two refusals beside it — a declarer's fence error and a backend's store error, both
/// reaching the wire through [`refused_row`](super::refused_row) because neither type may choose a
/// wire word — this one is minted here. So it answers [`ToErrorCode`](crate::ToErrorCode) itself,
/// which is that trait's own rule: the fact belongs to the type that has it.
/// THE WHOLE OF WHAT AN EMITTED DATA FIELD DOES — the door lookup, the suffix, the read, and the
/// encoding.
///
/// [`locate_artifact`]'s sibling, and deliberately its exact shape for that function's own reason: a
/// walk written twice is a walk two answers can disagree about. The same three acts in the same
/// order, with the READ where the render was — so a request wrong in two ways still reads the door's
/// refusal first, and a row outside its family's fence is still refused before any I/O happens.
///
/// # The BOUND is [`ArtifactData`], and it is the whole of what the two words buy
///
/// A position asks for bytes on the ENTITY, because a field's presence belongs to the expansion that
/// writes the `#[Object]` block. A family permits them on its OWN declaration, because whether an
/// object may travel inline is a fact about the objects. This bound is where the two meet: an ask
/// the family never permitted is `E0277` at the emitted field, carrying [`ArtifactData`]'s own
/// sentence — which names both roads, either one being a fix.
///
/// # ABSENCE COMES BACK AS A VALUE HERE TOO, and it is the address road's own sentence
///
/// [`None`] is the store saying *nothing is written there yet* — see
/// [`ArtifactData::read`](crate::ArtifactData::read), which is where the widening's reason is
/// written out. A bare position publishes it as `null`; a position whose declaration signed
/// `required` takes the other walk, [`read_signed_artifact`], and the two walks fork exactly where
/// the address's two do.
///
/// # Errors
///
/// Every refusal [`locate_artifact`] raises, and the store's own where the object cannot be read.
/// The last two attach [`ErrorCode::UnreadableRow`](crate::ErrorCode::UnreadableRow) through
/// [`refused_row`](super::refused_row), for that function's stated reason.
pub async
/// THE SIGNED READ — [`read_artifact`], and then the author's own word spent on what came back.
///
/// [`locate_signed_artifact`]'s twin one road over, and deliberately its exact shape: the walk is
/// the same walk, and the whole of what the word adds is at the end of it, where an [`Option`] the
/// bare field publishes as `null` has nowhere to go inside a type that cannot hold one.
///
/// A SECOND ENTRY POINT rather than a flag, for the address's own reason: the two positions differ
/// in their RETURN TYPE, which no parameter can decide.
///
/// # Errors
///
/// Every refusal [`read_artifact`] raises, and [`UnwrittenArtifact`] where the store answered that
/// there is no object — the one refusal that exists ONLY at this spelling. It is the SAME refusal
/// type the address road raises, which is what makes `required` mean one thing at both
/// store-mediated positions.
pub async
/// `bytes` as RFC 4648 §4 base64, padded — the encoding a GraphQL client reads binary out of.
///
/// # §4 and not the cursor's §5, and the split is what each one is for
///
/// A cursor is a URL query parameter and a header value, so [`cursor::text`](crate::cursor) writes
/// §5's URL-safe alphabet with no padding and refuses `=` coming back — two spellings of one cursor
/// being one too many. An inline object is a JSON string value read once by the client that asked
/// for it, and what every decoder on that side takes without being told is standard base64. Neither
/// is a default the other should inherit.
///
/// # Written rather than depended on, which is this crate's own precedent twice over
///
/// `store::fs` writes RFC 4648 base32 and `cursor::text` writes base64url, both for a rendering the
/// crate must be able to state exactly in both directions. This is the same thirty lines, and the
/// alternative is a dependency in the one build every wire face compiles.
/// The store an artifact family's addresses resolve against, out of the request's own context.
///
/// `data_opt` and a refusal of this seam's own rather than `data`'s, because the library's would
/// name the door type and stop. What a deployment reading this one is told is WHICH FAMILY went
/// looking, under WHICH WORD, and for WHICH STORE — and those three are what turn *a door is
/// missing* into *this `install` line is missing*.
///
/// # Errors
///
/// Where no [`BlobDoor`] onto `A::Store` is installed on the schema.