mongo 2.17.2 → 2.18.1

data/lib/mongo/collection/view/writable.rb

@@ -50,6 +50,8 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
         # @return [ BSON::Document, nil ] The document, if found.
         #
@@ -61,9 +63,6 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -77,21 +76,30 @@ module Mongo
               bypassDocumentValidation: opts[:bypass_document_validation],
               hint: opts[:hint],
               collation: opts[:collation] || opts['collation'] || collation,
-              let: opts[:let]
+              let: opts[:let],
+              comment: opts[:comment],
             }.compact
 
-            write_with_retry(session, write_concern) do |server, txn_num|
+            context = Operation::Context.new(client: client, session: session)
+            write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_4 = connection.server.description.server_version_gte?('4.4')
+              if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::WriteCommand.new(
                 selector: cmd,
                 db_name: database.name,
                 write_concern: write_concern,
                 session: session,
                 txn_num: txn_num,
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+              ).execute_with_connection(connection, context: context)
             end
-          end.first['value']
+          end.first&.fetch('value', nil)
         end
 
+        # db['users'].bulk_write([{insert_one: {x: 1}}, {insert_one: {x: 2}}])
+
         # Finds a single document and replaces it.
         #
         # @example Find a document and replace it, returning the original.
@@ -149,8 +157,10 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
-        # @return [ BSON::Document ] The document.
+        # @return [ BSON::Document | nil ] The document or nil if none is found.
         #
         # @since 2.0.0
         def find_one_and_update(document, opts = {})
@@ -160,9 +170,6 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -180,18 +187,25 @@ module Mongo
               hint: opts[:hint],
               collation: opts[:collation] || opts['collation'] || collation,
               let: opts[:let],
+              comment: opts[:comment]
             }.compact
 
-            write_with_retry(session, write_concern) do |server, txn_num|
+            context = Operation::Context.new(client: client, session: session)
+            write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_4 = connection.server.description.server_version_gte?('4.4')
+              if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::WriteCommand.new(
                 selector: cmd,
                 db_name: database.name,
                 write_concern: write_concern,
                 session: session,
                 txn_num: txn_num,
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+              ).execute_with_connection(connection, context: context)
             end
-          end.first['value']
+          end.first&.fetch('value', nil)
           value unless value.nil? || value.empty?
         end
 
@@ -210,6 +224,8 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
         # @return [ Result ] The response from the database.
         #
@@ -221,9 +237,6 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -234,7 +247,13 @@ module Mongo
               collation: opts[:collation] || opts['collation'] || collation,
             }.compact
 
-            nro_write_with_retry(session, write_concern) do |server|
+            context = Operation::Context.new(client: client, session: session)
+            nro_write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_4 = connection.server.description.server_version_gte?('4.4')
+              if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::Delete.new(
                 deletes: [ delete_doc ],
                 db_name: collection.database.name,
@@ -243,7 +262,8 @@ module Mongo
                 bypass_document_validation: !!opts[:bypass_document_validation],
                 session: session,
                 let: opts[:let],
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+                comment: opts[:comment],
+              ).execute_with_connection(connection, context: context)
             end
           end
         end
@@ -263,6 +283,8 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
         # @return [ Result ] The response from the database.
         #
@@ -274,9 +296,6 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -287,7 +306,13 @@ module Mongo
               collation: opts[:collation] || opts['collation'] || collation,
             }.compact
 
-            write_with_retry(session, write_concern) do |server, txn_num|
+            context = Operation::Context.new(client: client, session: session)
+            write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_4 = connection.server.description.server_version_gte?('4.4')
+              if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::Delete.new(
                 deletes: [ delete_doc ],
                 db_name: collection.database.name,
@@ -297,7 +322,8 @@ module Mongo
                 session: session,
                 txn_num: txn_num,
                 let: opts[:let],
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+                comment: opts[:comment],
+              ).execute_with_connection(connection, context: context)
             end
           end
         end
@@ -322,6 +348,8 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
         # @return [ Result ] The response from the database.
         #
@@ -333,9 +361,7 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
+            validate_replacement_documents!(replacement)
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -350,7 +376,13 @@ module Mongo
               update_doc['upsert'] = true
             end
 
