Skip to main content

ingraph/comparison/mongo/
text.rs

1//! The text comparison: [`MongoTextComparison`], the regular expression its affix slots lower to,
2//! and the escaping that keeps an operand from being read as one.
3
4use bson::{
5  Bson, Regex,
6  raw::{CString, cstr},
7};
8
9use super::{Mongo, MongoCarrier, MongoOperator, field_path, membership};
10use crate::{
11  TextFilter, TryMapFilter,
12  comparison::{At, Backend, ComplexComparison, TextMatch, ToDatabaseComparison, TryFromFilter},
13};
14
15/// The start-of-subject assertion a prefix match opens with.
16///
17/// `\A` rather than `^`, and the reason is the one that decides `END` too: PCRE2 documents `\A`,
18/// `\Z` and `\z` as assertions that *only ever match at the very start and end of the subject
19/// string, whatever options are set*, where `^` and `$` answer to the `m` option. This family never
20/// sets `m` and an operand cannot introduce one — an inline `(?m)` loses its brackets to the
21/// escaping — so the two spellings agree today and the absolute pair says so in the pattern rather
22/// than in a note about which options were passed.
23///
24/// It costs nothing at the index: MongoDB names a caret and `\A` as the two left anchors a *prefix
25/// expression* may open with, which is the form its planner turns into a range over an index.
26const START: &str = "\\A";
27
28/// The end-of-subject assertion a suffix match closes with.
29///
30/// `\z` rather than `$`, and here the two spellings do NOT agree. PCRE2's dollar *is true only if
31/// the current matching point is at the end of the subject string, or immediately before a newline
32/// at the end of the string* — so `ends_with: "corp"` spelled `corp$` also matches a field holding
33/// `"acme corp\n"`, which is a document the caller did not ask for. `\z` matches only at the end.
34const END: &str = "\\z";
35
36/// What a NUL in an operand is written as.
37///
38/// The BRACED form rather than `\x00`, so the escape cannot run into the operand's next character:
39/// `b` is a hex digit, so `"\0b"` written `\x00b` would depend on how many digits `\x` consumes,
40/// where `\x{0}b` is closed by its own bracket and depends on nothing.
41const NUL: &str = "\\x{0}";
42
43/// Why the pattern's conversion into a [`CString`] cannot fail — see [`escape_into`], which is the
44/// only thing that ever writes one.
45const NUL_FREE: &str = "a NUL is escaped, so a pattern holds no zero byte";
46
47/// The regular expression `operand` matches as: `kind`'s anchoring around the operand's characters
48/// made inert, and `nocase` in the options.
49///
50/// Public, so a comparison kind declared downstream gets the escaping rather than rewriting it —
51/// the standing this family's SQL analogue `like_pattern` has, for the same reason. It is the one
52/// thing a second text-shaped kind can take from this one.
53///
54/// # A member decides two characters here, and the `kind` is therefore an ARGUMENT
55///
56/// [`TextMatch`] is one vocabulary across both families; where they put the difference is not the
57/// same. A SQL dialect answers each member with its own SQL — `instr`, `LIKE '%v%'`,
58/// `substr(col, 1, length(v))` — and MongoDB answers all three with one `$regex` whose operand is
59/// IDENTICAL and whose anchors differ. So on this backend a member decides two characters and
60/// nothing else, which is why it is read beside the operand rather than dispatched on.
61///
62/// # The operand becomes part of a PATTERN, which is the whole of why this function exists
63///
64/// MongoDB has no `LIKE`. The three affix forms are one `$regex` under different anchors, so the
65/// operand is *read* rather than compared — and the two halves of that hazard are
66/// `contains: "a.b"` matching `axb`, which is a wrong result set reported as a right one, and
67/// `contains: "("`, which is not a wrong answer but no answer, since the server refuses a pattern
68/// it cannot compile.
69///
70/// # Everything but `[0-9A-Za-z_]` is escaped, and that is a RULE rather than a list
71///
72/// PCRE2 — MongoDB's engine since 6.1, and PCRE before it — documents both halves of the rule this
73/// rests on. A backslash *followed by a character that is not a digit or a letter takes away any
74/// special meaning that character may have*, and *only ASCII digits and letters have any special
75/// meaning after a backslash*. So quoting every ASCII character outside `[0-9A-Za-z]` is total by
76/// the engine's own definition, where a metacharacter LIST would have to be kept in step with a
77/// syntax the rule does not depend on. It is Perl's `quotemeta`, which is what `\Q…\E` means, and
78/// PCRE is Perl-compatible by construction.
79///
80/// `_` passes through, and that is the one concession: it needs no escape under either half of the
81/// rule, and it is the character a real prefix operand is most likely to contain. MongoDB's prefix
82/// optimization takes a left anchor *followed by a string of simple symbols*, so a backslash inside
83/// the prefix is what stops it — and `starts_with: "IMG_"` is the case that would pay for a
84/// backslash bought for tidiness.
85///
86/// Non-ASCII passes through as well. No metacharacter has a code point above 127, so quoting one
87/// changes nothing except the size of every operand not written in ASCII.
88///
89/// # The NUL is escaped for a BSON reason rather than a regex one
90///
91/// A BSON regular expression is stored as two cstrings, so [`Regex::pattern`] is a
92/// [`CString`] and a `String` holding a zero byte does not convert. A Rust `&str` may hold one and
93/// a GraphQL `String` may carry one, so an operand can — and `\x{0}` is the same character in bytes
94/// the cstring admits. That is what makes the conversion below total rather than merely lucky:
95/// [`escape_into`] is the only writer and it never emits the one byte the type refuses.
96///
97/// # The options ride INSIDE the regular expression, because `$options` is not an operator
98///
99/// `{field: {$regex: "…", $options: "i"}}` is two keys in one field's operator document, and this
100/// family's accumulator merges one (field, operator, value) at a time. Two comparisons at one path
101/// would then separate them — the second `$regex` overflows into `$and` and its flag does not —
102/// leaving a case-insensitive pattern matched case-sensitively, in silence. A BSON regular
103/// expression carries its own options and is ONE value, which is MongoDB's own third syntax:
104/// `{ <field>: { $regex: /pattern/<options> } }`.
105///
106/// That closes the option vocabulary at `i`, and deliberately: MongoDB requires `$options` for `x`
107/// and `s`, so neither can ride here at all. Neither is reachable from the filter, and an operand
108/// cannot smuggle one in, since `(?x)` loses its brackets to the escaping.
109///
110/// # `i` is PCRE2's caseless matching, which is NOT the collation question SQL's `_nocase` asks
111///
112/// SQL folds inside the query — `ILIKE` on Postgres, `LOWER` around both sides on MySQL, `lower`
113/// on SQLite — and what those fold by is the column's collation or the dialect's own function, so
114/// the three do not agree with each other either. MongoDB's `i` is a flag on the regex engine, and
115/// `$regex` is documented as *not collation-aware*: a collection collation does not change what it
116/// matches and a case-insensitive index does not serve it. So the pattern here is byte-identical to
117/// the case-sensitive one and only the options differ.
118pub fn text_regex(operand: &str, kind: TextMatch, nocase: bool) -> Regex {
119  let mut pattern = String::with_capacity(operand.len() + START.len() + END.len());
120  if matches!(kind, TextMatch::Prefix) {
121    pattern.push_str(START);
122  }
123  escape_into(operand, &mut pattern);
124  if matches!(kind, TextMatch::Suffix) {
125    pattern.push_str(END);
126  }
127  Regex {
128    pattern: CString::try_from(pattern).expect(NUL_FREE),
129    options: if nocase { cstr!("i") } else { cstr!("") }.into(),
130  }
131}
132
133/// `operand`'s characters appended to `out`, each of them inert.
134///
135/// Separate from the anchoring above so that the anchors are pushed OUTSIDE it, which is the
136/// property that keeps `starts_with: "^a"` from anchoring: an operand's `^` arrives here and
137/// leaves as a character to look for, where a `format!` around the raw operand would have let it
138/// assert a position instead.
139fn escape_into(operand: &str, out: &mut String) {
140  for ch in operand.chars() {
141    if ch == '\0' {
142      out.push_str(NUL);
143    } else if ch.is_ascii() && !ch.is_ascii_alphanumeric() && ch != '_' {
144      out.push('\\');
145      out.push(ch);
146    } else {
147      out.push(ch);
148    }
149  }
150}
151
152mongo_comparison_kind! {
153  /// A [`TextFilter`]'s storage-side twin: the same twenty operators, over the type this database
154  /// stores the field as.
155  ///
156  /// # The twelve affix slots read as a table, not as twelve renderings
157  ///
158  /// `contains` / `starts_with` / `ends_with`, each with a negated and a case-insensitive variant,
159  /// are (kind × negated × nocase) triples over one [`TextMatch`] — so the walk is a
160  /// twelve-row table and a loop. The SQL family arrives at that same table and then hands its rows
161  /// to a per-dialect leaf, because `instr`, `LIKE` and `substr` are three different pieces of SQL.
162  /// Here there is no leaf: the triple picks two anchors, one option character and one of two
163  /// operator keys, and [`text_regex`] does the rest.
164  MongoTextComparison {
165    one {
166      eq,
167      ne,
168      gt,
169      gte,
170      lt,
171      lte,
172      contains,
173      contains_nocase,
174      not_contains,
175      not_contains_nocase,
176      starts_with,
177      starts_with_nocase,
178      not_starts_with,
179      not_starts_with_nocase,
180      ends_with,
181      ends_with_nocase,
182      not_ends_with,
183      not_ends_with_nocase,
184    }
185    many { in_, not_in }
186  }
187}
188
189impl<V> MongoTextComparison<V> {
190  /// Cross a [`TextFilter`] into this comparison, converting each operand with `f`.
191  ///
192  /// The entry point a DECLARED converter uses (`mongo(into = …)`), and the same call the
193  /// trait crossing below makes with the storage type's own [`TryFrom`] supplied.
194  ///
195  /// All twenty operands cross through the one converter, substring operands included. A stored
196  /// form that is not a substring of another stored form where the domain values were — a
197  /// compressed or re-encoded text — therefore changes what `contains` MEANS, and that is a
198  /// property of the declared conversion rather than something this layer can check.
199  ///
200  /// The filter is a BOUND rather than a spelling — see
201  /// [`SqlScalarComparison::try_from_filter_with`](crate::comparison::sql::SqlScalarComparison::try_from_filter_with),
202  /// where the wall that closes is written up.
203  pub fn try_from_filter_with<D, I, E, F, X>(filter: X, f: F) -> Result<Self, E>
204  where
205    X: TryMapFilter<D, V, Mapped = TextFilter<V, I>>,
206    F: FnMut(D) -> Result<V, E>,
207  {
208    let stored = filter.try_map_filter(f)?;
209    Ok(Self {
210      eq: stored.eq,
211      ne: stored.ne,
212      gt: stored.gt,
213      gte: stored.gte,
214      lt: stored.lt,
215      lte: stored.lte,
216      contains: stored.contains,
217      contains_nocase: stored.contains_nocase,
218      not_contains: stored.not_contains,
219      not_contains_nocase: stored.not_contains_nocase,
220      starts_with: stored.starts_with,
221      starts_with_nocase: stored.starts_with_nocase,
222      not_starts_with: stored.not_starts_with,
223      not_starts_with_nocase: stored.not_starts_with_nocase,
224      ends_with: stored.ends_with,
225      ends_with_nocase: stored.ends_with_nocase,
226      not_ends_with: stored.not_ends_with,
227      not_ends_with_nocase: stored.not_ends_with_nocase,
228      in_: stored.in_,
229      not_in: stored.not_in,
230    })
231  }
232}
233
234/// The crossing states the LOWERING's bounds rather than the carrier's alone, so a storage type
235/// whose text this backend cannot read is refused where it is DECLARED.
236///
237/// Its SQL twin cannot do that. Three concrete impls whose bounds disagree have no bound list to
238/// restate, so the SQL row names `SqlTextComparison<V, Db>: ComplexComparison<Db>` instead. This
239/// family has one lowering, so its two bounds are the honest statement and the error a declarer
240/// gets names the missing trait.
241///
242/// The READING parameter is carried but never read: what a crossing spends is the OPERANDS, and the
243/// wire form they arrived under is spent by the time one is built. Generic over it so a declarer's
244/// own text type — whose filter names a marker that crate owns — reaches storage exactly as
245/// `TextFilter<String>` does.
246impl<D, I, V: MongoCarrier + AsRef<str>> ToDatabaseComparison<V, Mongo> for TextFilter<D, I> {
247  type Comparison = MongoTextComparison<V>;
248}
249
250/// The crossing with no declared converter — see
251/// [`MongoScalarComparison`](super::MongoScalarComparison)'s for what the identity case buys. A
252/// `String` field stored as `String` is the common one, and it reaches its comparison with an
253/// [`Infallible`](core::convert::Infallible) error.
254impl<D, I, V: TryFrom<D>> TryFromFilter<TextFilter<D, I>> for MongoTextComparison<V> {
255  type Error = V::Error;
256
257  fn try_from_filter(filter: TextFilter<D, I>) -> Result<Self, Self::Error> {
258    Self::try_from_filter_with(filter, V::try_from)
259  }
260}
261
262/// The text kind answers for its two PLAIN operators alone — see the SQL twin's note, whose reading
263/// of what the collapse assumes about two columns is this one's too.
264impl<V> crate::comparison::ReferentialComparison<Mongo> for MongoTextComparison<V> {
265  #[inline]
266  fn is_referential(&self) -> bool {
267    Self::conjuncts(self) == 1 && (self.eq.is_some() || self.in_.is_some())
268  }
269}
270
271/// The eight value operators lower as the scalar kind's do; the twelve affix slots are the whole of
272/// what is new, and they arrive under exactly TWO keys.
273///
274/// # A text comparison is the first kind that OVERFLOWS ITS OWN ENTRY
275///
276/// Every affix slot writes `$regex` or `$not`, so a comparison setting more than one of the six
277/// positive forms has two `$regex`es for one field — which no document key can hold. The
278/// accumulator's answer is already built and it is MongoDB's own: the first merges and the rest
279/// become `$and` branches beside it. Nothing is dropped and nothing is refused.
280///
281/// That is worth stating because the scalar kind cannot reach it. Its eight operators are eight
282/// distinct keys, so its merge never overflows from one comparison and the fold looked like a
283/// safeguard against two comparisons at one path. Here it is the ordinary case: twenty slots reach
284/// at most ten keys, and the other ten fold.
285///
286/// # `V: AsRef<str>` is a REQUIREMENT here where SQLite's lowering has none
287///
288/// The pattern is derived from the operand's characters, so a carrier that binds an opaque encoding
289/// has no characters to read — the same bound the two `LIKE` dialects carry, for the same reason.
290/// SQLite escapes it with `instr`, which takes the operand as a VALUE; MongoDB has no such form,
291/// because `$regex` is the only substring question it asks. So a stored text form with no
292/// `AsRef<str>` is filterable with `contains` on exactly one of this crate's four backends.
293///
294/// The omission is a bound naming the missing trait rather than a filter that matches something
295/// plausible:
296///
297/// ```compile_fail,E0599
298/// use ingraph::{
299///   At, ComplexComparison, FieldName, RecordAddress, TextFilter, TryFromFilter,
300///   comparison::mongo::{MongoConjunction, MongoTextComparison},
301/// };
302///
303/// // A text field stored as a blob — `MongoCarrier` through the crate's own `Vec<u8>` row, and no
304/// // `AsRef<str>` for a pattern to be built from.
305/// let c = MongoTextComparison::<Vec<u8>>::try_from_filter(
306///   TextFilter::<String>::new().with_contains("cam".to_owned()),
307/// )
308/// .unwrap();
309/// const ROW: RecordAddress = RecordAddress::new(FieldName::new("t"), &[FieldName::new("id")]);
310/// let frame = At::new(&ROW).frame(FieldName::new("n"));
311/// c.apply(frame.at(), MongoConjunction::new()).unwrap();
312/// ```
313///
314/// Its twin, which must COMPILE — stable rustdoc runs a `compile_fail` block just far enough to see
315/// it fail and never checks why, so the pair shares its call shape and one half has to be positive:
316///
317/// ```
318/// use bson::doc;
319/// use ingraph::{
320///   At, ComplexComparison, FieldName, RecordAddress, TextFilter, TryFromFilter,
321///   comparison::mongo::{MongoConjunction, MongoTextComparison},
322/// };
323///
324/// let c = MongoTextComparison::<String>::try_from_filter(
325///   TextFilter::<String>::new().with_contains("cam".to_owned()),
326/// )
327/// .unwrap();
328/// const ROW: RecordAddress = RecordAddress::new(FieldName::new("t"), &[FieldName::new("id")]);
329/// let frame = At::new(&ROW).frame(FieldName::new("n"));
330/// let filter = c
331///   .apply(frame.at(), MongoConjunction::new())
332///   .unwrap()
333///   .into_document();
334///
335/// assert_eq!(filter, doc! { "n": { "$regex": bson::Regex {
336///   pattern: "cam".try_into().unwrap(),
337///   options: "".try_into().unwrap(),
338/// } } });
339/// ```
340impl<V: MongoCarrier + AsRef<str>> ComplexComparison<Mongo> for MongoTextComparison<V> {
341  #[inline]
342  fn conjuncts(&self) -> usize {
343    Self::conjuncts(self)
344  }
345
346  fn apply<'q>(
347    &'q self,
348    at: At<'_>,
349    mut builder: <Mongo as Backend>::Builder<'q>,
350  ) -> Result<<Mongo as Backend>::Builder<'q>, <Mongo as Backend>::Error> {
351    let field = field_path(at);
352    for (slot, op) in [
353      (&self.eq, MongoOperator::Eq),
354      (&self.ne, MongoOperator::Ne),
355      (&self.gt, MongoOperator::Gt),
356      (&self.gte, MongoOperator::Gte),
357      (&self.lt, MongoOperator::Lt),
358      (&self.lte, MongoOperator::Lte),
359    ] {
360      if let Some(value) = slot {
361        builder.merge(&field, op, value.to_bson());
362      }
363    }
364    // The twelve affix slots, in the order the struct declares them: three kinds, each plain,
365    // case-insensitive, negated, and both.
366    let matches: [(&Option<V>, TextMatch, bool, bool); 12] = [
367      (&self.contains, TextMatch::Contains, false, false),
368      (&self.contains_nocase, TextMatch::Contains, false, true),
369      (&self.not_contains, TextMatch::Contains, true, false),
370      (&self.not_contains_nocase, TextMatch::Contains, true, true),
371      (&self.starts_with, TextMatch::Prefix, false, false),
372      (&self.starts_with_nocase, TextMatch::Prefix, false, true),
373      (&self.not_starts_with, TextMatch::Prefix, true, false),
374      (&self.not_starts_with_nocase, TextMatch::Prefix, true, true),
375      (&self.ends_with, TextMatch::Suffix, false, false),
376      (&self.ends_with_nocase, TextMatch::Suffix, false, true),
377      (&self.not_ends_with, TextMatch::Suffix, true, false),
378      (&self.not_ends_with_nocase, TextMatch::Suffix, true, true),
379    ];
380    for (slot, kind, negated, nocase) in matches {
381      if let Some(value) = slot {
382        let op = if negated {
383          MongoOperator::Not
384        } else {
385          MongoOperator::Regex
386        };
387        builder.merge(
388          &field,
389          op,
390          Bson::RegularExpression(text_regex(value.as_ref(), kind, nocase)),
391        );
392      }
393    }
394    for (slot, op) in [
395      (&self.in_, MongoOperator::In),
396      (&self.not_in, MongoOperator::Nin),
397    ] {
398      if let Some(values) = slot {
399        builder.merge(&field, op, membership(values));
400      }
401    }
402    Ok(builder)
403  }
404}
405
406#[cfg(test)]
407mod tests;