CDRIVER-5636 make trimFactor and sparsity optional (#1677)

* add spec test

* add prose test

* distinguish between 0 and unset for `sparsity` and `trimFactor`

* update version libmongocrypt

* update docs

---------

Co-authored-by: Ezra Chung <[email protected]>

Author: kevinAlbs

.evergreen/scripts/compile-libmongocrypt.sh

@@ -10,12 +10,12 @@ compile_libmongocrypt() {
   # `.evergreen/scripts/kms-divergence-check.sh` to ensure that there is no
   # divergence in the copied files.
 
-  # TODO: once 1.10.2 is released (containing MONGOCRYPT-706) replace the following with:
-  # git clone -q --depth=1 https://github.com/mongodb/libmongocrypt --branch 1.10.2 || return
+  # TODO: once 1.11.0 is released (containing MONGOCRYPT-698) replace the following with:
+  # git clone -q --depth=1 https://github.com/mongodb/libmongocrypt --branch 1.11.0 || return
   {
     git clone -q https://github.com/mongodb/libmongocrypt || return
-    # Check out commit containing MONGOCRYPT-706
-    git -C libmongocrypt checkout 06dedd42351b9adce146eaa0e971e793d8676e49
+    # Check out commit containing MONGOCRYPT-698
+    git -C libmongocrypt checkout 14ccd9ce8a030158aec07f63e8139d34b95d88e6
   }
 
   declare -a crypt_cmake_flags=(

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_sparsity.rst

@@ -14,10 +14,12 @@ Synopsis
 
 .. versionadded:: 1.24.0
 
-Sets sparsity for explicit encryption. Sparsity is required for explicit encryption of range indexes.
+Sets sparsity for explicit encryption.
 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 may be used to tune performance. When omitted, a default value is used.
+
 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

@@ -14,10 +14,12 @@ Synopsis
 
 .. versionadded:: 1.28.0
 
-Sets trim factor for explicit encryption. Trim factor is required for explicit encryption of range indexes.
+Sets trim factor for explicit encryption.
 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".
 
+The trim factor may be used to tune performance. When omitted, a default value is used.
+
 Trim factor must match the value set in the encryptedFields of the destination collection.
 It is an error to set a different value.
 

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

@@ -424,8 +424,14 @@ 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;
+      bool set;
+   } trim_factor;
+   struct {
+      int64_t value;
+      bool set;
+   } sparsity;
    struct {
       int32_t value;
       bool set;
@@ -555,15 +561,17 @@ mongoc_client_encryption_encrypt_range_opts_set_trim_factor (mongoc_client_encry
                                                              int32_t trim_factor)
 {
    BSON_ASSERT_PARAM (range_opts);
-   range_opts->trim_factor = trim_factor;
+   range_opts->trim_factor.set = true;
+   range_opts->trim_factor.value = trim_factor;
 }
 
 void
 mongoc_client_encryption_encrypt_range_opts_set_sparsity (mongoc_client_encryption_encrypt_range_opts_t *range_opts,
                                                           int64_t sparsity)
 {
    BSON_ASSERT_PARAM (range_opts);
-   range_opts->sparsity = sparsity;
+   range_opts->sparsity.set = true;
+   range_opts->sparsity.value = sparsity;
 }
 
 void
@@ -998,11 +1006,11 @@ append_bson_range_opts (bson_t *bson_range_opts, const mongoc_client_encryption_
    if (opts->range_opts->precision.set) {
       BSON_ASSERT (BSON_APPEND_INT32 (bson_range_opts, "precision", opts->range_opts->precision.value));
    }
-   if (opts->range_opts->sparsity) {
-      BSON_ASSERT (BSON_APPEND_INT64 (bson_range_opts, "sparsity", opts->range_opts->sparsity));
+   if (opts->range_opts->sparsity.set) {
+      BSON_ASSERT (BSON_APPEND_INT64 (bson_range_opts, "sparsity", opts->range_opts->sparsity.value));
    }
-   if (opts->range_opts->trim_factor) {
-      BSON_ASSERT (BSON_APPEND_INT32 (bson_range_opts, "trimFactor", opts->range_opts->trim_factor));
+   if (opts->range_opts->trim_factor.set) {
+      BSON_ASSERT (BSON_APPEND_INT32 (bson_range_opts, "trimFactor", opts->range_opts->trim_factor.value));
    }
 }