mongo 2.17.4 → 2.21.0

data/lib/mongo/database/view.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #
@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/cursor/nontailable'
+
 module Mongo
   class Database
 
@@ -25,6 +27,8 @@ module Mongo
       extend Forwardable
       include Enumerable
       include Retryable
+      include Mongo::CursorHost
+      include Cursor::NonTailable
 
       def_delegators :@database, :cluster, :read_preference, :client
       # @api private
@@ -53,9 +57,15 @@ module Mongo
       # @option options [ Hash ] :filter A filter on the collections returned.
       # @option options [ true, false ] :authorized_collections A flag, when
       #   set to true, that allows a user without the required privilege
-      #   to run the command when access control is enforced
+      #   to run the command when access control is enforced.
+      # @option options [ Object ] :comment A user-provided
+      #   comment to attach to this command.
+      # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+      #    Must be a non-negative integer. An explicit value of 0 means infinite.
+      #    The default value is unset which means the value is inherited from
+      #    the database or the client.
       #
-      #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+      #   See https://mongodb.com/docs/manual/reference/command/listCollections/
       #   for more information and usage.
       # @option options [ Session ] :session The session to use.
       #
@@ -64,9 +74,14 @@ module Mongo
       # @since 2.0.0
       def collection_names(options = {})
         @batch_size = options[:batch_size]
-        session = client.send(:get_session, options)
-        cursor = read_with_retry_cursor(session, ServerSelector.primary, self) do |server|
-          send_initial_query(server, session, options.merge(name_only: true))
+        session = client.get_session(options)
+        context = Operation::Context.new(
+          client: client,
+          session: session,
+          operation_timeouts: operation_timeouts(options)
+        )
+        cursor = read_with_retry_cursor(session, ServerSelector.primary, self, context: context) do |server|
+          send_initial_query(server, session, context, options.merge(name_only: true))
         end
         cursor.map do |info|
           if cursor.initial_result.connection_description.features.list_collections_enabled?
@@ -99,28 +114,44 @@ module Mongo
       #   set to true and used with nameOnly: true, that allows a user without the
       #   required privilege to run the command when access control is enforced
       #
-      #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+      #   See https://mongodb.com/docs/manual/reference/command/listCollections/
       #   for more information and usage.
       # @option options [ Session ] :session The session to use.
+      # @option options [ Boolean ] :deserialize_as_bson Whether to deserialize
+      #   this message using BSON types instead of native Ruby types wherever
+      #   possible.
       #
       # @return [ Array<Hash> ] Info for each collection in the database.
       #
       # @since 2.0.5
       def list_collections(options = {})
-        session = client.send(:get_session, options)
+        session = client.get_session(options)
         collections_info(session, ServerSelector.primary, options)
       end
 
       # Create the new database view.
       #
       # @example Create the new database view.
-      #   View::Index.new(database)
+      #   Database::View.new(database)
       #
       # @param [ Database ] database The database.
+      # @param [ Hash ] options The options to configure the view with.
+      #
+      # @option options [ :cursor_lifetime | :iteration ] :timeout_mode How to interpret
+      #   :timeout_ms (whether it applies to the lifetime of the cursor, or per
+      #   iteration).
+      # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+      #    Must be a non-negative integer. An explicit value of 0 means infinite.
+      #    The default value is unset which means the value is inherited from
+      #    the database or the client.
       #
       # @since 2.0.0
-      def initialize(database)
+      def initialize(database, options = {})
         @database = database
+        @operation_timeout_ms = options.delete(:timeout_ms)
+
+        validate_timeout_mode!(options)
+
         @batch_size =  nil
         @limit = nil
         @collection = @database[Database::COMMAND]
@@ -129,6 +160,12 @@ module Mongo
       # @api private
       attr_reader :database
 
+      # @return [ Integer | nil | The timeout_ms value that was passed as an
+      #   option to the view.
+      #
+      # @api private
+      attr_reader :operation_timeout_ms
+
       # Execute an aggregation on the database view.
       #
       # @example Aggregate documents.
@@ -139,7 +176,7 @@ module Mongo
       # @param [ Array<Hash> ] pipeline The aggregation pipeline.
       # @param [ Hash ] options The aggregation options.
       #
