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
//! The DECODE vocabulary: [`MongoExtract`], the BSON each storage type reads back out of, and the
//! [`field`] an emitted extraction calls once per column.
//!
//! # It is [`MongoCarrier`](crate::MongoCarrier) read backwards, row for row
//!
//! That table says what each storage type is WRITTEN as; this one says what it is read out of, and
//! the two are one encoding — `tests` round-trips every row through both, so a carrier that changed
//! its BSON arm without this file moving is a failing test rather than a document nothing can read.
//!
//! The rows are the ones a comparison OPERAND already has, which is not a coincidence: a filter
//! compares a stored value against an operand, so a type this crate can compare on is exactly a
//! type it can store, and a type it can store is one it must be able to read.
//!
//! # The two-state reading: a missing field IS a `null`
//!
//! [`extract`](MongoExtract::extract) takes `Option<&Bson>` rather than `&Bson`, and the blanket
//! over [`Option<T>`] is what spends it: `None` — the key is absent — and `Some(Bson::Null)` are
//! ONE answer, and that answer is [`None`].
//!
//! It is the RULED reading rather than a convenience, and MongoDB's query language is what rules
//! it: `{f: {$eq: null}}` matches a document whose `f` is null AND a document with no `f` at all,
//! and `$sort` orders a missing field exactly where it orders a null. So a decode that told the two
//! apart would carry a distinction no filter, no sort and no cursor over the same field can
//! express — and a page's keyset would compare against a value its own `$sort` disagreed with.
//!
//! A NON-optional type refuses both, and refuses them differently: an absent field is
//! [`MongoTypeError::Absent`] and a present `null` is a type mismatch naming `null`. Two sentences
//! for two situations a reader will want to tell apart, even though the query language will not.

use bson::{Bson, spec::BinarySubtype};

use super::{MongoExtractionError, MongoTypeError};
use crate::{BeI128, BeU64, BeU128, Count};

/// One storage type, read back out of the BSON this crate stores it as.
///
/// Public for the reason [`MongoCarrier`](crate::MongoCarrier) is: this is the surface a downstream
/// scalar or enum joins the storage vocabulary through, and a type with a row in both tables needs
/// nothing else from this crate to be stored, filtered on and read back.
///
/// # It takes an [`Option`], where the carrier takes `&self`
///
/// The asymmetry is the missing field. A write always has a value; a read may find nothing, and the
/// party that knows whether nothing is an answer is the TYPE — see the module note's two-state
/// reading. Handing `None` to the row rather than deciding above it is what keeps the decision in
/// one place per type instead of at every field of every emitted extraction.
pub trait MongoExtract: Sized {
  /// The BSON type ALIAS this row reads — `$type`'s own word, so a refusal and a query that would
  /// find the offending documents spell the type the same way.
  const BSON: &'static str;

  /// This value, out of the BSON a document held at some field, or [`None`] where the field is
  /// absent.
  ///
  /// # Errors
  ///
  /// [`MongoTypeError`] — absent where absence is no answer, a type mismatch, or a value the Rust
  /// type cannot hold.
  fn extract(value: Option<&Bson>) -> Result<Self, MongoTypeError>;
}

/// The value `document` holds at `name`, in the type the row's field carries — the ONE call an
/// emitted extraction makes per column, and the one place a refusal is given its field.
///
/// # Errors
///
/// [`MongoExtractionError`], naming `name` and carrying what the field held.
///
/// # Examples
///
/// ```
/// use bson::doc;
/// use ingraph::query::mongo::field;
///
/// let document = doc! { "_id": 7i64, "title": "a red car" };
///
/// assert_eq!(field::<i64>(&document, "_id"), Ok(7));
/// assert_eq!(field::<Option<String>>(&document, "caption"), Ok(None));
/// assert_eq!(
///   field::<i64>(&document, "title").unwrap_err().field(),
///   "title"
/// );
/// ```
pub fn field<T: MongoExtract>(
  document: &bson::Document,
  name: &'static str,
) -> Result<T, MongoExtractionError> {
  T::extract(document.get(name)).map_err(|cause| MongoExtractionError::new(name, cause))
}

