fix(NODE-6284): make sparsity and trimFactor optional (#4189)

.evergreen/install-mongodb-client-encryption.sh

@@ -1,5 +1,5 @@
 #! /usr/bin/env bash
-set +o xtrace # Do not write AWS credentials to stderr
+set +o xtrace
 
 # Initial checks for running these tests
 if [ -z ${PROJECT_DIRECTORY+omitted} ]; then echo "PROJECT_DIRECTORY is unset" && exit 1; fi
@@ -9,20 +9,19 @@ source "${PROJECT_DIRECTORY}/.evergreen/init-node-and-npm-env.sh"
 set -o xtrace   # Write all commands first to stderr
 set -o errexit  # Exit the script with error if any of the commands fail
 
-rm -rf $INSTALL_DIR
+rm -rf mongodb-client-encryption
 git clone https://github.com/mongodb-js/mongodb-client-encryption.git
 pushd mongodb-client-encryption
 
 if [ -n "${LIBMONGOCRYPT_VERSION}" ]; then
 	# nightly tests test with `latest` to test against the laster FLE build.
-    npm run install:libmongocrypt -- --libVersion $LIBMONGOCRYPT_VERSION
+    npm run install:libmongocrypt -- --build --libVersion $LIBMONGOCRYPT_VERSION
 else
 	# otherwise use whatever is specified in the package.json.
     npm run install:libmongocrypt
 fi
 
 echo "finished installing libmongocrypt"
-BINDINGS_DIR=$(pwd)
 
 popd
 

package.json

@@ -98,7 +98,7 @@
     "js-yaml": "^4.1.0",
     "mocha": "^10.4.0",
     "mocha-sinon": "^2.1.2",
-    "mongodb-client-encryption": "^6.1.0-alpha.0",
+    "mongodb-client-encryption": "^6.1.0",
     "mongodb-legacy": "^6.0.1",
     "nyc": "^15.1.0",
     "prettier": "^2.8.8",

src/client-side-encryption/client_encryption.ts

@@ -5,7 +5,15 @@ import type {
   MongoCryptOptions
 } from 'mongodb-client-encryption';
 
-import { type Binary, deserialize, type Document, type Long, serialize, type UUID } from '../bson';
+import {
+  type Binary,
+  deserialize,
+  type Document,
+  type Int32,
+  type Long,
+  serialize,
+  type UUID
+} from '../bson';
 import { type AnyBulkWriteOperation, type BulkWriteResult } from '../bulk/common';
 import { type ProxyOptions } from '../cmap/connection';
 import { type Collection } from '../collection';
@@ -956,13 +964,19 @@ export interface ClientEncryptionRewrapManyDataKeyResult {
 /**
  * @public
  * RangeOptions specifies index options for a Queryable Encryption field supporting "rangePreview" queries.
- * min, max, sparsity, and range must match the values set in the encryptedFields of the destination collection.
+ * min, max, sparsity, trimFactor and range must match the values set in the encryptedFields of the destination collection.
  * For double and decimal128, min/max/precision must all be set, or all be unset.
  */
 export interface RangeOptions {
+  /** min is the minimum value for the encrypted index. Required if precision is set. */
   min?: any;
+  /** max is the minimum value for the encrypted index. Required if precision is set. */
   max?: any;
-  sparsity: Long;
+  /** sparsity may be used to tune performance. must be non-negative. When omitted, a default value is used. */
+  sparsity?: Long | bigint;
+  /** trimFactor may be used to tune performance. must be non-negative. When omitted, a default value is used. */
+  trimFactor?: Int32 | number;
+  /* precision determines the number of significant digits after the decimal point. May only be set for double or decimal128. */
   precision?: number;
 }
 

test/integration/client-side-encryption/client_side_encryption.prose.23.range_encryption_defaults.test.ts

@@ -0,0 +1,144 @@
+import { expect } from 'chai';
+
+/* eslint-disable @typescript-eslint/no-restricted-imports */
+import { ClientEncryption } from '../../../src/client-side-encryption/client_encryption';
+import { type Binary, EJSON, Int32, Long } from '../../mongodb';
+import { installNodeDNSWorkaroundHooks } from '../../tools/runner/hooks/configuration';
+
+const metaData: MongoDBMetadataUI = {
+  requires: {
+    clientSideEncryption: '>=6.1.0',
+
+    // The Range Explicit Encryption tests require MongoDB server 7.0+ for QE v2.
+    // The tests must not run against a standalone.
+    //
+    // `range` is not supported on 8.0+ servers.
+    mongodb: '>=8.0.0',
+    topology: '!single'
+  }
+};
+
+const getKmsProviders = (): { local: { key: string } } => {
+  const result = EJSON.parse(process.env.CSFLE_KMS_PROVIDERS || '{}') as unknown as {
+    local: { key: string };
+  };
+
+  return { local: result.local };
+};
+
+describe('Range Explicit Encryption Defaults', function () {
+  installNodeDNSWorkaroundHooks();
+
+  let clientEncryption: ClientEncryption;
+  let keyId;
+  let keyVaultClient;
+  let payload_defaults: Binary;
+
+  beforeEach(async function () {
+    // Create a MongoClient named `keyVaultClient`.
+    keyVaultClient = this.configuration.newClient();
+
+    // Create a ClientEncryption object named `clientEncryption` with these options:
+    // ```typescript
+    // class ClientEncryptionOpts {
+    //   keyVaultClient: keyVaultClient,
+    //   keyVaultNamespace: "keyvault.datakeys",
+    //   kmsProviders: { "local": { "key": "<base64 decoding of LOCAL_MASTERKEY>" } },
+    // }
+    // ```
+    clientEncryption = new ClientEncryption(keyVaultClient, {
+      keyVaultNamespace: 'keyvault.datakeys',
+      kmsProviders: getKmsProviders()
+    });
+
+    // Create a key with `clientEncryption.createDataKey`. Store the returned key ID in a variable named `keyId`.
+    keyId = await clientEncryption.createDataKey('local');
+
+    // Call `clientEncryption.encrypt` to encrypt the int32 value `123` with these options:
+    // ```typescript
+    // class EncryptOpts {
+    //   keyId : keyId,
+    //   algorithm: "Range",
+    //   contentionFactor: 0,
+    //   rangeOpts: RangeOpts {
+    //       min: 0,
+    //       max: 1000
+    //   }
+    // }
+    // ```
+    // Store the result in a variable named `payload_defaults`.
+    payload_defaults = await clientEncryption.encrypt(new Int32(123), {
+      keyId,
+      algorithm: 'Range',
+      contentionFactor: 0,
+      rangeOptions: {
+        min: 0,
+        max: 1000
+      }
+    });
+  });
+
+  afterEach(async function () {
+    await keyVaultClient.close();
+  });
+
+  it('Case 1: Uses libmongocrypt defaults', metaData, async function () {
+    // Call `clientEncryption.encrypt` to encrypt the int32 value `123` with these options:
+    // ```typescript
+    // class EncryptOpts {
+    //   keyId : keyId,
+    //   algorithm: "Range",
+    //   contentionFactor: 0,
+    //   rangeOpts: RangeOpts {
+    //       min: 0,
+    //       max: 1000,
+    //       sparsity: 2,
+    //       trimFactor: 6
+    //   }
+    // }
+    // ```
+    const encrypted = await clientEncryption.encrypt(new Int32(123), {
+      keyId: keyId,
+      algorithm: 'Range',
+      contentionFactor: 0,
+      rangeOptions: {
+        min: 0,
+        max: 1000,
+        sparsity: new Long(2),
+        trimFactor: new Int32(6)
+      }
+    });
+
+    // Assert the returned payload size equals the size of `payload_defaults`.
+    expect(encrypted.length()).to.equal(payload_defaults.length());
+  });
+
+  it('Case 2: can find encrypted range and return the maximum', metaData, async function () {
+    // Call `clientEncryption.encrypt` to encrypt the int32 value `123` with these options:
+    // ```typescript
+    // class EncryptOpts {
+    //   keyId : keyId,
+    //   algorithm: "Range",
+    //   contentionFactor: 0,
+    //   rangeOpts: RangeOpts {
+    //       min: 0,
+    //       max: 1000,
+    //       trimFactor: 0
+    //   }
+    // }
+    // ```
+    const encrypted = await clientEncryption.encrypt(new Int32(123), {
+      keyId: keyId,
+      algorithm: 'Range',
+      contentionFactor: 0,
+      rangeOptions: {
+        min: 0,
+        max: 1000,
+        trimFactor: new Int32(0)
+      }
+    });
+
+    // Assert the returned payload size is greater than the size of `payload_defaults`.
+    expect(encrypted.length()).to.be.greaterThan(payload_defaults.length());
+  });
+});

test/integration/client-side-encryption/driver.test.ts

@@ -405,3 +405,74 @@ describe('Client Side Encryption Functional', function () {
     }
   );
 });