-      # @return [ Aggregation ] The aggregation object.
+      # @return [ Collection::View::Aggregation ] The aggregation object.
       #
       # @since 2.10.0
       # @api private
@@ -147,15 +184,41 @@ module Mongo
         Collection::View::Aggregation.new(self, pipeline, options)
       end
 
+      # The timeout_ms value to use for this operation; either specified as an
+      # option to the view, or inherited from the database.
+      #
+      # @return [ Integer | nil ] the timeout_ms for this operation
+      def timeout_ms
+        operation_timeout_ms || database.timeout_ms
+      end
+
+      # @return [ Hash ] timeout_ms value set on the operation level (if any).
+      #
+      # @api private
+      def operation_timeouts(opts = {})
+        {}.tap do |result|
+          if opts[:timeout_ms] || operation_timeout_ms
+            result[:operation_timeout_ms] = opts.delete(:timeout_ms) || operation_timeout_ms
+          else
+            result[:inherited_timeout_ms] = database.timeout_ms
+          end
+        end
+      end
+
       private
 
       def collections_info(session, server_selector, options = {}, &block)
         description = nil
-        cursor = read_with_retry_cursor(session, server_selector, self) do |server|
+        context = Operation::Context.new(
+          client: client,
+          session: session,
+          operation_timeouts: operation_timeouts(options)
+        )
+        cursor = read_with_retry_cursor(session, server_selector, self, context: context) do |server|
           # TODO take description from the connection used to send the query
           # once https://jira.mongodb.org/browse/RUBY-1601 is fixed.
           description = server.description
-          send_initial_query(server, session, options)
+          send_initial_query(server, session, context, options)
         end
         # On 3.0+ servers, we get just the collection names.
         # On 2.6 server, we get collection names prefixed with the database
@@ -170,7 +233,7 @@ module Mongo
             doc['name'].start_with?('system.') || doc['name'].include?('$')
           end
         else
-          docs = cursor.reject do |doc|
+          cursor.reject do |doc|
             doc['name'].start_with?("#{database.name}.system") || doc['name'].include?('$')
           end
         end
@@ -186,6 +249,7 @@ module Mongo
           spec[:selector][:nameOnly] = true if options[:name_only]
           spec[:selector][:filter] = options[:filter] if options[:filter]
           spec[:selector][:authorizedCollections] = true if options[:authorized_collections]
+          spec[:comment] = options[:comment] if options[:comment]
         end
       end
 
@@ -193,8 +257,51 @@ module Mongo
         Operation::CollectionsInfo.new(collections_info_spec(session, options))
       end
 
-      def send_initial_query(server, session, options = {})
-        initial_query_op(session, options).execute(server, context: Operation::Context.new(client: client, session: session))
+      # Sends command that obtains information about the database.
+      #
+      # This command returns a cursor, so there could be additional commands,
+      # therefore this method is called send *initial* command.
+      #
+      # @param [ Server ] server Server to send the query to.
+      # @param [ Session ] session Session that should be used to send the query.
+      # @param [ Hash ] options
+      # @option options [ Hash | nil ] :filter A query expression to filter
+      #   the list of collections.
+      # @option options [ true | false | nil ] :name_only A flag to indicate
+      #   whether the command should return just the collection/view names
+      #   and type or return both the name and other information.
+      # @option options [ true | false | nil ] :authorized_collections A flag,
+      #   when set to true and used with name_only: true, that allows a user
+      #   without the required privilege (i.e. listCollections
+      #   action on the database) to run the command when access control
+      #   is enforced.
+      # @option options [ Object | nil ] :comment A user-provided comment to attach
+      #   to this command.
+      # @option options [ true | false | nil ] :deserialize_as_bson Whether the
+      #   query results should be deserialized to BSON types, or to Ruby
+      #   types (where possible).
+      #
+      # @return [ Operation::Result ] Result of the query.
+      def send_initial_query(server, session, context, options = {})
+        opts = options.dup
+        execution_opts = {}
+        if opts.key?(:deserialize_as_bson)
+          execution_opts[:deserialize_as_bson] = opts.delete(:deserialize_as_bson)
+        end
+        if server.load_balancer?
+          connection = server.pool.check_out(context: context)
+          initial_query_op(session, opts).execute_with_connection(
+            connection,
+            context: context,
+            options: execution_opts
+          )
+        else
+          initial_query_op(session, opts).execute(
+            server,
+            context: context,
+            options: execution_opts
+          )
+        end
       end
     end
   end

