ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
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
//! The three facts a STORED composite states about itself, and the one authority all of them read:
//! how many columns a [`LanguageId`] spans, how those columns are bound out, and how they are read
//! back in.
//!
//! ```text
//!   SEGMENTS   language, script, region, rest    the width — a holder's INSERT list and DDL
//!   Carrier    ?, ?, ?, ?                        the bind — one placeholder per segment
//!   Assemble   read by NAME, four times          the decode — a transposition cannot typecheck away
//!   CursorValue  the canonical TAG               the keyset position, as text
//!   MongoCarrier  a SUB-DOCUMENT of the four     the same four names, nested rather than joined
//! ```
//!
//! # FOUR columns, and three of them are NULLABLE
//!
//! That is the difference from a multi-column value whose columns are all `NOT NULL`, and it is
//! what shapes the comparison next door: a whole-identity membership cannot be a row-value `IN`
//! here, because a row value compares `NULL` to `NULL` as unknown.
//!
//! The nullability is the type's own shape rather than a storage choice. A tag has a language or it
//! is not a tag; a script, a region and a tail are each declared or not, and `NULL` is the column
//! that says *not declared*. Storing an empty string instead would make *no script* and *a script
//! spelled `""`* one value, and would leave the filter's `isNull` test with nothing to test.
//!
//! # `_` between the segments is the BACKEND's, and the DDL has to agree
//!
//! An address carries a PATH rather than a name, so each column pushes one segment onto whatever it
//! was handed: an address at `spoken` reaches `spoken_language`, `spoken_script`, `spoken_region`
//! and `spoken_rest`, and the SAME comparison at the top level reaches the four bare names. The
//! separator is [`Backend::write_column`](crate::Backend::write_column)'s.
//!
//! Which is exactly why the MongoDB row below writes a SUB-DOCUMENT rather than four keys: that
//! backend's separator is `.` and its `.` is ADDRESSING rather than a character in a name, so the
//! same four segments reach `spoken.language` and its siblings — one shape, two spellings, and no
//! second list of names anywhere.
//!
//! # The decode CANONICALISES, and the cursor RE-VALIDATES
//!
//! Both go back through [`LanguageId`]'s own door, so a row written by something that is not this
//! crate is read as a value rather than trusted as one — and a forged page token is refused rather
//! than turned into an identity whose type says it cannot exist.

use core::fmt;

use crate::{ColumnKind, ColumnName, ColumnShape, CursorValue, FieldName, column::column_eq};

use super::{LanguageId, ParseLanguageIdError};
// The three seat types and the tail's door are named by `assembled` and by `document_seats`, so
// they ride the union of the two gates: a build with neither the SQL family nor this backend has no
// row that reads any of the four.
#[cfg(any(feature = "sqlx", feature = "mongo"))]
use super::tail;
#[cfg(any(feature = "sqlx", feature = "mongo"))]
use crate::primitives::lang::{Language, Region, ScriptSubtag};

#[cfg(test)]
mod tests;

/// The language column's segment — the name a frame pushes and a column carries.
///
/// `pub(crate)` rather than `pub(super)`, because the comparison next door addresses these columns
/// directly and reads the names from here rather than respelling them: one authority, at every
/// depth.
pub(crate) const LANGUAGE: &FieldName = FieldName::new("language");

/// The script column's segment.
pub(crate) const SCRIPT: &FieldName = FieldName::new("script");

/// The region column's segment.
pub(crate) const REGION: &FieldName = FieldName::new("region");

/// The tail column's segment.
pub(crate) const REST: &FieldName = FieldName::new("rest");

/// **The four columns an identity spans**, and the one authority every half of the crossing reads.
///
/// The names are the SEATS' own, not the wire's, because a column name is DDL a database already
/// holds while a field name is a schema commitment to a client. Here the two agree, there being no
/// shorter spelling of `language` worth having.
pub(super) const SEGMENTS: &[ColumnShape] = &[
  ColumnShape::Plain(ColumnName::of(LANGUAGE)),
  ColumnShape::Plain(ColumnName::of(SCRIPT)),
  ColumnShape::Plain(ColumnName::of(REGION)),
  ColumnShape::Plain(ColumnName::of(REST)),
];

/// **The STORAGE half of the width** — what a holder's row reads to know this field is four columns
/// and not one. It names no dialect, because a width has none.
impl ColumnKind for LanguageId {
  const SEGMENTS: &'static [ColumnShape] = SEGMENTS;
}

