Merge remote-tracking branch 'origin/master' into DRIVERS-719

Author: nhachicha

source/change-streams/change-streams.md

@@ -757,8 +757,17 @@ When `resumeAfter` is specified the `ChangeStream` will return notifications sta
 
 If the server supports sessions, the resume attempt MUST use the same session as the previous attempt's command.
 
-A driver MUST ensure that consecutive resume attempts can succeed, even in the absence of any changes received by the
-cursor between resume attempts.
+A driver MUST only attempt to resume once from a resumable error. However, if the `aggregate` for that resume succeeds,
+a driver MUST ensure that following resume attempts can succeed, even in the absence of any changes received by the
+cursor between resume attempts. For example:
+
+1. `aggregate` (succeeds)
+2. `getMore` (fails with resumable error)
+3. `aggregate` (succeeds)
+4. `getMore` (fails with resumable error)
+5. `aggregate` (succeeds)
+6. `getMore` (succeeds)
+7. change stream document received
 
 A driver SHOULD attempt to kill the cursor on the server on which the cursor is opened during the resume process, and
 MUST NOT attempt to kill the cursor on any other server. Any exceptions or errors that occur during the process of
@@ -1017,6 +1026,8 @@ There should be no backwards compatibility concerns.
 
 ## Changelog
 
+- 2025-09-08: Clarify resume behavior.
+
 - 2025-03-31: Update for expanded field visibility in server 8.2+
 
 - 2025-02-24: Make `nsType` `Optional` to match other optional fields in the change stream spec.

source/client-side-encryption/client-side-encryption.md