data/lib/mongo/database.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #
@@ -73,7 +73,8 @@ module Mongo
                    :read_preference,
                    :server_selector,
                    :read_concern,
-                   :write_concern
+                   :write_concern,
+                   :encrypted_fields_map
 
     # @return [ Mongo::Server ] Get the primary server from the cluster.
     def_delegators :cluster,
@@ -125,15 +126,21 @@ module Mongo
     # @option options [ true, false ] :authorized_collections A flag, when
     #   set to true and used with nameOnly: true, that allows a user without the
     #   required privilege to run the command when access control is enforced
-    #
-    #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
+    #
+    #   See https://mongodb.com/docs/manual/reference/command/listCollections/
     #   for more information and usage.
     #
     # @return [ Array<String> ] Names of the collections.
     #
     # @since 2.0.0
     def collection_names(options = {})
-      View.new(self).collection_names(options)
+      View.new(self, options).collection_names(options)
     end
 
     # Get info on all the non-system collections in the database.
@@ -150,9 +157,15 @@ module Mongo
     #   name and other information
     # @option options [ true, false ] :authorized_collections A flag, when
     #   set to true and used with nameOnly: true, that allows a user without the
-    #   required privilege to run the command when access control is enforced
-    #
-    #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+    #   required privilege to run the command when access control is enforced.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
+    #
+    #   See https://mongodb.com/docs/manual/reference/command/listCollections/
     #   for more information and usage.
     #
     # @return [ Array<Hash> ] Array of information hashes, one for each
@@ -160,7 +173,7 @@ module Mongo
     #
     # @since 2.0.5
     def list_collections(options = {})
-      View.new(self).list_collections(options)
+      View.new(self, options).list_collections(options)
     end
 
     # Get all the non-system collections that belong to this database.
@@ -173,9 +186,15 @@ module Mongo
     # @option options [ Hash ] :filter A filter on the collections returned.
     # @option options [ true, false ] :authorized_collections A flag, when
     #   set to true and used with name_only: true, that allows a user without the
-    #   required privilege to run the command when access control is enforced
-    #
-    #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+    #   required privilege to run the command when access control is enforced.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
+    #
+    #   See https://mongodb.com/docs/manual/reference/command/listCollections/
     #   for more information and usage.
     #
     # @return [ Array<Mongo::Collection> ] The collections.
@@ -195,6 +214,10 @@ module Mongo
     #
     # @option opts :read [ Hash ] The read preference for this command.
     # @option opts :session [ Session ] The session to use for this command.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
     # @option opts :execution_options [ Hash ] Options to pass to the code that
     #   executes this command. This is an internal option and is subject to
     #   change.
@@ -216,17 +239,21 @@ module Mongo
       Lint.validate_underscore_read_preference(txn_read_pref)
       selector = ServerSelector.get(txn_read_pref)
 
-      client.send(:with_session, opts) do |session|
+      client.with_session(opts) do |session|
         server = selector.select_server(cluster, nil, session)
         op = Operation::Command.new(
-          :selector => operation.dup,
+          :selector => operation,
           :db_name => name,
           :read => selector,
           :session => session
         )
 
         op.execute(server,
-          context: Operation::Context.new(client: client, session: session),
+          context: Operation::Context.new(
+            client: client,
+            session: session,
+            operation_timeouts: operation_timeouts(opts)
+          ),
           options: execution_opts)
       end
     end
@@ -238,6 +265,12 @@ module Mongo
     #
     # @option opts :read [ Hash ] The read preference for this command.
     # @option opts :session [ Session ] The session to use for this command.
+    # @option opts [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
     #
     # @return [ Hash ] The result of the command execution.
     # @api private
@@ -251,14 +284,20 @@ module Mongo
       Lint.validate_underscore_read_preference(txn_read_pref)
       preference = ServerSelector.get(txn_read_pref)
 