/// The BSON type alias `value` carries — `$type`'s own vocabulary.
///
/// Written here rather than taken from [`bson::spec::ElementType`], which carries no [`Display`]
/// and whose [`Debug`] spells `EmbeddedDocument` where the query language says `object`. A refusal
/// that names a type a `$type` query cannot take is a refusal a reader cannot act on.
///
/// # `pub(crate)`, widened from `pub(super)` — a builtin that joins the vocabulary from OUTSIDE
/// this module still owes an honest refusal
///
/// [`MongoCarrier`](crate::MongoCarrier)'s own doc calls the trait a surface a downstream scalar
/// "joins... through," and [`MongoExtract`] is public for the same reason — but every row this
/// module writes itself could reach this function by being IN `query::mongo`, where the language
/// family's rows cannot: they live beside the type, in `primitives::lang`, which is where
/// `MongoCarrier` already joins from. A wrong-type refusal written there without this function
/// would have to invent its own spelling of BSON's vocabulary or fall back to a refusal that does
/// not name what was found — both of which are exactly what this function exists to make
/// unnecessary. Re-exported at [`query::mongo`](super)'s own root as `pub(crate) use
/// extract::alias;`, mirroring [`comparison::mongo`](crate::comparison::mongo)'s `Lookup`/`one_key`
/// and this family's own `subtag_citizen`: a submodule-private helper, surfaced crate-wide by name
/// rather than by widening the module path that holds it.
///
/// `pub(crate)` and not `pub`: nothing outside this crate implements `MongoExtract` today, so
/// nothing outside it has honest-refusal-naming needs this function has to answer. The day a
/// downstream crate joins the storage vocabulary the way the language family joins the comparison
/// one, this is the one line that widens again.
///
/// [`Display`]: core::fmt::Display
pub(crate) fn alias(value: &Bson) -> &'static str {
  match value {
    Bson::Double(_) => "double",
    Bson::String(_) => "string",
    Bson::Array(_) => "array",
    Bson::Document(_) => "object",
    Bson::Boolean(_) => "bool",
    Bson::Null => "null",
    Bson::RegularExpression(_) => "regex",
    Bson::JavaScriptCode(_) => "javascript",
    Bson::JavaScriptCodeWithScope(_) => "javascriptWithScope",
    Bson::Int32(_) => "int",
    Bson::Int64(_) => "long",
    Bson::Timestamp(_) => "timestamp",
    Bson::Binary(_) => "binData",
    Bson::ObjectId(_) => "objectId",
    Bson::DateTime(_) => "date",
    Bson::Symbol(_) => "symbol",
    Bson::Decimal128(_) => "decimal",
    Bson::Undefined => "undefined",
    Bson::MaxKey => "maxKey",
    Bson::MinKey => "minKey",
    Bson::DbPointer(_) => "dbPointer",
  }
}

/// A present value of the wanted alias, or the refusal that says what arrived instead.
fn present<'a>(value: Option<&'a Bson>, wanted: &'static str) -> Result<&'a Bson, MongoTypeError> {
  match value {
    Some(value) => Ok(value),
    None => Err(MongoTypeError::Absent),
  }
  .and_then(|value| match value {
    Bson::Null => Err(MongoTypeError::wrong_type(wanted, "null")),
    value => Ok(value),
  })
}

/// The mismatch for a value that arrived at the wrong BSON type, read off the value itself so no
/// row can name a type the document did not hold.
fn mismatch(wanted: &'static str, found: &Bson) -> MongoTypeError {
  MongoTypeError::wrong_type(wanted, alias(found))
}

/// The ABSENCE is one answer with a `null`, which is MongoDB's own reading rather than this crate's
/// — see the module note.
///
/// It is the only row here that answers for a missing field, and that is what makes every other row
/// able to refuse one: a declaration whose field may be absent says so in its type.
impl<T: MongoExtract> MongoExtract for Option<T> {
  const BSON: &'static str = T::BSON;

  #[inline]
  fn extract(value: Option<&Bson>) -> Result<Self, MongoTypeError> {
    match value {
      None | Some(Bson::Null) => Ok(None),
      value => T::extract(value).map(Some),
    }
  }
}

