mongo 2.9.2 → 2.10.0.rc0

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

@@ -34,7 +34,15 @@ module Mongo
         #
         # @param [ Hash ] opts The options.
         #
+        # @option opts [ Integer ] :max_time_ms The maximum amount of time to allow the command
+        #   to run in milliseconds.
+        # @option opts [ Hash ] :projection The fields to include or exclude in the returned doc.
+        # @option opts [ Hash ] :sort The key and direction pairs by which the result set
+        #   will be sorted.
+        # @option opts [ Hash ] :write_concern The write concern options.
+        #   Defaults to the collection's write concern.
         # @option opts [ Hash ] :collation The collation to use.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ BSON::Document, nil ] The document, if found.
         #
@@ -44,10 +52,11 @@ module Mongo
           cmd[:fields] = projection if projection
           cmd[:sort] = sort if sort
           cmd[:maxTimeMS] = max_time_ms if max_time_ms
-          cmd[:writeConcern] = write_concern.options if write_concern
 
           with_session(opts) do |session|
-            write_with_retry(session, write_concern) do |server, txn_num|
+            applied_write_concern = applied_write_concern(session)
+            cmd[:writeConcern] = applied_write_concern.options if applied_write_concern
+            write_with_retry(session, applied_write_concern) do |server, txn_num|
               apply_collation!(cmd, server, opts)
               Operation::Command.new(
                   :selector => cmd,
@@ -93,6 +102,11 @@ module Mongo
         # @param [ BSON::Document ] document The updates.
         # @param [ Hash ] opts The options.
         #
+        # @option options [ Integer ] :max_time_ms The maximum amount of time to allow the command
+        #   to run in milliseconds.
+        # @option opts [ Hash ] :projection The fields to include or exclude in the returned doc.
+        # @option opts [ Hash ] :sort The key and direction pairs by which the result set
+        #   will be sorted.
         # @option opts [ Symbol ] :return_document Either :before or :after.
         # @option opts [ true, false ] :upsert Whether to upsert if the document doesn't exist.
         # @option opts [ true, false ] :bypass_document_validation Whether or
@@ -102,6 +116,7 @@ module Mongo
         # @option opts [ Hash ] :collation The collation to use.
         # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
         # an update should apply.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ BSON::Document ] The document.
         #
@@ -115,10 +130,11 @@ module Mongo
           cmd[:upsert] = opts[:upsert] if opts[:upsert]
           cmd[:maxTimeMS] = max_time_ms if max_time_ms
           cmd[:bypassDocumentValidation] = !!opts[:bypass_document_validation]
-          cmd[:writeConcern] = write_concern.options if write_concern
 
           value = with_session(opts) do |session|
-            write_with_retry(session, write_concern) do |server, txn_num|
+            applied_write_concern = applied_write_concern(opts[:session])
+            cmd[:writeConcern] = applied_write_concern.options if applied_write_concern
+            write_with_retry(session, applied_write_concern) do |server, txn_num|
               apply_collation!(cmd, server, opts)
               apply_array_filters!(cmd, server, opts)
               Operation::Command.new(
@@ -140,6 +156,7 @@ module Mongo
         # @param [ Hash ] opts The options.
         #
         # @option opts [ Hash ] :collation The collation to use.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ Result ] The response from the database.
         #
@@ -147,13 +164,14 @@ module Mongo
         def delete_many(opts = {})
           delete_doc = { Operation::Q => filter, Operation::LIMIT => 0 }
           with_session(opts) do |session|
-            legacy_write_with_retry do |server|
+            write_concern = write_concern_with_session(session)
+            nro_write_with_retry(session, write_concern) do |server|
               apply_collation!(delete_doc, server, opts)
               Operation::Delete.new(
                   :deletes => [ delete_doc ],
                   :db_name => collection.database.name,
                   :coll_name => collection.name,
-                  :write_concern => collection.write_concern,
+                  :write_concern => write_concern,
                   :session => session
               ).execute(server)
             end
@@ -168,14 +186,15 @@ module Mongo
         # @param [ Hash ] opts The options.
         #
         # @option opts [ Hash ] :collation The collation to use.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ Result ] The response from the database.
         #
         # @since 2.0.0
         def delete_one(opts = {})
           delete_doc = { Operation::Q => filter, Operation::LIMIT => 1 }
-          write_concern = collection.write_concern
           with_session(opts) do |session|
+            write_concern = write_concern_with_session(session)
             write_with_retry(session, write_concern) do |server, txn_num|
               apply_collation!(delete_doc, server, opts)
               Operation::Delete.new(
@@ -200,7 +219,10 @@ module Mongo
         #
         # @option opts [ true, false ] :upsert Whether to upsert if the
         #   document doesn't exist.
+        # @option opts [ true, false ] :bypass_document_validation Whether or
+        #   not to skip document level validation.
         # @option opts [ Hash ] :collation The collation to use.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ Result ] The response from the database.
         #
@@ -208,11 +230,12 @@ module Mongo
         def replace_one(replacement, opts = {})
           update_doc = { Operation::Q => filter,
                          Operation::U => replacement,
-                         Operation::MULTI => false,
-                         Operation::UPSERT => !!opts[:upsert]
                         }
-          write_concern = collection.write_concern
+          if opts[:upsert]
+            update_doc[:upsert] = true
+          end
           with_session(opts) do |session|
+            write_concern = write_concern_with_session(session)
             write_with_retry(session, write_concern) do |server, txn_num|
               apply_collation!(update_doc, server, opts)
               apply_array_filters!(update_doc, server, opts)
@@ -235,14 +258,17 @@ module Mongo
         # @example Update multiple documents in the collection.
         #   collection_view.update_many('$set' => { name: 'test' })
         #
-        # @param [ Hash ] spec The update statement.
+        # @param [ Hash | Array<Hash> ] spec The update document or pipeline.
         # @param [ Hash ] opts The options.
         #
         # @option opts [ true, false ] :upsert Whether to upsert if the
         #   document doesn't exist.
+        # @option opts [ true, false ] :bypass_document_validation Whether or
+        #   not to skip document level validation.
         # @option opts [ Hash ] :collation The collation to use.
-        # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
-        #   an update should apply.
+        # @option opts [ Array ] :array_filters A set of filters specifying to
+        #   which array elements an update should apply.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ Result ] The response from the database.
         #
@@ -251,16 +277,20 @@ module Mongo
           update_doc = { Operation::Q => filter,
                          Operation::U => spec,
                          Operation::MULTI => true,
-                         Operation::UPSERT => !!opts[:upsert] }
+                         }
+          if opts[:upsert]
+            update_doc[:upsert] = true
+          end
           with_session(opts) do |session|
-            legacy_write_with_retry do |server|
+            write_concern = write_concern_with_session(session)
+            nro_write_with_retry(session, write_concern) do |server|
               apply_collation!(update_doc, server, opts)
               apply_array_filters!(update_doc, server, opts)
               Operation::Update.new(
                   :updates => [ update_doc ],
                   :db_name => collection.database.name,
                   :coll_name => collection.name,
-                  :write_concern => collection.write_concern,
+                  :write_concern => write_concern,
                   :bypass_document_validation => !!opts[:bypass_document_validation],
                   :session => session
               ).execute(server)
@@ -273,14 +303,17 @@ module Mongo
         # @example Update a single document in the collection.
         #   collection_view.update_one('$set' => { name: 'test' })
         #
-        # @param [ Hash ] spec The update statement.
+        # @param [ Hash | Array<Hash> ] spec The update document or pipeline.
         # @param [ Hash ] opts The options.
         #
         # @option opts [ true, false ] :upsert Whether to upsert if the
         #   document doesn't exist.
+        # @option opts [ true, false ] :bypass_document_validation Whether or
+        #   not to skip document level validation.
         # @option opts [ Hash ] :collation The collation to use.
-        # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
-        #   an update should apply.
+        # @option opts [ Array ] :array_filters A set of filters specifying to
+        #   which array elements an update should apply.
+        # @option opts [ Session ] :session The session to use.
         #
         # @return [ Result ] The response from the database.
         #
@@ -288,10 +321,12 @@ module Mongo
         def update_one(spec, opts = {})
           update_doc = { Operation::Q => filter,
                          Operation::U => spec,
-                         Operation::MULTI => false,
-                         Operation::UPSERT => !!opts[:upsert] }
-          write_concern = collection.write_concern
+                         }
+          if opts[:upsert]
+            update_doc[:upsert] = true
+          end
           with_session(opts) do |session|
+            write_concern = write_concern_with_session(session)
             write_with_retry(session, write_concern) do |server, txn_num|
               apply_collation!(update_doc, server, opts)
               apply_array_filters!(update_doc, server, opts)
@@ -323,6 +358,17 @@ module Mongo
             raise Error::UnsupportedArrayFilters.new
           end
         end
+
+        # Get the write concern for an operation
+        #
+        # @return [ Mongo::WriteConcern ] The write concern.
+        def applied_write_concern(session)
+          if wco = options[:write_concern] || options[:write]
+            WriteConcern.get(wco)
+          else
+            write_concern_with_session(session)
+          end
+        end
       end
     end
   end

data/lib/mongo/cursor.rb

@@ -42,6 +42,12 @@ module Mongo
     # @return [ Collection::View ] view The collection view.
     attr_reader :view
 
+    # The resume token tracked by the cursor for change stream resuming
+    #
+    # @return [ BSON::Document | nil ] The cursor resume token.
+    # @api private
+    attr_reader :resume_token
+
     # Creates a +Cursor+ object.
     #
     # @example Instantiate the cursor.
@@ -125,20 +131,39 @@ module Mongo
     #
     # @since 2.0.0
     def each
-      process(@initial_result).each { |doc| yield doc }
-      while more?
-        return kill_cursors if exhausted?
-        get_more.each { |doc| yield doc }
+      # If we already iterated past the first batch (i.e., called get_more
+      # at least once), the cursor on the server side has advanced past
+      # the first batch and restarting iteration from the beginning by
+      # returning initial result would miss documents in the second batch
+      # and subsequent batches up to wherever the cursor is. Detect this
+      # condition and abort the iteration.
+      #
+      # In a future driver version, each would either continue from the
+      # end of previous iteration or would always restart from the
+      # beginning.
+      if @get_more_called
+        raise NotImplementedError, 'Cannot restart iteration of a cursor which issued a getMore'
       end
+
+      # To maintain compatibility with pre-2.10 driver versions, reset
+      # the documents array each time a new iteration is started.
+      @documents = nil
+
+      loop do
+        document = try_next
+        yield document if document
+      end
+    rescue StopIteration => e
+      return self
     end
 
     # Return one document from the query, if one is available.
     #
-    # Retries once on a resumable error.
-    #
     # This method will wait up to max_await_time_ms milliseconds
     # for changes from the server, and if no changes are received
-    # it will return nil.
+    # it will return nil. If there are no more documents to return
+    # from the server, or if we have exhausted the cursor, it will
+    # raise a StopIteration exception.
     #
     # @note This method is experimental and subject to change.
     #
@@ -146,30 +171,45 @@ module Mongo
     # @api private
     def try_next
       if @documents.nil?
-        @documents = process(@initial_result)
+        # Since published versions of Mongoid have a copy of old driver cursor
+        # code, our dup call in #process isn't invoked when Mongoid query
+        # cache is active. Work around that by also calling dup here on
+        # the result of #process which might come out of Mongoid's code.
+        @documents = process(@initial_result).dup
         # the documents here can be an empty array, hence
         # we may end up issuing a getMore in the first try_next call
       end
 
       if @documents.empty?
+        # On empty batches, we cache the batch resume token
+        cache_batch_resume_token
+
         if more?
           if exhausted?
             kill_cursors
-            return nil
+            raise StopIteration
           end
-
           @documents = get_more
+        else
+          raise StopIteration
         end
       else
         # cursor is closed here
         # keep documents as an empty array
       end
 
-      if @documents
-        return @documents.shift
+      # If there is at least one document, cache its _id
+      if @documents[0]
+        cache_resume_token(@documents[0])
       end
 
-      nil
+      # Cache the batch resume token if we are iterating
+      # over the last document, or if the batch is empty
+      if @documents.size <= 1
+        cache_batch_resume_token
+      end
+
+      return @documents.shift
     end
 
     # Get the batch size.
@@ -235,13 +275,15 @@ module Mongo
       use_limit? ? @remaining : (batch_size || 0)
     end
 
-    private
-
-    def exhausted?
-      limited? ? @remaining <= 0 : false
-    end
-
+    # Execute a getMore command and return the batch of documents
+    # obtained from the server.
+    #
+    # @return [ Array<BSON::Document> ] The batch of documents
+    #
+    # @api private
     def get_more
+      @get_more_called = true
+
       # Modern retryable reads specification prohibits retrying getMores.
       # Legacy retryable read logic used to retry getMores, but since
       # doing so may result in silent data loss, the driver no longer retries
@@ -250,6 +292,22 @@ module Mongo
       process(get_more_operation.execute(@server))
     end
 
+    private
+
+    def exhausted?
+      limited? ? @remaining <= 0 : false
+    end
+
+    def cache_resume_token(doc)
+      if doc[:_id] && doc[:_id].is_a?(Hash)
+        @resume_token = doc[:_id] && doc[:_id].dup.freeze
+      end
+    end
+
+    def cache_batch_resume_token
+      @resume_token = @post_batch_resume_token if @post_batch_resume_token
+    end
+
     def get_more_operation
       if @server.features.find_command_enabled?
         spec = Builder::GetMoreCommand.new(self, @session).specification
@@ -298,8 +356,17 @@ module Mongo
       @coll_name ||= result.namespace.sub("#{database.name}.", '') if result.namespace
       unregister if result.cursor_id == 0
       @cursor_id = result.cursor_id
+
+      if result.respond_to?(:post_batch_resume_token)
+        @post_batch_resume_token = result.post_batch_resume_token
+      end
+
       end_session if !more?
-      result.documents
+
+      # Since our iteration code mutates the documents array by calling #shift
+      # on it, duplicate the documents here to permit restarting iteration
+      # from the beginning of the cursor as long as get_more was not called
+      result.documents.dup
     end
 
     def use_limit?

data/lib/mongo/database.rb

@@ -42,6 +42,7 @@ module Mongo
     # Database name field constant.
     #
     # @since 2.1.0
+    # @deprecated
     NAME = 'name'.freeze
 
     # Databases constant.
@@ -109,34 +110,36 @@ module Mongo
 
     # Get all the names of the non-system collections in the database.
     #
-    # @example Get the collection names.
-    #   database.collection_names
+    # @note The set of returned collection names depends on the version of
+    #   MongoDB server that fulfills the request.
     #
-    # @return [ Array<String> ] The names of all non-system collections.
+    # @return [ Array<String> ] Names of the collections.
     #
     # @since 2.0.0
     def collection_names(options = {})
       View.new(self).collection_names(options)
     end
 
-    # Get info on all the collections in the database.
+    # Get info on all the non-system collections in the database.
     #
-    # @example Get info on each collection.
-    #   database.list_collections
+    # @note The set of collections returned, and the schema of the
+    #   information hash per collection, depends on the MongoDB server
+    #   version that fulfills the request.
     #
-    # @return [ Array<Hash> ] Info for each collection in the database.
+    # @return [ Array<Hash> ] Array of information hashes, one for each
+    #   collection in the database.
     #
     # @since 2.0.5
     def list_collections
       View.new(self).list_collections
     end
 
-    # Get all the collections that belong to this database.
+    # Get all the non-system collections that belong to this database.
     #
-    # @example Get all the collections.
-    #   database.collections
+    # @note The set of returned collections depends on the version of
+    #   MongoDB server that fulfills the request.
     #
-    # @return [ Array<Mongo::Collection> ] All the collections.
+    # @return [ Array<Mongo::Collection> ] The collections.
     #
     # @since 2.0.0
     def collections
@@ -156,37 +159,6 @@ module Mongo
     #
     # @return [ Hash ] The result of the command execution.
     def command(operation, opts = {})
-      txn_read_pref = if opts[:session] && opts[:session].in_transaction?
-        opts[:session].txn_read_preference
-      else
-        nil
-      end
-      txn_read_pref ||= opts[:read] || ServerSelector::PRIMARY
-      Lint.validate_underscore_read_preference(txn_read_pref)
-      selector = ServerSelector.get(txn_read_pref)
-
-      client.send(:with_session, opts) do |session|
-        server = selector.select_server(cluster)
-        Operation::Command.new({
-          :selector => operation.dup,
-          :db_name => name,
-          :read => selector,
-          :session => session
-        }).execute(server)
-      end
-    end
-
-    # Execute a read command on the database, retrying the read if necessary.
-    #
-    # @param [ Hash ] operation The command to execute.
-    # @param [ Hash ] opts The command options.
-    #
-    # @option opts :read [ Hash ] The read preference for this command.
-    # @option opts :session [ Session ] The session to use for this command.
-    #
-    # @return [ Hash ] The result of the command execution.
-    # @api private
-    def read_command(operation, opts = {})
       txn_read_pref = if opts[:session] && opts[:session].in_transaction?
         opts[:session].txn_read_preference
       else
@@ -228,7 +200,7 @@ module Mongo
           db_name: name,
           write_concern: write_concern,
           session: session
-        }).execute(next_primary)
+        }).execute(next_primary(nil, session))
       end
     end
 