/// **One leaf, and it is the value.** A language identity means its four subtags in the sequence BCP-47 writes them.
impl crate::DeclaredLeaves for LanguageId {}

// A tag is one column value when its four seats are — which is what this type's own `PartialEq`
// already says: each seat folded to canonical case before it was filled, so the four columns and
// the four fields agree.
column_eq! { LanguageId }

/// **The DECLARED half — FOUR words, every one of them text's.**
///
/// The [`Carrier`](crate::Carrier) row binds the language as a `String` and the three optional seats
/// as `Option<String>`, and an optional column is declared at its VALUE's type — nullability is
/// carried BESIDE the word rather than in it — so all four take the dialect's word for text and what
/// separates the seats is `NULL`, not the type.
///
/// Reading `String`'s row rather than naming a word is what keeps MySQL's `varchar(255)` and
/// PostgreSQL's `text` out of this file: a dialect that changed how it stores text would move all
/// four of these columns at once, and there is no second spelling here to be forgotten.
impl<Db> crate::StoredAs<Db> for LanguageId
where
  String: crate::StoredAs<Db>,
{
  const WORDS: &'static [&'static str] = &[
    <String as crate::StoredAs<Db>>::WORDS[0],
    <String as crate::StoredAs<Db>>::WORDS[0],
    <String as crate::StoredAs<Db>>::WORDS[0],
    <String as crate::StoredAs<Db>>::WORDS[0],
  ];
}

/// Four columns do not hold a language identity, and this says why.
///
/// It is a DECODE error rather than a parse error and it still carries a parse error, which is not
/// a contradiction: nothing was spelled as a whole tag, so there is no separator to be missing — but
/// each column's own text still has to name its own subtag, and [`ParseLanguageIdError`] is what
/// says which one did not.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum LanguageIdColumnError {
  /// The language column is `NULL` where the other three may be. A tag has a language or it is not
  /// a tag, so the column that holds one cannot be absent while its siblings hold values — an
  /// identity that is absent ENTIRELY is an `Option<LanguageId>` and a row of four `NULL`s, which
  /// the framework's own nullable reading handles above this one.
  NoLanguage,
  /// A column's text does not name the subtag its position calls for.
  Subtag(ParseLanguageIdError),
}

impl fmt::Display for LanguageIdColumnError {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    match self {
      Self::NoLanguage => f.write_str("the stored language column must not be null"),
      Self::Subtag(refused) => write!(f, "a stored column does not name its subtag: {refused}"),
    }
  }
}

impl core::error::Error for LanguageIdColumnError {
  fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
    match self {
      Self::Subtag(refused) => Some(refused),
      Self::NoLanguage => None,
    }
  }
}

/// The four columns as one identity, or the reason they are not.
///
/// Shared by the two readers below — the row decode and the cursor — so that an identity arriving
/// from a database and one arriving from a client's page token are admitted by the same rule.
///
/// # Each column goes through its OWN door, and it is the column identity that makes that necessary
///
/// The tempting shape is to spell the four columns back into a tag and hand it to
/// [`LanguageId::new`], which is shorter and gets the canonical case right. It is also WRONG on
/// exactly the rows this decode exists for, and the reason is that the tag parser is POSITIONAL: it
/// reads a subtag's seat off its shape, and a rebuilt tag has thrown away which column each part
/// came out of.
///
/// Measured, on a row this crate did not write: a `script` column holding `US` rebuilds as `de-US`,
/// which the tag parser reads as a REGION — so a garbage script silently becomes a plausible region
/// and the row comes back as a value nobody stored. A `script` column holding `Latin` rebuilds as
/// `de-Latin`, which is five alphanumeric characters and rides the TAIL, so a malformed script is
/// carried as a variant rather than refused.
///
/// Reading each column through its own type's door keeps the seat a column fact. Every fold still
/// applies — `GER` in the language column is `de` — and the SUPPRESSION still fires, because
/// [`LanguageId::compose`] is what puts the four together and it applies the same rule the parser
/// does.
///
/// Behind `sqlx`, as its one caller is: a build with no SQL family has no row to decode, and the
/// gate is here rather than on the caller alone so a bare build compiles no line of it.
#[cfg(feature = "sqlx")]
fn assembled(
  language: &str,
  script: Option<&str>,
  region: Option<&str>,
  rest: Option<&str>,
) -> Result<LanguageId, LanguageIdColumnError> {
  let refused = LanguageIdColumnError::Subtag;

  let language = Language::new(language)
    .map_err(ParseLanguageIdError::Language)
    .map_err(refused)?;
  let script = script
    .map(ScriptSubtag::new)
    .transpose()
    .map_err(ParseLanguageIdError::ScriptSubtag)
    .map_err(refused)?;
  let region = region
    .map(Region::new)
    .transpose()
    .map_err(ParseLanguageIdError::Region)
    .map_err(refused)?;
  let rest = rest.map(tail).transpose().map_err(refused)?;

  Ok(LanguageId::compose(language, script, region, rest))
}