/// The rows, each naming the BSON arm its carrier writes — see the module note for the round trip
/// that holds the two tables together.
macro_rules! extracts {
  ($( $ty:ty : $bson:literal => |$value:ident| $read:expr ),+ $(,)?) => {
    $(
      impl MongoExtract for $ty {
        const BSON: &'static str = $bson;

        fn extract(value: ::core::option::Option<&Bson>) -> Result<Self, MongoTypeError> {
          let $value = present(value, $bson)?;
          $read
        }
      }
    )+
  };
}

/// A stored integer that does not fit the width the declaration named.
///
/// One sentence for every narrowing row, because it is one situation: BSON has two integer widths
/// and this crate stores six Rust widths in them, so a value written by another writer — or by an
/// older declaration — can be perfectly good BSON and too wide for the field.
const NARROW: &str = "this field holds an integer wider than the type the declaration named";

/// A stored blob whose length is not the fixed-width carrier's.
const WIDTH: &str = "this field holds a blob of the wrong length for the carrier stored here";

/// A stored double outside the domain invariant the type carries.
const DOMAIN: &str = "this field holds a value outside the range this type admits";

/// A stored `long` that is negative, which [`Count::to_signed`] never writes.
///
/// The one domain check in `extracts!`'s own table rather than a row of its own beside
/// [`Confidence`](crate::Confidence)'s and [`Timestamp`]'s: a cardinality shares `i64`'s BSON arm
/// exactly, so the row differs from `i64`'s by this one guard and nothing about its shape.
const NEGATIVE: &str = "this field holds a negative value, and a cardinality is never negative";

extracts! {
  bool: "bool" => |v| match v {
    Bson::Boolean(value) => Ok(*value),
    other => Err(mismatch("bool", other)),
  },
  i32: "int" => |v| match v {
    Bson::Int32(value) => Ok(*value),
    other => Err(mismatch("int", other)),
  },
  i64: "long" => |v| match v {
    Bson::Int64(value) => Ok(*value),
    other => Err(mismatch("long", other)),
  },
  // **A CARDINALITY, READ BACK THROUGH `Count::from_signed`** — the same authority
  // `Count::to_signed` writes through, so the value a MongoDB filter compares and the value a
  // SQLite column holds are produced by one function on both ends of the crossing.
  //
  // The narrowing that writes one SATURATES and has no negative arm, so a negative `long` is a row
  // this code did not write: a hand-edited database, a column shared with something else, a bit
  // flip. It is refused BY NAME — [`NegativeCount`](crate::NegativeCount), mirroring the SQL
  // decode's own `Count::from_signed(stored).map_err(sqlx::error::BoxDynError::from)` — rather than
  // reinterpreted or clamped to zero, which would answer a question nobody asked and leave no trace.
  Count: "long" => |v| match v {
    Bson::Int64(value) => Count::from_signed(*value).map_err(|_| MongoTypeError::Range(NEGATIVE)),
    other => Err(mismatch("long", other)),
  },
  f64: "double" => |v| match v {
    Bson::Double(value) => Ok(*value),
    other => Err(mismatch("double", other)),
  },
  String: "string" => |v| match v {
    Bson::String(value) => Ok(value.clone()),
    other => Err(mismatch("string", other)),
  },
  Vec<u8>: "binData" => |v| match v {
    Bson::Binary(binary) if binary.subtype == BinarySubtype::Generic => Ok(binary.bytes.clone()),
    other => Err(mismatch("binData", other)),
  },
}

/// The NARROWING integer rows: three widths share BSON's `Int32` and one is stored in `Int64`, so
/// each of them reads the wider value and checks the fit.
///
/// The check is not decoration. `Int32` is what `i8`, `i16`, `u8` and `u16` are written as, so a
/// document written by anything else — another driver, an older declaration, a migration — can hold
/// a legal `Int32` this field cannot take, and a silent truncation would put a different value in
/// the record than the one that was stored.
macro_rules! narrowing {
  ($( $ty:ty : $wide:ty : $bson:literal => $arm:path ),+ $(,)?) => {
    $(
      impl MongoExtract for $ty {
        const BSON: &'static str = $bson;

        fn extract(value: ::core::option::Option<&Bson>) -> Result<Self, MongoTypeError> {
          match present(value, $bson)? {
            $arm(value) => <$ty>::try_from(*value).map_err(|_| MongoTypeError::Range(NARROW)),
            other => Err(mismatch($bson, other)),
          }
        }
      }
    )+
  };
}

