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
//! The bytes comparison: [`MongoBytesComparison`], the shape fact its ordering operators rest on,
//! and the two refusals the crossing owns.

use core::convert::Infallible;

use super::{Mongo, MongoCarrier, MongoOperator, field_path, membership};
use crate::{
  BytesFilter, FixedBytesFilter, TryMapFilter,
  comparison::{At, Backend, ComplexComparison, ToDatabaseComparison, TryFromFilter},
  graphql::filter::{ByteOperands, ByteSlots},
};

/// **WHICH OF THIS BACKEND'S TWO REFUSALS A BYTE FILTER HAS EARNED**, read off the filter BEFORE its
/// operands convert.
///
/// # BSON does not order binary values the way the SQL family does
///
/// MongoDB compares `BinData` by LENGTH first, then by the one-byte SUBTYPE, then byte by byte.
/// SQLite's `BLOB`, Postgres's `BYTEA` and MySQL's `VARBINARY` compare byte by byte and settle a
/// prefix by length LAST. The two orders therefore disagree the moment two operands differ in
/// length: `x'FF'` is greater than `x'0000'` on every dialect in the SQL family and less than it
/// here, from a filter that spells one `gt`.
///
/// A [`FixedBytesFilter`] column holds the first two fields of MongoDB's order constant. Every value
/// is exactly `N` bytes, and every blob [`MongoCarrier`] writes carries the generic subtype —
/// decided once, in `carrier`, for exactly this reason — so what is left to compare IS the bytes,
/// and the answer agrees with the SQL family's. A [`BytesFilter`] column holds neither constant, so
/// its ordering operators are refused at the crossing rather than rendered.
///
/// That is not a new ruling. It is the one `carrier`'s big-endian rows already rest on — the
/// property that lets a [`BeU64`](crate::BeU64) column answer `$lt` at all — and
/// `legacy/ingraph`'s `store::encode` states it from above both families with the same
/// qualification, that a `BinData` comparison is the bytewise one *of equal length*. What is new is
/// that the KIND decides it, where legacy's MongoDB lowering rendered `$gt` for both and so
/// contradicted its own codec note.
///
/// # It was a `BYTEWISE` const on a shape marker, and the census said the axis it rode on was dead
///
/// The two facts a byte column's width used to state lived on two traits: `BytesShape::SUBSTRING`,
/// the SQL family's *has this column a substring FORM*, and `MongoBytesOrder::BYTEWISE`, this
/// family's *is `$gt` over it the comparison every other backend gives*. They partitioned the same
/// two markers and they partitioned them the OTHER WAY UP — a blob had the substring form and not
/// the order, a hash had the order and not the form — which is why they were two traits and never
/// one const read twice.
///
/// The type split settles the SQL half by construction: a fixed filter has no substring field, so
/// nothing is left to refuse and `BytesShape` retires with the parameter that carried it. This half
/// does NOT settle the same way, and that is the census result rather than an oversight: MongoDB
/// refuses a substring match at EVERY width — it has no binary substring form at all — and refuses
/// ordering on a blob at every reading. Both are facts about OPERANDS THIS REQUEST SET, so both stay
/// values; what the split removes is the const, not the check.
///
/// So the fact stays where it was and changes what it is keyed on: a trait of MongoDB's own,
/// implemented per byte KIND instead of per shape marker. [`MongoCarrier`] is `Carrier`'s twin for
/// the same reason — a fact lives with the family it is true of.
///
/// `pub(crate)`, where `MongoBytesOrder` was public: a shape marker was a type a declaring crate
/// could mint, and a byte KIND is not. See [`MongoBytesComparison::try_from_filter_with`] for how a
/// declaring crate's own minted filter reaches this row anyway.
pub(crate) trait MongoByteRefusal {
  /// The operator this filter sets that MongoDB cannot answer over this kind of byte column, or
  /// [`None`] when every set operator has an answer.
  fn refused<E>(&self) -> Option<MongoBytesCrossingError<E>>;
}