+
+describe('Range Explicit Encryption with JS native types', function () {
+  installNodeDNSWorkaroundHooks();
+
+  const metaData: MongoDBMetadataUI = {
+    requires: {
+      clientSideEncryption: '>=6.1.0',
+
+      // The Range Explicit Encryption tests require MongoDB server 7.0+ for QE v2.
+      // The tests must not run against a standalone.
+      //
+      // `range` is not supported on 8.0+ servers.
+      mongodb: '>=8.0.0',
+      topology: '!single'
+    }
+  };
+
+  const getKmsProviders = (): { local: { key: string } } => {
+    const result = EJSON.parse(process.env.CSFLE_KMS_PROVIDERS || '{}') as unknown as {
+      local: { key: string };
+    };
+
+    return { local: result.local };
+  };
+
+  let clientEncryption: ClientEncryption;
+  let keyId;
+  let keyVaultClient;
+
+  beforeEach(async function () {
+    keyVaultClient = this.configuration.newClient();
+    clientEncryption = new ClientEncryption(keyVaultClient, {
+      keyVaultNamespace: 'keyvault.datakeys',
+      kmsProviders: getKmsProviders()
+    });
+
+    keyId = await clientEncryption.createDataKey('local');
+  });
+
+  afterEach(async function () {
+    await keyVaultClient.close();
+  });
+
+  it('supports a js number for trimFactor', metaData, async function () {
+    await clientEncryption.encrypt(new BSON.Int32(123), {
+      keyId,
+      algorithm: 'Range',
+      contentionFactor: 0,
+      rangeOptions: {
+        min: 0,
+        max: 1000,
+        trimFactor: 1,
+        sparsity: new BSON.Long(1)
+      }
+    });
+  });
+
+  it('supports a bigint for sparsity', metaData, async function () {
+    await clientEncryption.encrypt(new BSON.Int32(123), {
+      keyId,
+      algorithm: 'Range',
+      contentionFactor: 0,
+      rangeOptions: {
+        min: 0,
+        max: 1000,
+        trimFactor: new BSON.Int32(1),
+        sparsity: 1n
+      }
+    });
+  });
+});