narrowing! {
  i8: i32: "int" => Bson::Int32,
  i16: i32: "int" => Bson::Int32,
  u8: i32: "int" => Bson::Int32,
  u16: i32: "int" => Bson::Int32,
  u32: i64: "long" => Bson::Int64,
}

/// `f32` is stored as BSON's only binary float, which is 64-bit, so the read back is a NARROWING
/// exactly as the integer rows are — and it is checked the same way rather than truncated.
///
/// The check is the round trip: a `f64` that came from a `f32` widens exactly, so narrowing it and
/// widening it again is the identity. Anything else was written as a `double` by something that was
/// not this carrier, and rounding it into the record would store a value the document does not
/// hold. `NaN` is admitted deliberately — it survives both directions and is a value a `f32` column
/// can legitimately carry — which is why the comparison is written on the narrowed pair rather than
/// with `==` on the originals.
impl MongoExtract for f32 {
  const BSON: &'static str = "double";

  fn extract(value: Option<&Bson>) -> Result<Self, MongoTypeError> {
    match present(value, Self::BSON)? {
      Bson::Double(value) => {
        let narrowed = *value as Self;
        if f64::from(narrowed).to_bits() == value.to_bits() {
          return Ok(narrowed);
        }
        Err(MongoTypeError::Range(NARROW))
      }
      other => Err(mismatch(Self::BSON, other)),
    }
  }
}

/// A [`Score`] is a `f32` with a `[0.0, 1.0]` invariant, and the invariant is the DOMAIN's rather
/// than the column's — so the read is the `f32` row's followed by the constructor that checks it.
///
/// Refusing rather than clamping, for the reason every crossing in this crate refuses: a score
/// outside the range is a document written by something that did not hold this invariant, and
/// clamping would put a value in the record that nothing ever stored.
impl<S: crate::ConfidenceCarrier + MongoExtract> MongoExtract for crate::Confidence<S> {
  const BSON: &'static str = <S as MongoExtract>::BSON;

  fn extract(value: Option<&Bson>) -> Result<Self, MongoTypeError> {
    Self::new(S::extract(value)?).ok_or(MongoTypeError::Range(DOMAIN))
  }
}

/// The BIG-ENDIAN carriers: a fixed-width generic `BinData`, read through the carrier's own
/// `from_blob`.
///
/// The codec is the carrier's at both ends — `to_blob` writes and `from_blob` reads — so the eight
/// or sixteen bytes have ONE author, and a row spelling `from_be_bytes` itself would agree today
/// and be free to stop.
macro_rules! blobs {
  ($( $ty:ty ),+ $(,)?) => {
    $(
      impl MongoExtract for $ty {
        const BSON: &'static str = "binData";

        fn extract(value: ::core::option::Option<&Bson>) -> Result<Self, MongoTypeError> {
          match present(value, Self::BSON)? {
            Bson::Binary(binary) if binary.subtype == BinarySubtype::Generic => {
              <$ty>::from_blob(&binary.bytes).ok_or(MongoTypeError::Range(WIDTH))
            }
            other => Err(mismatch(Self::BSON, other)),
          }
        }
      }
    )+
  };
}

blobs!(BeU64, BeU128, BeI128);

/// A stored sub-document whose two integers are not the pair an instant is written as.
///
/// One sentence for both halves of that, because a reader can act on neither differently: a `nanos`
/// past a whole second and a pair whose signs disagree are both values this carrier never wrote,
/// and the answer to each is that the document holds something else.
const INSTANT: &str = "this field holds a `secs` and `nanos` pair that is not an instant";

