DRIVERS-2767 QE Range Protocol v2

src/libmongoc/doc/mongoc_client_encryption_encrypt.rst

@@ -20,22 +20,19 @@ Performs explicit encryption.
 
 ``ciphertext`` is always initialized (even on failure). Caller must call :symbol:`bson_value_destroy()` to free.
 
-To insert or query with an "Indexed" or "RangePreview" encrypted payload, use a
+To insert or query with an "Indexed" or "Range" encrypted payload, use a
 :symbol:`mongoc_client_t` configured with
 :symbol:`mongoc_auto_encryption_opts_t`. The
 :symbol:`mongoc_auto_encryption_opts_t` may be configured to bypass query
 analysis with :symbol:`mongoc_auto_encryption_opts_set_bypass_query_analysis`.
 The :symbol:`mongoc_auto_encryption_opts_t` must not be configured to bypass
 automatic encryption with
-:symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. **Note** that
-the ``"RangePreview"`` payload type |qenc:is-experimental|. The |qenc:range-is-experimental| 
+:symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`.
 
-To insert with a ``RangePreview`` payload 
+To insert with a ``Range`` payload 
 :symbol:`mongoc_client_encryption_encrypt_range_opts_t` must be set in ``opts``.
 
-To query with a ``RangePreview`` payload, use :symbol:`mongoc_client_encryption_encrypt_expression()`
-
-**NOTE** that the |qenc:range-is-experimental|
+To query with a ``Range`` payload, use :symbol:`mongoc_client_encryption_encrypt_expression()`
 
 Parameters
 ----------

src/libmongoc/doc/mongoc_client_encryption_encrypt_expression.rst

@@ -16,12 +16,11 @@ Synopsis
       bson_t *expr_out,
       bson_error_t *error);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Encrypts a Match Expression or Aggregate Expression to query a range index.
 
-To query with a ``RangePreview`` encrypted payload, use a
+To query with a ``Range`` encrypted payload, use a
 :symbol:`mongoc_client_t` configured with
 :symbol:`mongoc_auto_encryption_opts_t`. The
 :symbol:`mongoc_auto_encryption_opts_t` may be configured to bypass query
@@ -30,7 +29,7 @@ The :symbol:`mongoc_auto_encryption_opts_t` must not be configured to bypass
 automatic encryption with
 :symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. 
 
-To query with a ``RangePreview`` payload, ``expr`` must be one of the following forms: 
+To query with a ``Range`` payload, ``expr`` must be one of the following forms: 
 
 #. A Match Expression of the following form: 
 

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_algorithm.rst

@@ -14,12 +14,9 @@ Synopsis
 
    #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
    #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
-   // (Experimental: See below)
    #define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed"
-   // (Experimental: See below)
    #define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed"
-   // (Experimental: See below)
-   #define MONGOC_ENCRYPT_ALGORITHM_RANGEPREVIEW "RangePreview"
+   #define MONGOC_ENCRYPT_ALGORITHM_RANGE "Range"
 
 Identifies the algorithm to use for encryption. Valid values of ``algorithm`` are:
 
@@ -39,12 +36,10 @@ Identifies the algorithm to use for encryption. Valid values of ``algorithm`` ar
 
    for unindexed encryption. Specific to the `Queryable Encryption <queryable-encryption_>`_ feature.
 
-``"RangePreview"``
+``"Range"``
 
    for range encryption. Specific to the `Queryable Encryption <queryable-encryption_>`_ feature.
 
-   .. note:: The |qenc:range-is-experimental| |qenc:opt-is-experimental|
-
 Parameters
 ----------
 

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_contention_factor.rst

@@ -15,8 +15,8 @@ Synopsis
 .. versionadded:: 1.22.0
 
 Sets a contention factor for explicit encryption.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed" or "RangePreview".
-It is an error to set the contention factor when algorithm is not "Indexed" or "RangePreview". **Note** that the |qenc:range-is-experimental|
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed" or "Range".
+It is an error to set the contention factor when algorithm is not "Indexed" or "Range".
 If contention factor is not supplied, it defaults to a value of 0.
 
 Parameters

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_query_type.rst

@@ -9,7 +9,7 @@ Synopsis
 .. code-block:: c
 
    #define MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY "equality"
-   #define MONGOC_ENCRYPT_QUERY_TYPE_RANGEPREVIEW "rangePreview"
+   #define MONGOC_ENCRYPT_QUERY_TYPE_RANGE "range"
 
    MONGOC_EXPORT (void)
     mongoc_client_encryption_encrypt_opts_set_query_type (
@@ -18,10 +18,10 @@ Synopsis
 .. versionadded:: 1.22.0
 
 Sets a query type for explicit encryption. Currently, the supported values
-for ``query_type`` are ``"equality"`` and ``"rangePreview"``. **NOTE** that the |qenc:range-is-experimental|
+for ``query_type`` are ``"equality"`` and ``"range"``.
 
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed" or "RangePreview".
-It is an error to set the query type when algorithm is not "Indexed" or "RangePreview".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed" or "Range".
+It is an error to set the query type when algorithm is not "Indexed" or "Range".
 
 Parameters
 ----------

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_range_opts.rst

@@ -13,12 +13,11 @@ Synopsis
           mongoc_client_encryption_encrypt_opts_t *opts,
           const mongoc_client_encryption_encrypt_range_opts_t *range_opts);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Sets the ``range_opts`` for explicit encryption.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
-It is an error to set ``range_opts`` when algorithm is not "RangePreview".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Range".
+It is an error to set ``range_opts`` when algorithm is not "Range".
 
 Parameters
 ----------

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_destroy.rst

@@ -11,7 +11,6 @@ Synopsis
   void
   mongoc_client_encryption_encrypt_range_opts_destroy (mongoc_client_encryption_encrypt_range_opts_t *range_opts);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Frees resources of a :symbol:`mongoc_client_encryption_encrypt_range_opts_t` created with :symbol:`mongoc_client_encryption_encrypt_range_opts_new()`. Does nothing if ``NULL`` is passed.

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_new.rst

@@ -11,7 +11,6 @@ Synopsis
   mongoc_client_encryption_encrypt_range_opts_t *
   mongoc_client_encryption_encrypt_range_opts_new (void);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Returns

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_max.rst

@@ -13,12 +13,11 @@ Synopsis
          mongoc_client_encryption_encrypt_range_opts_t *range_opts,
          const bson_value_t *max);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Sets the maximum value of the range for explicit encryption.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
-It is an error to set maximum when algorithm is not "RangePreview".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Range".
+It is an error to set maximum when algorithm is not "Range".
 
 The maximum must match the value set in the encryptedFields of the destination collection.
 It is an error to set a different value.

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_min.rst

@@ -13,12 +13,11 @@ Synopsis
          mongoc_client_encryption_encrypt_range_opts_t *range_opts,
          const bson_value_t *min);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Sets the minimum value of the range for explicit encryption.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
-It is an error to set minimum when algorithm is not "RangePreview".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Range".
+It is an error to set minimum when algorithm is not "Range".
 
 The minimum must match the value set in the encryptedFields of the destination collection.
 It is an error to set a different value.

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_precision.rst

@@ -12,12 +12,11 @@ Synopsis
     mongoc_client_encryption_encrypt_range_opts_set_precision (
          mongoc_client_encryption_encrypt_range_opts_t *range_opts, int32_t precision);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Sets precision for explicit encryption.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
-It is an error to set precision when algorithm is not "RangePreview".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Range".
+It is an error to set precision when algorithm is not "Range".
 
 Precision can only be set with double or decimal128 fields. 
 It is an error to set precision if the type of the encryptedFields in the destination collection is not double or decimal128. 

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_sparsity.rst

@@ -12,12 +12,11 @@ Synopsis
     mongoc_client_encryption_encrypt_range_opts_set_sparsity (
          mongoc_client_encryption_encrypt_range_opts_t *range_opts, int64_t sparsity);
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
 Sets sparsity for explicit encryption. Sparsity is required for explicit encryption of range indexes.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
-It is an error to set sparsity when algorithm is not "RangePreview".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Range".
+It is an error to set sparsity when algorithm is not "Range".
 
 Sparsity must match the value set in the encryptedFields of the destination collection.
 It is an error to set a different value.

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_trim_factor.rst

@@ -0,0 +1,31 @@
+:man_page: mongoc_client_encryption_encrypt_range_opts_set_trim_factor
+
+mongoc_client_encryption_encrypt_range_opts_set_trim_factor()
+=============================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+    void
+    mongoc_client_encryption_encrypt_range_opts_set_trim_factor (
+         mongoc_client_encryption_encrypt_range_opts_t *range_opts, int32_t trim_factor);
+
+.. versionadded:: 1.28.0
+
+Sets trim factor for explicit encryption. Trim factor is required for explicit encryption of range indexes.
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Range".
+It is an error to set trim factor when algorithm is not "Range".
+
+Trim factor must match the value set in the encryptedFields of the destination collection.
+It is an error to set a different value.
+
+Parameters
+----------
+
+* ``range_opts``: A :symbol:`mongoc_client_encryption_encrypt_range_opts_t`
+* ``trim_factor``: A non-negative trim factor.
+
+.. seealso::
+    | :symbol:`mongoc_client_encryption_encrypt_range_opts_t`

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_t.rst

@@ -10,12 +10,11 @@ Synopsis
 
   typedef struct _mongoc_client_encryption_encrypt_range_opts_t mongoc_client_encryption_encrypt_range_opts_t;
 
-.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
 .. versionadded:: 1.24.0
 
-RangeOpts specifies index options for a Queryable Encryption field supporting "rangePreview" queries. Used to set options for :symbol:`mongoc_client_encryption_encrypt()`.
+RangeOpts specifies index options for a Queryable Encryption field supporting "range" queries. Used to set options for :symbol:`mongoc_client_encryption_encrypt()`.
 
-The options min, max, sparsity, and range must match the values set in the encryptedFields of the destination collection.
+The options min, max, trim factor, sparsity, and range must match the values set in the encryptedFields of the destination collection.
 
 For double and decimal128 fields, min/max/precision must all be set, or all be unset.
 
@@ -30,6 +29,7 @@ For double and decimal128 fields, min/max/precision must all be set, or all be u
 
     mongoc_client_encryption_encrypt_range_opts_new
     mongoc_client_encryption_encrypt_range_opts_destroy
+    mongoc_client_encryption_encrypt_range_opts_set_trim_factor
     mongoc_client_encryption_encrypt_range_opts_set_sparsity
     mongoc_client_encryption_encrypt_range_opts_set_min
     mongoc_client_encryption_encrypt_range_opts_set_max

src/libmongoc/src/mongoc/mongoc-client-side-encryption.c

@@ -424,6 +424,7 @@ struct _mongoc_client_encryption_encrypt_range_opts_t {
       bson_value_t value;
       bool set;
    } max;
+   int32_t trim_factor;
    int64_t sparsity;
    struct {
       int32_t value;
@@ -549,6 +550,14 @@ mongoc_client_encryption_encrypt_range_opts_new (void)
    return bson_malloc0 (sizeof (mongoc_client_encryption_encrypt_range_opts_t));
 }
 
+void
+mongoc_client_encryption_encrypt_range_opts_set_trim_factor (mongoc_client_encryption_encrypt_range_opts_t *range_opts,
+                                                             int32_t trim_factor)
+{
+   BSON_ASSERT_PARAM (range_opts);
+   range_opts->trim_factor = trim_factor;
+}
+
 void
 mongoc_client_encryption_encrypt_range_opts_set_sparsity (mongoc_client_encryption_encrypt_range_opts_t *range_opts,
                                                           int64_t sparsity)
@@ -612,6 +621,7 @@ copy_range_opts (const mongoc_client_encryption_encrypt_range_opts_t *opts)
       opts_new->precision.set = true;
    }
    opts_new->sparsity = opts->sparsity;
+   opts_new->trim_factor = opts->trim_factor;
    return opts_new;
 }
 
@@ -991,6 +1001,9 @@ append_bson_range_opts (bson_t *bson_range_opts, const mongoc_client_encryption_
    if (opts->range_opts->sparsity) {
       BSON_ASSERT (BSON_APPEND_INT64 (bson_range_opts, "sparsity", opts->range_opts->sparsity));
    }
+   if (opts->range_opts->trim_factor) {
+      BSON_ASSERT (BSON_APPEND_INT32 (bson_range_opts, "trimFactor", opts->range_opts->trim_factor));
+   }
 }
 
 /*--------------------------------------------------------------------------

src/libmongoc/src/mongoc/mongoc-client-side-encryption.h

@@ -33,9 +33,11 @@ struct _mongoc_database_t;
 #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
 #define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed"
 #define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed"
+#define MONGOC_ENCRYPT_ALGORITHM_RANGE "Range"
 #define MONGOC_ENCRYPT_ALGORITHM_RANGEPREVIEW "RangePreview"
 
 #define MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY "equality"
+#define MONGOC_ENCRYPT_QUERY_TYPE_RANGE "range"
 #define MONGOC_ENCRYPT_QUERY_TYPE_RANGEPREVIEW "rangePreview"
 
 
@@ -247,6 +249,10 @@ mongoc_client_encryption_encrypt_range_opts_new (void);
 MONGOC_EXPORT (void)
 mongoc_client_encryption_encrypt_range_opts_destroy (mongoc_client_encryption_encrypt_range_opts_t *range_opts);
 
+MONGOC_EXPORT (void)
+mongoc_client_encryption_encrypt_range_opts_set_trim_factor (mongoc_client_encryption_encrypt_range_opts_t *range_opts,
+                                                             int32_t trim_factor);
+
 MONGOC_EXPORT (void)
 mongoc_client_encryption_encrypt_range_opts_set_sparsity (mongoc_client_encryption_encrypt_range_opts_t *range_opts,
                                                           int64_t sparsity);

src/libmongoc/src/mongoc/mongoc-crypt.c

@@ -1419,6 +1419,11 @@ _mongoc_crypt_new (const bson_t *kms_providers,
    // Enable the NEEDS_CREDENTIALS state for on-demand credential loading
    mongocrypt_setopt_use_need_kms_credentials_state (crypt->handle);
 
+   if (!mongocrypt_setopt_use_range_v2 (crypt->handle)) {
+      _crypt_check_error (crypt->handle, error, true);
+      goto fail;
+   }
+
    if (!mongocrypt_init (crypt->handle)) {
       _crypt_check_error (crypt->handle, error, true);
       goto fail;

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/range-encryptedFields-Date.json

@@ -10,10 +10,13 @@
       "path": "encryptedDate",
       "bsonType": "date",
       "queries": {
-        "queryType": "rangePreview",
+        "queryType": "range",
         "contention": {
           "$numberLong": "0"
         },
+        "trimFactor": {
+          "$numberLong": "1"
+        },
         "sparsity": {
           "$numberLong": "1"
         },

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/range-encryptedFields-DecimalNoPrecision.json

@@ -10,7 +10,7 @@
       "path": "encryptedDecimalNoPrecision",
       "bsonType": "decimal",
       "queries": {
-        "queryType": "rangePreview",
+        "queryType": "range",
         "contention": {
           "$numberLong": "0"
         },

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/range-encryptedFields-DecimalPrecision.json

@@ -10,10 +10,13 @@
       "path": "encryptedDecimalPrecision",
       "bsonType": "decimal",
       "queries": {
-        "queryType": "rangePreview",
+        "queryType": "range",
         "contention": {
           "$numberLong": "0"
         },
+        "trimFactor": {
+          "$numberLong": "1"
+        },
         "sparsity": {
           "$numberLong": "1"
         },

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/range-encryptedFields-DoubleNoPrecision.json

@@ -10,7 +10,7 @@
       "path": "encryptedDoubleNoPrecision",
       "bsonType": "double",
       "queries": {
-        "queryType": "rangePreview",
+        "queryType": "range",
         "contention": {
           "$numberLong": "0"
         },

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/range-encryptedFields-DoublePrecision.json

@@ -10,10 +10,13 @@
       "path": "encryptedDoublePrecision",
       "bsonType": "double",
       "queries": {
-        "queryType": "rangePreview",
+        "queryType": "range",
         "contention": {
           "$numberLong": "0"
         },
+        "trimFactor": {
+          "$numberLong": "1"
+        },
         "sparsity": {
           "$numberLong": "1"
         },