CDRIVER-4198 let option for CRUD commands (#957)

* Add "let" option to CRUD methods

* mongoc_bulk_operation_set_let

* Support "let" option for delete, update, and findAndModify

* CRUD spec tests for "let" option

Synced with mongodb/specifications@1028c34

Also includes some test changes related to CDRIVER-4063

* Document "let" option for mongoc_collection_find_with_opts

* mongoc_bulk_operation_t tests for "let" option

Author: jmikola

build/generate-opts.py

@@ -151,6 +151,11 @@ def __init__(self, items, **defaults):
     'help': 'A document or string that specifies the index to use to support the query predicate.'
 })
 
+let_option = ('let', {
+    'type': 'document',
+    'help': 'A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.'
+})
+
 opts_structs = OrderedDict([
     ('mongoc_crud_opts_t', Shared([
         write_concern_option,
@@ -164,6 +169,7 @@ def __init__(self, items, **defaults):
         collation_option,
         hint_option,
         upsert_option,
+        let_option,
     ])),
 
     ('mongoc_insert_one_opts_t', Struct([
@@ -181,6 +187,7 @@ def __init__(self, items, **defaults):
         ('crud', {'type': 'mongoc_crud_opts_t'}),
         collation_option,
         hint_option,
+        let_option,
     ])),
 
     ('mongoc_delete_one_opts_t', Struct([
@@ -209,6 +216,7 @@ def __init__(self, items, **defaults):
         write_concern_option,
         ordered_option,
         session_option,
+        let_option,
     ], allow_extra=False, ordered='true')),
 
     ('mongoc_bulk_insert_opts_t', Struct([
@@ -321,13 +329,14 @@ def __init__(self, items, **defaults):
         collation_option,
         server_option,
         ('batchSize', {'type': 'int32_t', 'help': 'An ``int32`` representing number of documents requested to be returned on each call to :symbol:`mongoc_cursor_next`', 'check_set': True}),
-        ('let', {'type': 'document', 'help': 'A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language'})
+        let_option,
     ])),
 
     ('mongoc_find_and_modify_appended_opts_t', Struct([
         write_concern_option,
         session_option,
-        hint_option
+        hint_option,
+        let_option,
     ], opts_name='extra'))
 ])
 

src/libmongoc/doc/includes/aggregate-opts.txt

@@ -12,4 +12,4 @@
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``serverId``: To target a specific server, include an int32 "serverId" field. Obtain the id by calling :symbol:`mongoc_client_select_server`, then :symbol:`mongoc_server_description_id` on its return value.
 * ``batchSize``: An ``int32`` representing number of documents requested to be returned on each call to :symbol:`mongoc_cursor_next`
-* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

src/libmongoc/doc/includes/bulk-opts.txt

@@ -8,3 +8,4 @@
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
 * ``ordered``: set to ``false`` to attempt to insert all documents, continuing after errors.
 * ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

src/libmongoc/doc/includes/delete-many-opts.txt

@@ -10,3 +10,4 @@
 * ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

src/libmongoc/doc/includes/delete-one-opts.txt

@@ -10,3 +10,4 @@
 * ``validate``: Construct a bitwise-or of all desired :symbol:`bson_validate_flags_t <bson_validate_with_error>`. Set to ``false`` to skip client-side validation of the provided BSON documents.
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

src/libmongoc/doc/includes/find-and-modify-appended-opts.txt

@@ -8,3 +8,4 @@
 * ``writeConcern``: Construct a :symbol:`mongoc_write_concern_t` and use :symbol:`mongoc_write_concern_append` to add the write concern to ``opts``. See the example code for :symbol:`mongoc_client_write_command_with_opts`.
 * ``sessionId``: First, construct a :symbol:`mongoc_client_session_t` with :symbol:`mongoc_client_start_session`. You can begin a transaction with :symbol:`mongoc_client_session_start_transaction`, optionally with a :symbol:`mongoc_transaction_opt_t` that overrides the options inherited from |opts-source|, and use :symbol:`mongoc_client_session_append` to add the session to ``opts``. See the example code for :symbol:`mongoc_client_session_t`.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