impl<B, I> MongoByteRefusal for BytesFilter<B, I> {
  fn refused<E>(&self) -> Option<MongoBytesCrossingError<E>> {
    for (operand, operator) in [
      (self.contains(), "contains"),
      (self.not_contains(), "not_contains"),
    ] {
      if operand.is_some() {
        return Some(MongoBytesCrossingError::Substring(operator));
      }
    }
    for (operand, operator) in [
      (self.gt(), "gt"),
      (self.gte(), "gte"),
      (self.lt(), "lt"),
      (self.lte(), "lte"),
    ] {
      if operand.is_some() {
        return Some(MongoBytesCrossingError::VariableOrdering(operator));
      }
    }
    None
  }
}

/// A fixed-width column earns NEITHER refusal, and it earns neither for two different reasons: it
/// has no substring field to set, and its `BinData` order IS the bytewise one. So the answer is a
/// constant, and the eight operators this kind can express are the eight this backend answers.
impl<B, const N: usize, I> MongoByteRefusal for FixedBytesFilter<B, N, I> {
  #[inline]
  fn refused<E>(&self) -> Option<MongoBytesCrossingError<E>> {
    None
  }
}

/// Why a byte filter's operands did not become storage values.
///
/// The SQL family has no such type any more — the split left its one refusal with nothing to refuse
/// — and this one keeps two, because neither is about a WIDTH the type system now carries: MongoDB
/// has no binary substring form at any width, and a blob's ordering disagrees with every other
/// backend's at every reading.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MongoBytesCrossingError<E> {
  /// An operand did not convert into the column's storage type — the converter's own error, the
  /// same one every other kind in this family reports directly.
  Operand(E),
  /// A byte-substring match, named here by its operator (`"contains"` / `"not_contains"`).
  ///
  /// Reachable from a [`BytesFilter`] alone, and not because a fixed column is allowed one: a
  /// [`FixedBytesFilter`] has no such field, so the operand this variant names cannot exist there.
  /// See [`MongoBytesComparison`] for what MongoDB's only substring question actually reads.
  Substring(&'static str),
  /// An ordering operator on a variable-width column, named here by its operator (`"gt"`, `"gte"`,
  /// `"lt"`, `"lte"`).
  ///
  /// The order BSON would answer it in is not the one the same filter gets on any other backend —
  /// see [`MongoByteRefusal`] — and a differently-ordered result set is a wrong answer reported as
  /// a right one, where a refusal says so.
  VariableOrdering(&'static str),
}

impl<E: core::fmt::Display> core::fmt::Display for MongoBytesCrossingError<E> {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    match self {
      Self::Operand(error) => error.fmt(f),
      Self::Substring(operator) => write!(
        f,
        "operator {operator:?} is a byte-substring match, and MongoDB's only substring form reads a \
         string rather than binary data"
      ),
      Self::VariableOrdering(operator) => write!(
        f,
        "operator {operator:?} orders a variable-width binary column, which MongoDB compares by \
         length before bytes and this crate will not answer approximately"
      ),
    }
  }
}

impl<E: std::error::Error + 'static> std::error::Error for MongoBytesCrossingError<E> {
  fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
    match self {
      Self::Operand(error) => Some(error),
      Self::Substring(_) | Self::VariableOrdering(_) => None,
    }
  }
}