-      client.send(:with_session, opts) do |session|
-        read_with_retry(session, preference) do |server|
+      client.with_session(opts) do |session|
+        context = Operation::Context.new(
+          client: client,
+          session: session,
+          operation_timeouts: operation_timeouts(opts)
+        )
+        read_with_retry(session, preference, context) do |server|
           Operation::Command.new(
             selector: operation.dup,
             db_name: name,
             read: preference,
             session: session,
-          ).execute(server, context: Operation::Context.new(client: client, session: session))
+            comment: opts[:comment],
+          ).execute(server, context: context)
         end
       end
     end
@@ -271,14 +310,18 @@ module Mongo
     # @param [ Hash ] options The options for the operation.
     #
     # @option options [ Session ] :session The session to use for the operation.
-    # @option opts [ Hash ] :write_concern The write concern options.
+    # @option options [ Hash ] :write_concern The write concern options.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
     #
     # @return [ Result ] The result of the command.
     #
     # @since 2.0.0
     def drop(options = {})
       operation = { :dropDatabase => 1 }
-      client.send(:with_session, options) do |session|
+      client.with_session(options) do |session|
         write_concern = if options[:write_concern]
           WriteConcern.get(options[:write_concern])
         else
@@ -289,7 +332,14 @@ module Mongo
           db_name: name,
           write_concern: write_concern,
           session: session
-        }).execute(next_primary(nil, session), context: Operation::Context.new(client: client, session: session))
+        }).execute(
+          next_primary(nil, session),
+          context: Operation::Context.new(
+            client: client,
+            session: session,
+            operation_timeouts: operation_timeouts(options)
+          )
+        )
       end
     end
 
@@ -301,6 +351,10 @@ module Mongo
     # @param [ Mongo::Client ] client The driver client.
     # @param [ String, Symbol ] name The name of the database.
     # @param [ Hash ] options The options.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the client.
     #
     # @raise [ Mongo::Database::InvalidName ] If the name is nil.
     #
@@ -378,21 +432,23 @@ 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 [ Integer ] :max_time_ms The maximum amount of time to
+    #   allow the query to run, in milliseconds. This option is deprecated, use
+    #   :timeout_ms instead.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the database or the client.
     # @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.
+    # @return [ Collection::View::Aggregation ] The aggregation object.
     #
     # @since 2.10.0
     def aggregate(pipeline, options = {})
-      View.new(self).aggregate(pipeline, options)
+      View.new(self, options).aggregate(pipeline, options)
     end
 
     # As of version 3.6 of the MongoDB server, a ``$changeStream`` pipeline stage is supported
@@ -405,10 +461,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 for the server to
@@ -420,6 +501,13 @@ module Mongo
     #   changes that occurred 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 a $changeStream
@@ -429,8 +517,11 @@ module Mongo
     #
     # @since 2.6.0
     def watch(pipeline = [], options = {})
+      view_options = options.dup
+      view_options[:cursor_type] = :tailable_await if options[:max_await_time_ms]
+
       Mongo::Collection::View::ChangeStream.new(
-        Mongo::Collection::View.new(collection("#{COMMAND}.aggregate")),
+        Mongo::Collection::View.new(collection("#{COMMAND}.aggregate"), {}, view_options),
         pipeline,
         Mongo::Collection::View::ChangeStream::DATABASE,
         options)
@@ -453,5 +544,28 @@ module Mongo
       database = Database.new(client, client.options[:database], client.options)
       client.instance_variable_set(:@database, database)
     end
+
+    # @return [ Integer | nil ] Operation timeout that is for this database or
+    #   for the corresponding client.
+    #
+    # @api private
+    def timeout_ms
+      options[:timeout_ms] || client.timeout_ms
+    end
+
+    # @return [ Hash ] timeout_ms value set on the operation level (if any),
+    #   and/or timeout_ms that is set on collection/database/client level (if any).
+    #
+    # @api private
+    def operation_timeouts(opts)
+      # TODO: We should re-evaluate if we need two timeouts separately.
+      {}.tap do |result|
+        if opts[:timeout_ms].nil?
+          result[:inherited_timeout_ms] = timeout_ms
+        else
+          result[:operation_timeout_ms] = opts.delete(:timeout_ms)
+        end
+      end
+    end
   end
 end