@@ -287,6 +259,38 @@ module Mongo
       Auth::User::View.new(self)
     end
 
+    # Perform an aggregation on the database.
+    #
+    # @example Perform an aggregation.
+    #   collection.aggregate([ { "$listLocalSessions" => {} } ])
+    #
+    # @param [ Array<Hash> ] pipeline The aggregation pipeline.
+    # @param [ Hash ] options The aggregation options.
+    #
+    # @option options [ true, false ] :allow_disk_use Set to true if disk
+    #   usage is allowed during the aggregation.
+    # @option options [ Integer ] :batch_size The number of documents to return
+    #   per batch.
+    # @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 [ String ] :hint The index to use for the aggregation.
+    # @option options [ Integer ] :max_time_ms The maximum amount of time in
+    #   milliseconds to allow the aggregation to run.
+    # @option options [ true, false ] :use_cursor Indicates whether the command
+    #   will request that the server provide results using a cursor. Note that
+    #   as of server version 3.6, aggregations always provide results using a
+    #   cursor and this option is therefore not valid.
+    # @option options [ Session ] :session The session to use.
+    #
+    # @return [ Aggregation ] The aggregation object.
+    #
+    # @since 2.10.0
+    def aggregate(pipeline, options = {})
+      View.new(self).aggregate(pipeline, options)
+    end
+
     # As of version 3.6 of the MongoDB server, a ``$changeStream`` pipeline stage is supported
     # in the aggregation framework. As of version 4.0, this stage allows users to request that
     # notifications are sent for all changes that occur in the client's database.