mongo_comparison_kind! {
  /// A [`BytesFilter`]'s storage-side twin: the eight operators BSON can answer over a binary
  /// column, over the type this database stores it as.
  ///
  /// # It is EIGHT slots where the filter has TEN, and the absence is the refusal
  ///
  /// `contains` and `not_contains` are byte-substring matches, and MongoDB has no form for one at
  /// any width. `$regex` is the only substring question it asks and it reads a STRING: a pattern
  /// matched against a `BinData` field matches no document, so rendering one would answer *no
  /// rows* to a question that was never asked — the same wrong-result-reported-as-right hazard
  /// [`text_regex`](super::text_regex)'s escaping exists to close, arrived at from the other side.
  ///
  /// So the storage side has no slot to hold one. That is the earliest place the refusal can
  /// stand: the crossing declines the two operators by name, and no lowering — this one or a
  /// later one — can reach them at all. `legacy/ingraph` refused the same pair while RENDERING,
  /// which is what a backend does when the type it renders from still carries them.
  ///
  /// The SQL twin keeps both slots because three of its dialects answer them on a blob, and it is
  /// the SHAPE that decides there. Here the shape decides nothing about them.
  ///
  /// The absence is visible from outside (`E0599`):
  ///
  /// ```compile_fail,E0599
  /// use ingraph::comparison::mongo::MongoBytesComparison;
  ///
  /// let comparison = MongoBytesComparison::<Vec<u8>>::new();
  /// let _ = comparison.contains();
  /// ```
  ///
  /// Its twin, which must COMPILE — stable rustdoc runs a `compile_fail` block just far enough to
  /// see it fail and never checks why, so the pair shares its call shape and one half has to be
  /// positive:
  ///
  /// ```
  /// use ingraph::comparison::mongo::MongoBytesComparison;
  ///
  /// let comparison = MongoBytesComparison::<Vec<u8>>::new();
  /// let _ = comparison.eq();
  /// ```
  ///
  /// # The ordering four ARE slots, because one byte kind answers them
  ///
  /// A fixed-width column's `$gt` is the bytewise comparison every other backend gives; a blob's is
  /// not. [`MongoByteRefusal`] is where the length-first rule and what it costs a blob are written
  /// down, and [`try_from_filter_with`](Self::try_from_filter_with) is the single gate that reads
  /// it.
  ///
  /// # ONE parameter, and the SQL twin has stopped carrying two
  ///
  /// `SqlBytesComparison<V, K, Db>` named a shape because its gate was an INHERENT method reading
  /// `K::SUBSTRING`, and an inherent method may only name its own type's parameters. That gate is
  /// gone, so that parameter is gone: both families now take the width off the FILTER's type and
  /// keep it off the comparison's, where nothing downstream of a crossing ever read one.
  MongoBytesComparison {
    one { eq, ne, gt, gte, lt, lte }
    many { in_, not_in }
  }
}

impl<V> MongoBytesComparison<V> {
  /// Cross a byte filter into this comparison, converting each operand with `f`.
  ///
  /// The entry point a DECLARED converter uses (`mongo(into = …)`), and the ONE gate on
  /// the operators this backend cannot answer. The trait crossings below reach the same gate with
  /// the storage type's own [`TryFrom`] in place of `f`.
  ///
  /// The refusals are checked BEFORE the operands convert, for the reason the whole family checks
  /// its own first: an operator with no answer has none whatever the operands would have turned
  /// into, so the error names the operator and never the conversion.
  ///
  /// # The parameter is a BOUND, and the normalisation is what buys that order
  ///
  /// `X` is anything whose operands map — which is the two byte kinds and any MINTED element filter
  /// over either, the row `ingraph-codegen`'s element door emits. Naming one filter type here is
  /// what used to make a minted filter `E0308` at an expansion its author cannot edit.
  ///
  /// A BOUND cannot be asked which operators a request set, so the input is first mapped through
  /// the converter that changes nothing (`Ok`), which lands it on the framework kind carrying
  /// [`MongoByteRefusal`] — a minted filter's `Mapped` at *stored = subject* IS that kind. What it
  /// costs is one rebuilt list per SET membership slot, on the declared-converter path alone: the
  /// two identity crossings below hand the framework kind straight to the gate. What it buys is the
  /// refusal ORDER above, unchanged — checking after the map would make an operand's failure win
  /// over an operator that had no answer either way.
  ///
  /// # Errors
  ///
  /// [`MongoBytesCrossingError::Substring`] when `contains` or `not_contains` is set;
  /// [`MongoBytesCrossingError::VariableOrdering`] when a blob's ordering operator is set;
  /// [`MongoBytesCrossingError::Operand`] when `f` refuses an operand. A fixed-width filter earns
  /// neither refusal — see [`MongoByteRefusal`].
  // SEALED, deliberately, for the reason the SQL twin's entry records: both bounds are
  // `pub(crate)`, so any crate may SATISFY them and none may add an implementor. Which operators
  // MongoDB declines is this family's answer about ITS OWN backend, not a seam a declaring crate
  // has anything to say into.
  #[allow(private_bounds)]
  pub fn try_from_filter_with<D, E, F, X, M>(
    filter: X,
    f: F,
  ) -> Result<Self, MongoBytesCrossingError<E>>
  where
    X: TryMapFilter<D, D, Mapped = M>,
    M: MongoByteRefusal + TryMapFilter<D, V, Mapped: ByteSlots<V>>,
    F: FnMut(D) -> Result<V, E>,
  {
    let filter = match filter.try_map_filter(Ok::<D, Infallible>) {
      Ok(filter) => filter,
      Err(never) => match never {},
    };
    Self::crossed(filter, f)
  }