src/libmongoc/doc/includes/replace-one-opts.txt

@@ -12,3 +12,4 @@
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: When true, creates a new document if no document matches the query.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.

src/libmongoc/doc/includes/update-many-opts.txt

@@ -12,4 +12,5 @@
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: When true, creates a new document if no document matches the query.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.
 * ``arrayFilters``: An array of filters specifying to which array elements an update should apply.

src/libmongoc/doc/includes/update-one-opts.txt

@@ -12,4 +12,5 @@
 * ``collation``: Configure textual comparisons. See :ref:`Setting Collation Order <setting_collation_order>`, and `the MongoDB Manual entry on Collation <https://docs.mongodb.com/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: When true, creates a new document if no document matches the query.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.
 * ``arrayFilters``: An array of filters specifying to which array elements an update should apply.

src/libmongoc/doc/mongoc_bulk_operation_set_let.rst

@@ -0,0 +1,26 @@
+:man_page: mongoc_bulk_operation_set_let
+
+mongoc_bulk_operation_set_let()
+===============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_bulk_operation_set_let (
+     mongoc_bulk_operation_t *bulk, const bson_t *let);
+
+Parameters
+----------
+
+* ``bulk``: A :symbol:`mongoc_bulk_operation_t`.
+* ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.
+
+Description
+-----------
+
+Defines constants that can be accessed by all update, replace, and delete operations executed as part of this :doc:`bulk <mongoc_bulk_operation_t>`.
+
+It is prohibited to call this function after adding operations to the :doc:`bulk <mongoc_bulk_operation_t>`.

src/libmongoc/doc/mongoc_bulk_operation_t.rst

@@ -50,6 +50,7 @@ After adding all of the write operations to the ``mongoc_bulk_operation_t``, cal
     mongoc_bulk_operation_set_bypass_document_validation
     mongoc_bulk_operation_set_client_session
     mongoc_bulk_operation_set_hint
+    mongoc_bulk_operation_set_let
     mongoc_bulk_operation_update
     mongoc_bulk_operation_update_many_with_opts
     mongoc_bulk_operation_update_one

src/libmongoc/doc/mongoc_collection_find_with_opts.rst

@@ -129,7 +129,7 @@ Option                   BSON type           Option               BSON type
 ``awaitData``            bool                ``sessionId``        (none)
 ``collation``            document            ``showRecordId``     bool
 ``comment``              string              ``singleBatch``      bool
-``allowDiskUse``         bool
+``allowDiskUse``         bool                ``let``              document
 =======================  ==================  ===================  ==================
 
 All options are documented in the reference page for `the "find" command`_ in the MongoDB server manual, except for "maxAwaitTimeMS", "sessionId", and "exhaust".

src/libmongoc/src/mongoc/mongoc-bulk-operation-private.h

@@ -33,6 +33,7 @@ struct _mongoc_bulk_operation_t {
    mongoc_client_session_t *session;
    mongoc_write_concern_t *write_concern;
    mongoc_bulk_write_flags_t flags;
+   bson_t let;
    uint32_t server_id;
    mongoc_array_t commands;
    mongoc_write_result_t result;

src/libmongoc/src/mongoc/mongoc-bulk-operation.c

@@ -54,6 +54,8 @@ mongoc_bulk_operation_new (bool ordered)
    bulk->flags.ordered = ordered;
    bulk->server_id = 0;
 
+   bson_init (&bulk->let);
+
    _mongoc_array_init (&bulk->commands, sizeof (mongoc_write_command_t));
    _mongoc_write_result_init (&bulk->result);
 
@@ -102,6 +104,7 @@ mongoc_bulk_operation_destroy (mongoc_bulk_operation_t *bulk) /* IN */
 
       bson_free (bulk->database);
       bson_free (bulk->collection);
+      bson_destroy (&bulk->let);
       mongoc_write_concern_destroy (bulk->write_concern);
       _mongoc_array_destroy (&bulk->commands);
 
@@ -135,7 +138,7 @@ mongoc_bulk_operation_destroy (mongoc_bulk_operation_t *bulk) /* IN */
    } while (0)
 
 
-bool
+static bool
 _mongoc_bulk_operation_remove_with_opts (
    mongoc_bulk_operation_t *bulk,
    const bson_t *selector,
@@ -145,6 +148,7 @@ _mongoc_bulk_operation_remove_with_opts (
 {
    mongoc_write_command_t command = {0};
    mongoc_write_command_t *last;
+   bson_t cmd_opts = BSON_INITIALIZER;
    bson_t opts;
    bool has_collation;
    bool ret = false;
@@ -193,8 +197,12 @@ _mongoc_bulk_operation_remove_with_opts (
       }
    }
 
+   if (!bson_empty (&bulk->let)) {
+      bson_append_document (&cmd_opts, "let", 3, &bulk->let);
+   }
+
    _mongoc_write_command_init_delete (
-      &command, selector, NULL, &opts, bulk->flags, bulk->operation_id);
+      &command, selector, &cmd_opts, &opts, bulk->flags, bulk->operation_id);
 
    command.flags.has_collation = has_collation;
    command.flags.has_delete_hint = has_delete_hint;
@@ -204,6 +212,7 @@ _mongoc_bulk_operation_remove_with_opts (
    ret = true;
 
 done:
+   bson_destroy (&cmd_opts);
    bson_destroy (&opts);
    RETURN (ret);
 }
@@ -408,6 +417,7 @@ _mongoc_bulk_operation_update_append (
 {
    mongoc_write_command_t command = {0};
    mongoc_write_command_t *last;
+   bson_t cmd_opts = BSON_INITIALIZER;
    bson_t opts;
    bool has_collation;
    bool has_array_filters;
@@ -445,20 +455,31 @@ _mongoc_bulk_operation_update_append (
          last->flags.has_update_hint |= has_update_hint;
          last->flags.has_multi_write |= update_opts->multi;
          _mongoc_write_command_update_append (last, selector, document, &opts);
-         bson_destroy (&opts);
-         return;
+         GOTO (done);
       }
    }
 
-   _mongoc_write_command_init_update (
-      &command, selector, document, &opts, bulk->flags, bulk->operation_id);
+   if (!bson_empty (&bulk->let)) {
+      bson_append_document (&cmd_opts, "let", 3, &bulk->let);
+   }
+
+   _mongoc_write_command_init_update (&command,
+                                      selector,
+                                      document,
+                                      &cmd_opts,
+                                      &opts,
+                                      bulk->flags,
+                                      bulk->operation_id);
 
    command.flags.has_array_filters = has_array_filters;
    command.flags.has_collation = has_collation;
    command.flags.has_update_hint = has_update_hint;
    command.flags.has_multi_write = update_opts->multi;
 
    _mongoc_array_append_val (&bulk->commands, command);
+
+done:
+   bson_destroy (&cmd_opts);
    bson_destroy (&opts);
 }
 
@@ -950,3 +971,20 @@ mongoc_bulk_operation_set_bypass_document_validation (
 
    bulk->flags.bypass_document_validation = bypass;
 }
+
+
+void
+mongoc_bulk_operation_set_let (mongoc_bulk_operation_t *bulk, const bson_t *let)
+{
+   BSON_ASSERT (bulk);
+   BSON_ASSERT (let);
+
+   /* This method cannot be called after appending operations, as the CRUD spec
+    * states the option should apply to all commands (excluding insert). Since
+    * commands are initialized as operations are added, allowing "let" to be
+    * changed at any time could violate that contract. */
+   BSON_ASSERT (bulk->commands.len == 0);
+
+   bson_destroy (&bulk->let);
+   bson_copy_to (let, &bulk->let);
+}

src/libmongoc/src/mongoc/mongoc-bulk-operation.h

@@ -115,6 +115,9 @@ mongoc_bulk_operation_update_one_with_opts (mongoc_bulk_operation_t *bulk,
 MONGOC_EXPORT (void)
 mongoc_bulk_operation_set_bypass_document_validation (
    mongoc_bulk_operation_t *bulk, bool bypass);
+MONGOC_EXPORT (void)
+mongoc_bulk_operation_set_let (
+   mongoc_bulk_operation_t *bulk, const bson_t *let);
 
 
 /*