/// **The framework's own instant, read back out of the two flat integers its carrier wrote.**
///
/// `object`, because the pair is a sub-document — see [`MongoCarrier`](crate::MongoCarrier)'s row
/// for why a composite nests here and flattens in a table, and for the licence that makes this row
/// exist at all beside the `Temporal` refusal.
///
/// The recomposition is [`from_parts`](crate::Timestamp::from_parts)'s, which is the SAME call the
/// SQL family's [`Assemble`](crate::Assemble) row makes: a pair that jiff would have NORMALISED is
/// refused rather than resolved, so one document and one row cannot disagree about which pairs are
/// instants. What differs between the two families is only the vocabulary the refusal is spoken in.
///
/// Each part is read at ITS OWN BSON type rather than through the `i64` and `i32` rows above, which
/// is the shape the derive corpus's composite takes too: those rows answer for a whole FIELD, and
/// these two integers are parts of one.
impl MongoExtract for crate::Timestamp {
  const BSON: &'static str = "object";

  fn extract(value: Option<&Bson>) -> Result<Self, MongoTypeError> {
    let held = present(value, Self::BSON)?;
    let Bson::Document(held) = held else {
      return Err(mismatch(Self::BSON, held));
    };
    let (Some(Bson::Int64(second)), Some(Bson::Int32(nanosecond))) = (
      held.get(crate::primitives::timestamp::SECOND.as_str()),
      held.get(crate::primitives::timestamp::NANOSECOND.as_str()),
    ) else {
      return Err(MongoTypeError::Range(INSTANT));
    };
    crate::Timestamp::from_parts(*second, *nanosecond).map_err(|_| MongoTypeError::Range(INSTANT))
  }
}

/// A stored pattern that the `regex` this build carries will not compile.
///
/// It is a `Range` rather than a vocabulary of its own, and the placement is that variant's own
/// sentence read literally: the field is at the right BSON type and holds *a value this Rust type
/// cannot take*. What makes a pattern the first such value the module note did not foresee is that
/// reading one is a PARSE — the note's *BSON is self-describing, so there is no parse to fail* is
/// true of every other row here and false of this one, the automaton being a build product of the
/// text rather than anything the document holds.
///
/// # The `regex::Error` itself is a recorded DOOR, and the cost is [`Eq`]
///
/// The SQL read lane carries the compiler's own words — [`PatternColumnError`] wraps a
/// `regex::Error` and says *the stored pattern does not compile: …* — and this road cannot without
/// [`MongoTypeError`] giving up `Eq`, which `regex::Error` does not implement and which this crate's
/// public refusal has always had. So the mongo road names the SITUATION and the SQL road names the
/// FAULT, the asymmetry is written here rather than hidden, and closing it is a decision about a
/// published derive rather than a row.
///
/// [`PatternColumnError`]: crate::PatternColumnError
#[cfg(feature = "regex")]
const PATTERN: &str = "this field holds text that is no longer a pattern this build can compile";

/// **THE PATTERN, READ BACK OUT OF THE TEXT ITS CARRIER WROTE** — the read half of the row at
/// [`MongoCarrier`](crate::MongoCarrier), and the last face a pattern column needed to cross MongoDB
/// in both directions.
///
/// `string`, because that is the arm the carrier writes: a pattern is stored as a VALUE and
/// deliberately not as BSON's own `Bson::RegularExpression`, which is an OPERATOR's type carrying a
/// pattern and an options string a `regex::Regex` has no field for. See the carrier row's note.
///
/// # The read does real WORK, which no other row here does
///
/// Every other extraction moves a value the document already holds into the shape the field wants.
/// This one COMPILES, so it can fail where the write could not: `Regex::new` is the inverse of
/// `Regex::as_str` only over the texts THIS build's `regex` admits, and a document written by
/// another writer, by an older build, or by a hand can hold text that is perfectly good BSON and no
/// longer a pattern. That is a refusal naming the field, exactly as the SQL road's is — never a
/// panic, and never a pattern quietly replaced by one that matches nothing.
#[cfg(feature = "regex")]
impl MongoExtract for regex::Regex {
  const BSON: &'static str = "string";

  fn extract(value: Option<&Bson>) -> Result<Self, MongoTypeError> {
    match present(value, Self::BSON)? {
      Bson::String(text) => Self::new(text).map_err(|_| MongoTypeError::Range(PATTERN)),
      other => Err(mismatch(Self::BSON, other)),
    }
  }
}

#[cfg(test)]
mod tests;