-            write_with_retry(session, write_concern) do |server, txn_num|
+            context = Operation::Context.new(client: client, session: session)
+            write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_2 = connection.server.description.server_version_gte?('4.2')
+              if !gte_4_2 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::Update.new(
                 updates: [ update_doc ],
                 db_name: collection.database.name,
@@ -359,8 +391,9 @@ module Mongo
                 bypass_document_validation: !!opts[:bypass_document_validation],
                 session: session,
                 txn_num: txn_num,
-                let: opts[:let]
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+                let: opts[:let],
+                comment: opts[:comment],
+              ).execute_with_connection(connection, context: context)
             end
           end
         end
@@ -387,6 +420,8 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
         # @return [ Result ] The response from the database.
         #
@@ -398,9 +433,7 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
+            validate_update_documents!(spec)
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -416,7 +449,13 @@ module Mongo
               update_doc['upsert'] = true
             end
 
-            nro_write_with_retry(session, write_concern) do |server|
+            context = Operation::Context.new(client: client, session: session)
+            nro_write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_2 = connection.server.description.server_version_gte?('4.2')
+              if !gte_4_2 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::Update.new(
                 updates: [ update_doc ],
                 db_name: collection.database.name,
@@ -425,7 +464,8 @@ module Mongo
                 bypass_document_validation: !!opts[:bypass_document_validation],
                 session: session,
                 let: opts[:let],
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+                comment: opts[:comment],
+              ).execute_with_connection(connection, context: context)
             end
           end
         end
@@ -452,6 +492,8 @@ module Mongo
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
         # @option options [ Hash ] :let Mapping of variables to use in the command.
         #   See the server documentation for details.
+        # @option options [ Object ] :comment A user-provided
+        #   comment to attach to this command.
         #
         # @return [ Result ] The response from the database.
         #
@@ -463,9 +505,7 @@ module Mongo
             else
               write_concern_with_session(session)
             end
-            if opts[:hint] && write_concern && !write_concern.acknowledged?
-              raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-            end
+            validate_update_documents!(spec)
 
             QueryCache.clear_namespace(collection.namespace)
 
@@ -480,7 +520,13 @@ module Mongo
               update_doc['upsert'] = true
             end
 
-            write_with_retry(session, write_concern) do |server, txn_num|
+            context = Operation::Context.new(client: client, session: session)
+            write_with_retry(write_concern, context: context) do |connection, txn_num, context|
+              gte_4_2 = connection.server.description.server_version_gte?('4.2')
+              if !gte_4_2 && opts[:hint] && write_concern && !write_concern.acknowledged?
+                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
+              end
+
               Operation::Update.new(
                 updates: [ update_doc ],
                 db_name: collection.database.name,
@@ -490,7 +536,54 @@ module Mongo
                 session: session,
                 txn_num: txn_num,
                 let: opts[:let],
-              ).execute(server, context: Operation::Context.new(client: client, session: session))
+                comment: opts[:comment],
+              ).execute_with_connection(connection, context: context)
+            end
+          end
+        end
+
+        private
+
+        # Checks the update documents to make sure they only have atomic modifiers.
+        # Note that as per the spec, we only have to examine the first element
+        # in the update document.
+        #
+        # @param [ Hash | Array<Hash> ] spec The update document or pipeline.
+        #
+        # @raise [ Error::InvalidUpdateDocument ] if the first key in the
+        #   document does not start with a $.
+        def validate_update_documents!(spec)
+          if update = spec.is_a?(Array) ? spec&.first : spec
+            if key = update.keys&.first
+              unless key.to_s.start_with?("$")
+                if Mongo.validate_update_replace
+                  raise Error::InvalidUpdateDocument.new(key: key)
+                else
+                  Error::InvalidUpdateDocument.warn(Logger.logger, key)
+                end
+              end
+            end
+          end
+        end
+
+        # Check the replacement documents to make sure they don't have atomic
+        # modifiers. Note that as per the spec, we only have to examine the
+        # first element in the replacement document.
+        #
+        # @param [ Hash | Array<Hash> ] spec The replacement document or pipeline.
+        #
+        # @raise [ Error::InvalidUpdateDocument ] if the first key in the
+        #   document does not start with a $.
+        def validate_replacement_documents!(spec)
+          if replace = spec.is_a?(Array) ? spec&.first : spec
+            if key = replace.keys&.first
+              if key.to_s.start_with?("$")
+                if Mongo.validate_update_replace
+                  raise Error::InvalidReplacementDocument.new(key: key)
+                else
+                  Error::InvalidReplacementDocument.warn(Logger.logger, key)
+                end
+              end
             end
           end
         end