/// **The KEYSET position**: the canonical tag's UTF-8 bytes.
///
/// A TAG rather than four framed fields, and the framing is exactly why: three of the four columns
/// are variable-width text, so a concatenation of them would need a delimiter of its own — and a
/// cursor slot is already length-delimited by the layer above, which is the framing this row is
/// told not to add. The tag has separators the grammar defines, so it delimits itself.
///
/// It round-trips because the rendering and the parse are inverse over canonical text, and the read
/// RE-VALIDATES because a cursor is a string a CLIENT hands back.
impl CursorValue for LanguageId {
  fn write_cursor(&self, out: &mut Vec<u8>) {
    out.extend_from_slice(self.to_string().as_bytes());
  }

  fn read_cursor(bytes: &[u8]) -> Option<Self> {
    Self::new(core::str::from_utf8(bytes).ok()?).ok()
  }
}

/// **N BINDS OUT.** The engine's `VALUES` loop writes the comma between FIELDS; the commas between
/// this field's own four columns are these, because the count is this type's.
///
/// The three optional seats bind through `Option<String>`'s own row, which writes the `NULL`
/// keyword rather than a typed null — see the framework's note, where the reason is that PostgreSQL
/// infers a parameter's type from its bind and would refuse a `BOOL` null in a `TEXT` column.
#[cfg(feature = "sqlx")]
impl<Db> crate::Carrier<Db> for LanguageId
where
  Db: sqlx::Database,
  String: crate::Carrier<Db>,
  Option<String>: crate::Carrier<Db>,
{
  fn push_bind(&self, qb: &mut sqlx::QueryBuilder<Db>) {
    <String as crate::Carrier<Db>>::push_bind(&String::from(self.language().as_str()), qb);

    for part in [
      self.script().map(|script| String::from(script.as_str())),
      self.region().map(|region| String::from(region.as_str())),
      self.rest().map(|rest| String::from(rest.as_str())),
    ] {
      qb.push(", ");
      <Option<String> as crate::Carrier<Db>>::push_bind(&part, qb);
    }
  }
}

