feat(NODE-7537): promote QE string queries (prefix/suffix/substring) (#4996)

Author: tadjik1

package-lock.json

@@ -34,7 +34,7 @@
     "@mongodb-js/zstd": "^7.0.0",
     "gcp-metadata": "^7.0.1",
     "kerberos": "^7.0.0",
-    "mongodb-client-encryption": ">=7.0.0 <7.1.0",
+    "mongodb-client-encryption": "^7.2.0",
     "snappy": "^7.3.2",
     "socks": "^2.8.6"
   },
@@ -96,7 +96,7 @@
     "js-yaml": "^4.2.0",
     "mocha": "^11.7.6",
     "mocha-sinon": "^2.1.2",
-    "mongodb-client-encryption": "^7.0.0",
+    "mongodb-client-encryption": "^7.2.0",
     "nyc": "^17.1.0",
     "prettier": "^3.6.2",
     "semver": "^7.7.2",

package.json

@@ -746,8 +746,16 @@ export class ClientEncryption {
     expressionMode: boolean,
     options: ClientEncryptionEncryptOptions
   ): Promise<Binary> {
-    const { algorithm, keyId, keyAltName, contentionFactor, queryType, rangeOptions, textOptions } =
-      options;
+    const {
+      algorithm,
+      keyId,
+      keyAltName,
+      contentionFactor,
+      queryType,
+      rangeOptions,
+      stringOptions,
+      textOptions
+    } = options;
     const contextOptions: ExplicitEncryptionContextOptions = {
       expressionMode,
       algorithm
@@ -780,8 +788,9 @@ export class ClientEncryption {
       contextOptions.rangeOptions = serialize(rangeOptions);
     }
 
-    if (typeof textOptions === 'object') {
-      contextOptions.textOptions = serialize(textOptions);
+    const resolvedStringOptions = stringOptions ?? textOptions;
+    if (typeof resolvedStringOptions === 'object') {
+      contextOptions.textOptions = serialize(resolvedStringOptions);
     }
 
     const valueBuffer = serialize({ v: value });
@@ -815,6 +824,8 @@ export interface ClientEncryptionEncryptOptions {
     | 'Indexed'
     | 'Unindexed'
     | 'Range'
+    | 'String'
+    /** @deprecated Use `'String'` instead. */
     | 'TextPreview';
 
   /**
@@ -833,26 +844,39 @@ export interface ClientEncryptionEncryptOptions {
   /**
    * The query type.
    */
-  queryType?: 'equality' | 'range' | 'prefixPreview' | 'suffixPreview' | 'substringPreview';
+  queryType?:
+    | 'equality'
+    | 'range'
+    | 'prefix'
+    | 'suffix'
+    | 'substring'
+    /** @deprecated Use `'prefix'` instead. */
+    | 'prefixPreview'
+    /** @deprecated Use `'suffix'` instead. */
+    | 'suffixPreview'
+    /** @deprecated Use `'substring'` instead. */
+    | 'substringPreview';
 
   /** The index options for a Queryable Encryption field supporting "range" queries.*/
   rangeOptions?: RangeOptions;
 
+  /** Options for a Queryable Encryption field supporting string queries. Only valid when `algorithm` is `'String'` or the deprecated `'TextPreview'`. */
+  stringOptions?: StringQueryOptions;
+
   /**
-   * Options for a Queryable Encryption field supporting text queries.  Only valid when `algorithm` is `TextPreview`.
+   * Options for a Queryable Encryption field supporting text queries. Only valid when `algorithm` is `'String'` or the deprecated `'TextPreview'`.
    *
-   * @experimental Public Technical Preview: `textPreview` is an experimental feature and may break at any time.
+   * @deprecated Use `stringOptions` instead.
    */
-  textOptions?: TextQueryOptions;
+  textOptions?: StringQueryOptions;
 }
 
 /**
- * Options for a Queryable Encryption field supporting text queries.
+ * Options for a Queryable Encryption field supporting string queries.
  *
  * @public
- * @experimental Public Technical Preview: `textPreview` is an experimental feature and may break at any time.
  */
-export interface TextQueryOptions {
+export interface StringQueryOptions {
   /** Indicates that text indexes for this field are case sensitive */
   caseSensitive: boolean;
   /** Indicates that text indexes for this field are diacritic sensitive. */
@@ -882,6 +906,12 @@ export interface TextQueryOptions {
   };
 }
 
+/**
+ * @public
+ * @deprecated Use {@link StringQueryOptions} instead.
+ */
+export type TextQueryOptions = StringQueryOptions;
+
 /**
  * @public
  * @experimental

src/client-side-encryption/client_encryption.ts

@@ -241,6 +241,7 @@ export type {
   GCPEncryptionKeyOptions,
   KMIPEncryptionKeyOptions,
   RangeOptions,
+  StringQueryOptions,
   TextQueryOptions
 } from './client-side-encryption/client_encryption';
 export {

src/index.ts

@@ -1,3 +1,5 @@
+/* https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/tests/README.md#25-test-lookup */
+
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 
@@ -37,7 +39,7 @@ const newEncryptedClient = ({ configuration }: { configuration: TestConfiguratio
     }
   );
 
-describe('$lookup support', defaultMetadata, function () {
+describe('25. Test $lookup', defaultMetadata, function () {
   before(async function () {
     const mochaTest = { metadata: defaultMetadata };
 
@@ -83,6 +85,7 @@ describe('$lookup support', defaultMetadata, function () {
        *   db.qe2 with options: { "encryptedFields": "<schema-qe2.json>"}.
        *   db.no_schema with no options.
        *   db.no_schema2 with no options.
+       *   db.non_csfle_schema with options: { "validator": { "$jsonSchema": "<schema-non-csfle.json>"}}.
        * ```
        */
       const collections = [
@@ -115,6 +118,11 @@ describe('$lookup support', defaultMetadata, function () {
           name: 'no_schema2',
           options: {},
           document: { no_schema2: 'no_schema2' }
+        },
+        {
+          name: 'non_csfle_schema',
+          options: { validator: { $jsonSchema: await readFixture('schema-non-csfle.json') } },
+          document: { non_csfle_schema: 'non_csfle_schema' }
         }
       ];
 
@@ -126,6 +134,7 @@ describe('$lookup support', defaultMetadata, function () {
       unencryptedClient = this.configuration.newClient({}, { writeConcern: { w: 'majority' } });
 
       /**
+       * Insert documents with encryptedClient:
        * ```
        * {"csfle": "csfle"} into db.csfle
        * Use the unencrypted client to retrieve it. Assert the csfle field is BSON binary.
@@ -137,12 +146,13 @@ describe('$lookup support', defaultMetadata, function () {
        * Use the unencrypted client to retrieve it. Assert the qe2 field is BSON binary.
        * {"no_schema": "no_schema"} into db.no_schema
        * {"no_schema2": "no_schema2"} into db.no_schema2
+       * {"non_csfle_schema": "non_csfle_schema"} into db.non_csfle_schema
        * ```
        */
       for (const { name, document } of collections) {
         const { insertedId } = await encryptedClient.db('db').collection(name).insertOne(document);
 
-        if (name.startsWith('no_')) continue;
+        if (name.startsWith('no_') || name === 'non_csfle_schema') continue;
 
         expect(await unencryptedClient.db('db').collection(name).findOne(insertedId))
           .to.have.property(Object.keys(document)[0])
@@ -325,6 +335,11 @@ describe('$lookup support', defaultMetadata, function () {
     { requires: { ...defaultMetadata.requires, mongodb: '>=8.1.0' } }
   );
 
+  // Case 8 expects one of two error messages depending on mongocryptd/crypt_shared and libmongocrypt versions:
+  // - mongocryptd/crypt_shared <8.2 or libmongocrypt <1.17.0: "not supported"
+  // - mongocryptd/crypt_shared 8.2+ and libmongocrypt 1.17.0+:
+  //   "Cannot specify both encryptionInformation and csfleEncryptionSchemas unless
+  //    csfleEncryptionSchemas only contains non-encryption JSON schema validators"
   test(
     'Case 8: db.csfle joins db.qe',
     'csfle',
@@ -339,7 +354,7 @@ describe('$lookup support', defaultMetadata, function () {
       },
       { $project: { _id: 0 } }
     ],
-    /not supported/i,
+    /not supported|Cannot specify both encryptionInformation and csfleEncryptionSchemas/i,
     { requires: { ...defaultMetadata.requires, mongodb: '>=8.1.0' } }
   );
 
@@ -360,4 +375,26 @@ describe('$lookup support', defaultMetadata, function () {
     /Upgrade/i,
     { requires: { ...defaultMetadata.requires, mongodb: '>=7.0.0 <8.1.0' } }
   );
+
+  // Case 10 requires server 8.2+, mongocryptd/crypt_shared 8.2+, and libmongocrypt 1.17.0+.
+  test(
+    'Case 10: db.qe joins db.non_csfle_schema',
+    'qe',
+    [
+      { $match: { qe: 'qe' } },
+      {
+        $lookup: {
+          from: 'non_csfle_schema',
+          as: 'matched',
+          pipeline: [
+            { $match: { non_csfle_schema: 'non_csfle_schema' } },
+            { $project: { _id: 0, __safeContent__: 0 } }
+          ]
+        }
+      },
+      { $project: { _id: 0, __safeContent__: 0 } }
+    ],
+    { qe: 'qe', matched: [{ non_csfle_schema: 'non_csfle_schema' }] },
+    { requires: { ...defaultMetadata.requires, mongodb: '>=8.2.0' } }
+  );
 });