data/lib/mongo/collection.rb

@@ -17,6 +17,8 @@
 
 require 'mongo/bulk_write'
 require 'mongo/collection/view'
+require 'mongo/collection/helpers'
+require 'mongo/collection/queryable_encryption'
 
 module Mongo
 
@@ -27,6 +29,8 @@ module Mongo
   class Collection
     extend Forwardable
     include Retryable
+    include QueryableEncryption
+    include Helpers
 
     # The capped option.
     #
@@ -47,8 +51,8 @@ module Mongo
     # @return [ Hash ] The collection options.
     attr_reader :options
 
-    # Get client, cluster, read preference, and write concern from client.
-    def_delegators :database, :client, :cluster
+    # Get client, cluster, read preference, write concern, and encrypted_fields_map from client.
+    def_delegators :database, :client, :cluster, :encrypted_fields_map
 
     # Delegate to the cluster for the next primary.
     def_delegators :cluster, :next_primary
@@ -58,10 +62,17 @@ module Mongo
     # @since 2.1.0
     CHANGEABLE_OPTIONS = [ :read, :read_concern, :write, :write_concern ].freeze
 
-    # Options that can be used for creating a time-series collection.
-    TIME_SERIES_OPTIONS = {
+    # Options map to transform create collection options.
+    #
+    # @api private
+    CREATE_COLLECTION_OPTIONS = {
       :time_series => :timeseries,
-      :expire_after => :expireAfterSeconds
+      :expire_after => :expireAfterSeconds,
+      :clustered_index => :clusteredIndex,
+      :change_stream_pre_and_post_images => :changeStreamPreAndPostImages,
+      :encrypted_fields => :encryptedFields,
+      :validator => :validator,
+      :view_on => :viewOn
     }
 
     # Check if a collection is equal to another object. Will check the name and
@@ -94,10 +105,14 @@ module Mongo
     # @option options [ Hash ] :write_concern The write concern options.
     #   Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.
     # @option options [ Hash ] :time_series Create a time-series collection.
-    #   See https://docs.mongodb.com/manual/core/timeseries-collections/ for more
+    #   See https://mongodb.com/docs/manual/core/timeseries-collections/ for more
     #   information about time-series collection.
     # @option options [ Integer ] :expire_after Number indicating
     #   after how many seconds old time-series data should be deleted.
+    # @options clustered_index [ Hash ] :clustered_index Create a clustered index.
+    #   This option specifies how this collection should be clustered on _id.
+    #   See https://www.mongodb.com/docs/v5.3/reference/method/db.createCollection/#std-label-db.createCollection.clusteredIndex
+    #   for more information about this option.
     #
     # @since 2.0.0
     def initialize(database, name, options = {})
@@ -241,6 +256,12 @@ module Mongo
     # @option opts [ Hash ] :time_series Create a time-series collection.
     # @option opts [ Integer ] :expire_after Number indicating
     #   after how many seconds old time-series data should be deleted.
+    # @option opts [ Hash ] :change_stream_pre_and_post_images Used to enable
+    #   pre- and post-images on the created collection.
+    # @option opts [ Hash ] :encrypted_fields Hash describing encrypted fields
+    #   for queryable encryption.
+    # @option opts [ Hash ] :validator Hash describing document validation
+    #   options for the collection.
     #
     # @return [ Result ] The result of the command.
     #
@@ -253,9 +274,9 @@ module Mongo
       options = Hash[self.options.reject do |key, value|
         %w(read read_preference read_concern).include?(key.to_s)
       end]
-      options.update(opts.slice(*TIME_SERIES_OPTIONS.keys))
-      # Converting Ruby spelled time series options to server style.
-      TIME_SERIES_OPTIONS.each do |ruby_key, server_key|
+      options.update(opts.slice(*CREATE_COLLECTION_OPTIONS.keys))
+      # Converting Ruby options to server style.
+      CREATE_COLLECTION_OPTIONS.each do |ruby_key, server_key|
         if options.key?(ruby_key)
           options[server_key] = options.delete(ruby_key)
         end
@@ -271,20 +292,24 @@ module Mongo
         end
 
         context = Operation::Context.new(client: client, session: session)
-        Operation::Create.new(
-          selector: operation,
-          db_name: database.name,
-          write_concern: write_concern,
-          session: session,
-          # Note that these are collection options, collation isn't
-          # taken from options passed to the create method.
-          collation: options[:collation] || options['collation'],
-        ).execute(next_primary(nil, session), context: context)
+        maybe_create_qe_collections(opts[:encrypted_fields], client, session) do |encrypted_fields|
+          Operation::Create.new(
+            selector: operation,
+            db_name: database.name,
+            write_concern: write_concern,
+            session: session,
+            # Note that these are collection options, collation isn't
+            # taken from options passed to the create method.
+            collation: options[:collation] || options['collation'],
+            encrypted_fields: encrypted_fields,
+            validator: options[:validator],
+          ).execute(next_primary(nil, session), context: context)
+        end
       end
     end
 
     # Drop the collection. Will also drop all indexes associated with the
-    # collection.
+    # collection, as well as associated queryable encryption collections.
     #
     # @note An error returned if the collection doesn't exist is suppressed.
     #
@@ -301,25 +326,22 @@ module Mongo
     # @since 2.0.0
     def drop(opts = {})
       client.send(:with_session, opts) do |session|
-        temp_write_concern = write_concern
-        write_concern = if opts[:write_concern]
-          WriteConcern.get(opts[:write_concern])
-        else
-          temp_write_concern
+        maybe_drop_emm_collections(opts[:encrypted_fields], client, session) do
+          temp_write_concern = write_concern
+          write_concern = if opts[:write_concern]
+            WriteConcern.get(opts[:write_concern])
+          else
+            temp_write_concern
+          end
+          context = Operation::Context.new(client: client, session: session)
+          operation = Operation::Drop.new({
+            selector: { :drop => name },
+            db_name: database.name,
+            write_concern: write_concern,
+            session: session,
+          })
+          do_drop(operation, session, context)
         end
-        Operation::Drop.new({
-                              selector: { :drop => name },
-                              db_name: database.name,
-                              write_concern: write_concern,
-                              session: session,
-                              }).execute(next_primary(nil, session), context: Operation::Context.new(client: client, session: session))
-      end
-    rescue Error::OperationFailure => ex
-      # NamespaceNotFound
-      if ex.code == 26 || ex.code.nil? && ex.message =~ /ns not found/
-        false
-      else
-        raise
       end
     end
 
@@ -343,7 +365,8 @@ module Mongo
     # @option options [ Integer ] :batch_size The number of documents returned in each batch
     #   of results from MongoDB.
     # @option options [ Hash ] :collation The collation to use.
-    # @option options [ String ] :comment Associate a comment with the query.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     # @option options [ :tailable, :tailable_await ] :cursor_type The type of cursor to use.
     # @option options [ Integer ] :limit The max number of docs to return from the query.
     # @option options [ Integer ] :max_time_ms
@@ -386,7 +409,8 @@ module Mongo
     # @option options [ true, false ] :bypass_document_validation Whether or
     #   not to skip document level validation.
     # @option options [ Hash ] :collation The collation to use.
-    # @option options [ String ] :comment Associate a comment with the aggregation.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     # @option options [ String ] :hint The index to use for the aggregation.
     # @option options [ Hash ] :let Mapping of variables to use in the pipeline.
     #   See the server documentation for details.
@@ -416,11 +440,35 @@ module Mongo
     # @param [ Array<Hash> ] pipeline Optional additional filter operators.
     # @param [ Hash ] options The change stream options.
     #
-    # @option options [ String ] :full_document Allowed values: ‘default’,
-    #   ‘updateLookup’. Defaults to ‘default’. When set to ‘updateLookup’,
-    #   the change notification for partial updates will include both a delta
-    #   describing the changes to the document, as well as a copy of the entire
-    #   document that was changed from some time after the change occurred.
+    # @option options [ String ] :full_document Allowed values: nil, 'default',
+    #   'updateLookup', 'whenAvailable', 'required'.
+    #
+    #   The default is to not send a value (i.e. nil), which is equivalent to
+    #   'default'. By default, the change notification for partial updates will
+    #   include a delta describing the changes to the document.
+    #
+    #   When set to 'updateLookup', the change notification for partial updates
+    #   will include both a delta describing the changes to the document as well
+    #   as a copy of the entire document that was changed from some time after
+    #   the change occurred.
+    #
+    #   When set to 'whenAvailable', configures the change stream to return the
+    #   post-image of the modified document for replace and update change events
+    #   if the post-image for this event is available.
+    #
+    #   When set to 'required', the same behavior as 'whenAvailable' except that
+    #   an error is raised if the post-image is not available.
+    # @option options [ String ] :full_document_before_change Allowed values: nil,
+    #   'whenAvailable', 'required', 'off'.
+    #
+    #   The default is to not send a value (i.e. nil), which is equivalent to 'off'.
+    #
+    #   When set to 'whenAvailable', configures the change stream to return the
+    #   pre-image of the modified document for replace, update, and delete change
+    #   events if it is available.
+    #
+    #   When set to 'required', the same behavior as 'whenAvailable' except that
+    #   an error is raised if the pre-image is not available.
     # @option options [ BSON::Document, Hash ] :resume_after Specifies the
     #   logical starting point for the new change stream.
     # @option options [ Integer ] :max_await_time_ms The maximum amount of time
@@ -433,6 +481,13 @@ module Mongo
     #   changes that occurred at or after the specified timestamp. Any command run
     #   against the server will return a cluster time that can be used here.
     #   Only recognized by server versions 4.0+.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @option options [ Boolean ] :show_expanded_events Enables the server to
+    #   send the 'expanded' list of change stream events. The list of additional
+    #   events included with this flag set are: createIndexes, dropIndexes,
+    #   modify, create, shardCollection, reshardCollection,
+    #   refineCollectionShardKey.
     #
     # @note A change stream only allows 'majority' read concern.
     # @note This helper method is preferable to running a raw aggregation with
@@ -442,7 +497,9 @@ module Mongo
     #
     # @since 2.5.0
     def watch(pipeline = [], options = {})
-      View::ChangeStream.new(View.new(self, {}, options), pipeline, nil, options)
+      view_options = options.dup
+      view_options[:await_data] = true if options[:max_await_time_ms]
+      View::ChangeStream.new(View.new(self, {}, view_options), pipeline, nil, options)
     end
 
     # Gets an estimated number of matching documents in the collection.
@@ -460,6 +517,8 @@ module Mongo
     # @option options [ Hash ] :read The read preference options.
     # @option options [ Hash ] :collation The collation to use.
     # @option options [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Integer ] The document count.
     #
@@ -493,6 +552,9 @@ module Mongo
     #   command to run.
     # @option options :read [ Hash ] The read preference options.
     # @option options :collation [ Hash ] The collation to use.
+    # @option options [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Integer ] The document count.
     #
@@ -509,9 +571,11 @@ module Mongo
     #
     # @param [ Hash ] options Options for the operation.
     #
-    # @option opts :max_time_ms [ Integer ] The maximum amount of time to allow
+    # @option options :max_time_ms [ Integer ] The maximum amount of time to allow
     #   the command to run for on the server.
-    # @option opts [ Hash ] :read The read preference options.
+    # @option options [ Hash ] :read The read preference options.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Integer ] The document count.
     #
@@ -597,7 +661,8 @@ module Mongo
           raise ArgumentError, "Document to be inserted cannot be nil"
         end
 
-        write_with_retry(session, write_concern) do |server, txn_num|
+        context = Operation::Context.new(client: client, session: session)
+        write_with_retry(write_concern, context: context) do |connection, txn_num, context|
           Operation::Insert.new(
             :documents => [ document ],
             :db_name => database.name,
@@ -608,7 +673,8 @@ module Mongo
             :id_generator => client.options[:id_generator],
             :session => session,
             :txn_num => txn_num,
-          ).execute(server, context: Operation::Context.new(client: client, session: session))
+            :comment => opts[:comment]
+          ).execute_with_connection(connection, context: context)
         end
       end
     end
@@ -650,6 +716,8 @@ module Mongo
     # @option options [ true, false ] :bypass_document_validation Whether or
     #   not to skip document level validation.
     # @option options [ Session ] :session The session to use for the set of operations.
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ BulkWrite::Result ] The result of the operation.
     #