/// **THE DOCUMENT'S FORM: a SUB-DOCUMENT of the same four names, in the same order, with `null` in
/// every seat the tag did not fill.**
///
/// ```text
///   { "language": "zh", "script": "Hans", "region": "CN", "rest": null }
/// ```
///
/// # It NESTS where the table FLATTENS, and neither side chose that
///
/// [`MongoCarrier`](crate::MongoCarrier)'s own instant row states the asymmetry and the reason: a
/// composite is flattened into columns wherever a TABLE stores it and stays nested wherever a
/// DOCUMENT does, because SQL's namespace is flat and BSON's is not. `flatten` is a SQL family's
/// naming act — dropping a prefix only that family renders — and MongoDB's declaration block has no
/// such word at all, its default BEING the sub-document. So the four segments this file declares are
/// joined with `_` by [`Backend::write_column`](crate::Backend::write_column) and with `.` by
/// MongoDB's own path syntax, and an identity at `spoken` is reached as `spoken_language` in one
/// family and `spoken.language` in the other. **The SEGMENTS are the same segments** — this row reads
/// the four [`FieldName`]s above and spells nothing of its own, which is what keeps one authority.
///
/// # ALL FOUR KEYS ARE WRITTEN, and the absent seats hold `null` rather than being left out
///
/// MongoDB reads a missing field and a `null` field as one answer for a FIELD-level test — `{f: {$eq:
/// null}}` matches both — so for the null test alone the two spellings are the same. They are not the
/// same for anything else this value is, and three things decide it:
///
/// * **A WHOLE-IDENTITY equality is a document comparison**, and BSON compares two documents by their
///   keys in the order written. `{$eq: {language: "de"}}` and a stored `{language: "de", script:
///   null, region: null, rest: null}` are two different documents, so a carrier that omitted its
///   nulls would answer *no documents* against a writer that did not, and the two spellings are
///   invisible in the filter.
/// * **The ORDER is the seat order**, which is what a fixed key set buys: BSON ranks `Null` below
///   `String` in its own type order and compares field by field, so a document written by this row
///   compares by language, then script, then region, then tail — the same order [`LanguageId`]'s
///   derived [`Ord`](core::cmp::Ord) walks, absent sorting before present in both. It is read from
///   MongoDB's documented BSON order rather than measured here, the posture the register takes for
///   its `BinData` rows; nothing spends it today, the identity facet publishing no ordering words.
/// * **It is the SQL bind's own answer.** [`Carrier::push_bind`](crate::Carrier) below writes the
///   `NULL` keyword into every absent seat rather than pushing three columns instead of four, for a
///   reason that is the same reason at bottom: a value whose width varies with its content is a value
///   two writers can disagree about.
///
/// # What a DOCUMENT can hold is the narrower question, and this row does not answer it
///
/// This is the FILTER OPERAND's shape. The document's WRITE is serde's, and no storage type this
/// crate ships carries a serde row — so a declaration naming a bare [`LanguageId`] column under
/// `mongo(…)` is `E0277` at the declaration, exactly as [`Timestamp`](crate::Timestamp)'s row says a
/// bare instant is, and the escape is the same one: a `type = "…"` with its own conversions.
///
/// **`mediagraph` never had a MongoDB story for this family at all** — every storage face it shipped
/// was `sqlx`-gated — so the shape above is a decision taken here rather than a form carried over,
/// and it is written down for that reason.
#[cfg(feature = "mongo")]
impl crate::MongoCarrier for LanguageId {
  fn to_bson(&self) -> bson::Bson {
    /// One seat as the BSON it holds — the canonical text, or the `null` that says the tag did not
    /// fill this one.
    fn seat(held: Option<&str>) -> bson::Bson {
      held.map_or(bson::Bson::Null, |text| {
        bson::Bson::String(String::from(text))
      })
    }

    let mut tag = bson::Document::new();
    tag.insert(
      LANGUAGE.as_str(),
      bson::Bson::String(String::from(self.language().as_str())),
    );

    // The three optional seats, in the order `SEGMENTS` states them — which is the order a document
    // comparison reads, so the loop is the key order rather than a convenience.
    for (name, held) in [
      (SCRIPT, self.script().map(|script| script.as_str())),
      (REGION, self.region().map(|region| region.as_str())),
      (REST, self.rest().map(|rest| rest.as_str())),
    ] {
      tag.insert(name.as_str(), seat(held));
    }

    bson::Bson::Document(tag)
  }
}

/// The stored language seat is `null` or missing entirely — the one refusal [`document_seats`]
/// collapses two different BSON shapes into, mirroring [`LanguageIdColumnError::NoLanguage`].
///
/// The general law this vocabulary reads every OTHER field under —
/// [`MongoExtract`](crate::query::mongo::MongoExtract)'s own two-state reading — is that a missing
/// key and an explicit `Null` are one answer because the field MAY be absent. The language seat may
/// not: `LanguageId`'s own doc states "a tag with no language is not a tag." So the two arrivals
/// still collapse to ONE answer here, for the opposite reason — both name a tag this crate refuses
/// to hold, not a value it reads as `None`.
#[cfg(feature = "mongo")]
const NO_LANGUAGE: &str = "this field holds a language identity whose language key is null or missing, and a tag with no \
   language is not a tag";

/// The stored `rest` seat is a `string` that is not a variant, extension or private-use subtag —
/// [`tail`]'s own envelope, checked again on the way in exactly as `assembled` checks it on SQL's.
#[cfg(feature = "mongo")]
const TAIL: &str = "this field holds a tail that is not a variant, extension or private-use subtag";