@@ -48,6 +48,8 @@ QEv1 and QEv2 are incompatible.
 MongoDB 8.0 dropped `queryType=rangePreview` and added `queryType=range`
 ([SPM-3583](https://jira.mongodb.org/browse/SPM-3583)).
 
+MongoDB 8.2 added unstable support for QE text queries ([SPM-2880](https://jira.mongodb.org/browse/SPM-2880))
+
 ## META
 
 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
@@ -1256,6 +1258,7 @@ class EncryptOpts {
    contentionFactor: Optional<Int64>,
    queryType: Optional<String>
    rangeOpts: Optional<RangeOpts>
+   textOpts: Optional<TextOpts>
 }
 
 // RangeOpts specifies index options for a Queryable Encryption field supporting "range" queries.
@@ -1273,6 +1276,48 @@ class RangeOpts {
    // precision determines the number of significant digits after the decimal point. May only be set for double or decimal128.
    precision: Optional<Int32>
 }
+
+// TextOpts specifies options for a Queryable Encryption field supporting text queries.
+// NOTE: TextOpts is currently unstable API and subject to backwards breaking changes.
+class TextOpts {
+   // substring contains further options to support substring queries.
+   substring: Optional<SubstringOpts>,
+   // prefix contains further options to support prefix queries.
+   prefix: Optional<PrefixOpts>,
+   // suffix contains further options to support suffix queries.
+   suffix: Optional<SuffixOpts>,
+   // caseSensitive determines whether text indexes for this field are case sensitive.
+   caseSensitive: bool,
+   // diacriticSensitive determines whether text indexes for this field are diacritic sensitive.
+   diacriticSensitive: bool
+}
+
+// NOTE: SubstringOpts is currently unstable API and subject to backwards breaking changes.
+class SubstringOpts {
+   // strMaxLength is the maximum allowed length to insert. Inserting longer strings will error.
+   strMaxLength: Int32,
+   // strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+   strMinQueryLength: Int32,
+   // strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+   strMaxQueryLength: Int32,
+}
+
+// NOTE: PrefixOpts is currently unstable API and subject to backwards breaking changes.
+class PrefixOpts {
+   // strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+   strMinQueryLength: Int32,
+   // strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+   strMaxQueryLength: Int32,
+}
+
+// NOTE: SuffixOpts is currently unstable API and subject to backwards breaking changes.
+class SuffixOpts {
+   // strMinQueryLength is the minimum allowed query length. Querying with a shorter string will error.
+   strMinQueryLength: Int32,
+   // strMaxQueryLength is the maximum allowed query length. Querying with a longer string will error.
+   strMaxQueryLength: Int32,
+}
+
 ```
 
 Explicit encryption requires a key and algorithm. Keys are either identified by `_id` or by alternate name. Exactly one
@@ -1295,34 +1340,45 @@ One of the strings:
 - "Indexed"
 - "Unindexed"
 - "Range"
+- "TextPreview"
 
-The result of explicit encryption with the "Indexed" or "Range" algorithm must be processed by the server to insert or
-query. Drivers MUST document the following behavior:
+The result of explicit encryption with the "Indexed", "Range", or "TextPreview" algorithm must be processed by the
+server to insert or query. Drivers MUST document the following behavior:
 
-> To insert or query with an "Indexed" or "Range" encrypted payload, use a `MongoClient` configured with
+> To insert or query with an "Indexed", "Range", or "TextPreview" encrypted payload, use a `MongoClient` configured with
 > `AutoEncryptionOpts`. `AutoEncryptionOpts.bypassQueryAnalysis` may be true. `AutoEncryptionOpts.bypassAutoEncryption`
-> must be false.
+> must be false. The "TextPreview" algorithm is in preview and should be used for experimental workloads only. These
+> features are unstable and their security is not guaranteed until released as Generally Available (GA). The GA version
+> of these features may not be backwards compatible with the preview version.
 
 #### contentionFactor
 
-contentionFactor may be used to tune performance. Only applies when algorithm is "Indexed" or "Range". libmongocrypt
-returns an error if contentionFactor is set for a non-applicable algorithm.
+contentionFactor may be used to tune performance. Only applies when algorithm is "Indexed", "Range", or "TextPreview".
+libmongocrypt returns an error if contentionFactor is set for a non-applicable algorithm.
 
 #### queryType
 
 One of the strings:
 
 - "equality"
 - "range"
+- "prefixPreview"
+- "suffixPreview"
+- "substringPreview"
 
-queryType only applies when algorithm is "Indexed" or "Range". libmongocrypt returns an error if queryType is set for a
-non-applicable queryType.
+queryType only applies when algorithm is "Indexed", "Range", or "TextPreview". libmongocrypt returns an error if
+queryType is set for a non-applicable algorithm.
 
 #### rangeOpts
 
 rangeOpts only applies when algorithm is "Range". libmongocrypt returns an error if rangeOpts is set for a
 non-applicable algorithm.
 
+#### textOpts
+
+textOpts only applies when algorithm is "TextPreview". libmongocrypt returns an error if textOpts is set for a
+non-applicable algorithm.
+
 ## User facing API: When Auto Encryption Fails
 
 Auto encryption requires parsing the MongoDB query language client side (with the [mongocryptd](#mongocryptd) process or
@@ -2463,6 +2519,8 @@ explicit session parameter as described in the [Drivers Sessions Specification](
 
 ## Changelog
 
+- 2025-08-06: Add `TextPreview` algorithm.
+
 - 2024-02-19: Add custom options AWS credential provider.
 
 - 2024-10-09: Add retry prose test.

source/client-side-encryption/etc/data/encryptedFields-prefix-suffix.json

@@ -0,0 +1,38 @@
+{
+  "fields": [
+    {
+            "keyId": {
+                "$binary": {
+                    "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+                    "subType": "04"
+                }
+            },
+            "path": "encryptedText",
+            "bsonType": "string",
+            "queries": [
+                {
+                    "queryType": "prefixPreview",
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "10"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                },
+                {
+                    "queryType": "suffixPreview",
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "10"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                }
+            ]
+        }
+  ]
+}

source/client-side-encryption/etc/data/encryptedFields-substring.json

@@ -0,0 +1,30 @@
+{
+  "fields": [
+    {
+            "keyId": {
+                "$binary": {
+                    "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+                    "subType": "04"
+                }
+            },
+            "path": "encryptedText",
+            "bsonType": "string",
+            "queries": [
+                {
+                    "queryType": "substringPreview",
+                    "strMaxLength": {
+                        "$numberInt": "10"
+                    },
+                    "strMinQueryLength": {
+                        "$numberInt": "2"
+                    },
+                    "strMaxQueryLength": {
+                        "$numberInt": "10"
+                    },
+                    "caseSensitive": true,
+                    "diacriticSensitive": true
+                }
+            ]
+        }
+  ]
+}

source/client-side-encryption/limits/limits-encryptedFields.json

@@ -0,0 +1,14 @@
+{
+    "fields": [
+        {
+            "keyId": {
+                "$binary": {
+                    "base64": "LOCALAAAAAAAAAAAAAAAAA==",
+                    "subType": "04"
+                }
+            },
+            "path": "foo",
+            "bsonType": "string"
+        }
+    ]
+}

source/client-side-encryption/limits/limits-qe-doc.json

@@ -0,0 +1,3 @@
+{
+    "foo": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+}