  /// The gate itself, over a framework byte kind: refuse, then convert, then gather.
  fn crossed<D, E, F, M>(filter: M, f: F) -> Result<Self, MongoBytesCrossingError<E>>
  where
    M: MongoByteRefusal + TryMapFilter<D, V, Mapped: ByteSlots<V>>,
    F: FnMut(D) -> Result<V, E>,
  {
    if let Some(refusal) = filter.refused() {
      return Err(refusal);
    }
    let stored = filter
      .try_map_filter(f)
      .map_err(MongoBytesCrossingError::Operand)?
      .byte_operands();
    // The two substring slots are not carried across, and the refusal above is what makes that a
    // proof rather than a drop: a blob setting one never reaches here, and a fixed-width column has
    // no such field to have set.
    Ok(Self::from_operands(stored))
  }

  /// The eight slots this backend holds, out of the ten a byte filter's gather carries.
  fn from_operands(operands: ByteOperands<V>) -> Self {
    Self {
      eq: operands.eq,
      ne: operands.ne,
      gt: operands.gt,
      gte: operands.gte,
      lt: operands.lt,
      lte: operands.lte,
      in_: operands.in_,
      not_in: operands.not_in,
    }
  }
}

/// One backend, so one row — and the header naming [`Mongo`] concretely is what keeps it from
/// overlapping the SQL one, for the coherence reason
/// [`MongoScalarComparison`](super::MongoScalarComparison)'s row records.
///
/// The bound is the LOWERING's and it is exactly the carrier. Nothing here derives a value from an
/// operand the way a `LIKE` pattern or a `$regex` does, so a byte column asks for no
/// `AsRef<[u8]>` — the one bound [`MongoTextComparison`](super::MongoTextComparison)'s row carries
/// that this does not, and the same place the SQL family's three bytes impls land.
///
/// The WIDTH is not stated here. What decides a refusal is the crossing's bound rather than the
/// lowering's, and the crossing is deliberately not an item bound on this map — see
/// [`ToDatabaseComparison`] for why that promise cannot travel with the projection.
impl<D, V: MongoCarrier, I> ToDatabaseComparison<V, Mongo> for BytesFilter<D, I> {
  type Comparison = MongoBytesComparison<V>;
}

/// The fixed kind's row, and it lands on the SAME comparison — a storage side reads no width.
impl<D, V: MongoCarrier, const N: usize, I> ToDatabaseComparison<V, Mongo>
  for FixedBytesFilter<D, N, I>
{
  type Comparison = MongoBytesComparison<V>;
}

/// The BLOB's crossing with no declared converter: the storage type's own [`TryFrom`].
///
/// Its error is [`MongoBytesCrossingError`], so the identity crossing reaches
/// [`Infallible`](core::convert::Infallible) in the [`Operand`](MongoBytesCrossingError::Operand)
/// half alone: `MongoBytesCrossingError<Infallible>` keeps two inhabited variants, because neither
/// refusal has anything to do with converting.
///
/// It calls the GATE rather than the public entry, so the identity path pays nothing for the
/// normalisation that entry's bound needs.
impl<D, V: TryFrom<D>, I> TryFromFilter<BytesFilter<D, I>> for MongoBytesComparison<V> {
  type Error = MongoBytesCrossingError<V::Error>;