/// **THE READ: a sub-document back into an identity, seat by seat** — [`MongoCarrier`]'s mirror,
/// and `assembled`'s own reason applied to this backend rather than SQL's.
///
/// # Each seat goes through ITS OWN door, for `assembled`'s own reason
///
/// The tempting shape is to read the four keys back into a tag string and hand it to
/// [`LanguageId::new`], and it is wrong for the reason `assembled`'s own doc gives: the tag parser
/// is POSITIONAL, and a rebuilt tag has thrown away which key each part came out of. So this reads
/// [`Language`], [`ScriptSubtag`] and [`Region`] each through their own `MongoExtract` row — which
/// is what keeps every fold applying and the suppression firing, through [`LanguageId::compose`]
/// rather than [`LanguageId::new`].
///
/// # The LANGUAGE key: missing-or-null is ONE refusal, named — see [`NO_LANGUAGE`]
///
/// # The three OPTIONAL seats delegate to `Option<T>`'s own blanket, unchanged
///
/// `script` and `region` may be absent, so a missing key and an explicit `Null` are one answer for
/// each — the SAME law [`NO_LANGUAGE`]'s doc names, applied here because it is the honest reading
/// as it is everywhere else, not because the case was overlooked. `Option<ScriptSubtag>`'s and
/// `Option<Region>`'s own blanket already read exactly that way, so delegating to them costs no new
/// logic. `rest` has no citizen of its own to delegate to, so it is read here directly through
/// [`tail`] — the SAME re-validating door `assembled` sends a stored tail column back through.
#[cfg(feature = "mongo")]
pub(crate) fn document_seats(
  held: &bson::Document,
) -> Result<LanguageId, crate::query::mongo::MongoTypeError> {
  use crate::query::mongo::{MongoExtract, MongoTypeError, alias};

  let language = match held.get(LANGUAGE.as_str()) {
    None | Some(bson::Bson::Null) => return Err(MongoTypeError::Range(NO_LANGUAGE)),
    found => Language::extract(found)?,
  };
  let script = Option::<ScriptSubtag>::extract(held.get(SCRIPT.as_str()))?;
  let region = Option::<Region>::extract(held.get(REGION.as_str()))?;
  let rest = match held.get(REST.as_str()) {
    None | Some(bson::Bson::Null) => None,
    Some(bson::Bson::String(text)) => {
      Some(tail(text).map_err(|_refused| MongoTypeError::Range(TAIL))?)
    }
    Some(other) => return Err(MongoTypeError::wrong_type("string", alias(other))),
  };

  Ok(LanguageId::compose(language, script, region, rest))
}

/// **THE WHOLE FIELD: `Option<&Bson>` down to a sub-document, or the refusal naming what arrived
/// instead** — the presence-and-type half [`document_seats`] does not do, so a bare `LanguageId`
/// field and one nested under `Option`'s own blanket both reach it the same way every other row in
/// this vocabulary does.
#[cfg(feature = "mongo")]
impl crate::query::mongo::MongoExtract for LanguageId {
  const BSON: &'static str = "object";

  fn extract(value: Option<&bson::Bson>) -> Result<Self, crate::query::mongo::MongoTypeError> {
    match value {
      Some(bson::Bson::Document(held)) => document_seats(held),
      Some(other) => Err(crate::query::mongo::MongoTypeError::wrong_type(
        Self::BSON,
        crate::query::mongo::alias(other),
      )),
      None => Err(crate::query::mongo::MongoTypeError::Absent),
    }
  }
}

/// **AND N COLUMNS BACK IN** — the bind above read the other way.
///
/// By NAME in all four cases, which is what a transposition cannot survive: every column is text, so
/// `script` and `region` read positionally would swap without a type error anywhere.
#[cfg(feature = "sqlx")]
impl<'a, R: sqlx::Row> crate::Assemble<'a, R> for LanguageId
where
  String: crate::Assemble<'a, R>,
  Option<String>: crate::Assemble<'a, R>,
{
  fn assemble(row: &'a R, under: Option<&crate::Path<'_>>) -> sqlx::Result<Self> {
    let language: Option<String> = crate::assembled(row, LANGUAGE, under)?;
    let script: Option<String> = crate::assembled(row, SCRIPT, under)?;
    let region: Option<String> = crate::assembled(row, REGION, under)?;
    let rest: Option<String> = crate::assembled(row, REST, under)?;

    let language = language.ok_or(LanguageIdColumnError::NoLanguage);
    let assembled = language.and_then(|language| {
      assembled(
        &language,
        script.as_deref(),
        region.as_deref(),
        rest.as_deref(),
      )
    });

    assembled.map_err(|refused| sqlx::Error::Decode(Box::new(refused)))
  }
}