  fn try_from_filter(filter: BytesFilter<D, I>) -> Result<Self, Self::Error> {
    Self::crossed(filter, V::try_from)
  }
}

/// The FIXED kind's identity crossing, and its error is the CONVERTER's.
///
/// That is the split stated where a type can be read: a fixed-width column has no substring field
/// and its `BinData` order is the bytewise one, so this backend has nothing to refuse it and the
/// error says so — `V::Error` at [`Infallible`](core::convert::Infallible) is a crossing that
/// provably cannot fail. Its blob twin above cannot make that claim and does not.
///
/// The body is not the gate's, and the reason is exactly that honesty: reaching the gate would give
/// back a `MongoBytesCrossingError` with two variants this kind can never inhabit, and unwrapping
/// them here would be an `unreachable!` where the type system already knows better.
impl<D, V: TryFrom<D>, const N: usize, I> TryFromFilter<FixedBytesFilter<D, N, I>>
  for MongoBytesComparison<V>
{
  type Error = V::Error;

  fn try_from_filter(filter: FixedBytesFilter<D, N, I>) -> Result<Self, Self::Error> {
    Ok(Self::from_operands(
      filter.try_map(V::try_from)?.byte_operands(),
    ))
  }
}

/// The bytes kind answers here for the reason it does in the SQL family — a `BinData` `$eq` is
/// bitwise, so the collapse's assumption about two columns comparing alike is the one a byte column
/// cannot get wrong — and the refusal that costs a blob its ORDERING operators costs this nothing:
/// [`MongoByteRefusal`] is a question about `$gt`, and `$gt` is not a shape a foreign key may carry
/// under any backend.
impl<V> crate::comparison::ReferentialComparison<Mongo> for MongoBytesComparison<V> {
  #[inline]
  fn is_referential(&self) -> bool {
    Self::conjuncts(self) == 1 && (self.eq.is_some() || self.in_.is_some())
  }
}

/// The eight operators map one-to-one onto `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in` and
/// `$nin`, and the walk is the scalar kind's — see it for the two places that mapping is not the
/// identity it looks like, and for why the field path is rendered once.
///
/// # It asks nothing about which byte kind filled it, and that is the single-gate rule
///
/// An operator this backend cannot answer never reaches a comparison, because the crossing is the
/// only way to set one and it refuses. A second check here would be a second place for the two to
/// disagree — the same rule the SQL family's bytes walk states, where there is no longer anything
/// to check at all.
impl<V: MongoCarrier> ComplexComparison<Mongo> for MongoBytesComparison<V> {
  #[inline]
  fn conjuncts(&self) -> usize {
    Self::conjuncts(self)
  }

  fn apply<'q>(
    &'q self,
    at: At<'_>,
    mut builder: <Mongo as Backend>::Builder<'q>,
  ) -> Result<<Mongo as Backend>::Builder<'q>, <Mongo as Backend>::Error> {
    let field = field_path(at);
    for (slot, op) in [
      (&self.eq, MongoOperator::Eq),
      (&self.ne, MongoOperator::Ne),
      (&self.gt, MongoOperator::Gt),
      (&self.gte, MongoOperator::Gte),
      (&self.lt, MongoOperator::Lt),
      (&self.lte, MongoOperator::Lte),
    ] {
      if let Some(value) = slot {
        builder.merge(&field, op, value.to_bson());
      }
    }
    for (slot, op) in [
      (&self.in_, MongoOperator::In),
      (&self.not_in, MongoOperator::Nin),
    ] {
      if let Some(values) = slot {
        builder.merge(&field, op, membership(values));
      }
    }
    Ok(builder)
  }
}

#[cfg(test)]
mod tests;