mongo 2.13.3 → 2.14.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41f37eb33cbd1ebf2c916187b4610eefd895885042eeb3949882ce0a8c4ed069
-  data.tar.gz: db734108633f8b5988eaa15de33165182233ba5064f0b805298747256fb578b1
+  metadata.gz: 493d0cb29d48d80c7fe4c87691500c078b6667bd214dcc021e0074938229be83
+  data.tar.gz: 44507b68e42abadad6987f50c3b3ae1b8ae70f046812607755ffbe292013ccc4
 SHA512:
-  metadata.gz: 27c0c7ca84b6b7983767eb652f6aa5968362d8b42a4adf3eab3ee4a11fe4e74d36096b636436ac5075b31207470a67a8c5ecb00eac7f27a3889966ee30d84db9
-  data.tar.gz: 86c9fb09b3fb9c9512db2e7caed2f21ac2d53ee75f671d1cbcc92b89afa0d471cc1217552c3971ee9641f90b4c710692ab885c454f8701371726623e16114604
+  metadata.gz: ea39c71265e24349b018a8e5f5699b556d1ed43107135da46790ad8496c4bcd8a3917ca6fd0c7b405c5e6cff968d6e18cedf35ac33fe660f19f2869f663cdf64
+  data.tar.gz: 30ca549b30bec1889f622f7002658c918b6686e417bd9a636777bbc7f321d06094278b5a7ff4b04a9395f61bf90e28f99f26ff9ec404b0e3687dbc1b4a77ec1f

data/lib/mongo/address/ipv4.rb

@@ -81,7 +81,7 @@ module Mongo
       # @param [ Hash ] options The options.
       #
       # @option options [ Float ] :connect_timeout Connect timeout.
-      # @option options [ true | false ] :ssl Whether to use SSL.
+      # @option options [ true | false ] :ssl Whether to use TLS.
       # @option options [ String ] :ssl_ca_cert
       #   Same as the corresponding Client/Socket::SSL option.
       # @option options [ Array<OpenSSL::X509::Certificate> ] :ssl_ca_cert_object

data/lib/mongo/address/ipv6.rb

@@ -95,7 +95,7 @@ module Mongo
       # @param [ Hash ] options The options.
       #
       # @option options [ Float ] :connect_timeout Connect timeout.
-      # @option options [ true | false ] :ssl Whether to use SSL.
+      # @option options [ true | false ] :ssl Whether to use TLS.
       # @option options [ String ] :ssl_ca_cert
       #   Same as the corresponding Client/Socket::SSL option.
       # @option options [ Array<OpenSSL::X509::Certificate> ] :ssl_ca_cert_object

data/lib/mongo/address.rb

@@ -286,7 +286,7 @@ module Mongo
       rescue IOError, SystemCallError => e
         raise Error::SocketError, "#{e.class}: #{e} (for #{self})"
       rescue OpenSSL::SSL::SSLError => e
-        raise Error::SocketError, "#{e.class}: #{e} (for #{self})"
+        raise Error::SocketError, "#{e.class}: #{e} (for #{self}) (#{SSL_ERROR})"
       end
     end
   end

data/lib/mongo/bulk_write.rb

@@ -195,6 +195,13 @@ module Mongo
           end
         end
       end
+    # With OP_MSG (3.6+ servers), the size of each section in the message
+    # is independently capped at 16m and each bulk operation becomes
+    # its own section. The size of the entire bulk write is limited to 48m.
+    # With OP_QUERY (pre-3.6 servers), the entire bulk write is sent as a
+    # single document and is thus subject to the 16m document size limit.
+    # This means the splits differ between pre-3.6 and 3.6+ servers, with
+    # 3.6+ servers being able to split less.
     rescue Error::MaxBSONSize, Error::MaxMessageSize => e
       raise e if values.size <= 1
       unpin_maybe(session) do
@@ -214,27 +221,37 @@ module Mongo
     end
 
     def delete_one(documents, connection, operation_id, session, txn_num)
+      QueryCache.clear_namespace(collection.namespace)
+
       spec = base_spec(operation_id, session).merge(:deletes => documents, :txn_num => txn_num)
       Operation::Delete.new(spec).bulk_execute(connection, client: client)
     end
 
     def delete_many(documents, connection, operation_id, session, txn_num)
+      QueryCache.clear_namespace(collection.namespace)
+
       spec = base_spec(operation_id, session).merge(:deletes => documents)
       Operation::Delete.new(spec).bulk_execute(connection, client: client)
     end
 
     def insert_one(documents, connection, operation_id, session, txn_num)
+      QueryCache.clear_namespace(collection.namespace)
+
       spec = base_spec(operation_id, session).merge(:documents => documents, :txn_num => txn_num)
       Operation::Insert.new(spec).bulk_execute(connection, client: client)
     end
 
     def update_one(documents, connection, operation_id, session, txn_num)
+      QueryCache.clear_namespace(collection.namespace)
+
       spec = base_spec(operation_id, session).merge(:updates => documents, :txn_num => txn_num)
       Operation::Update.new(spec).bulk_execute(connection, client: client)
     end
     alias :replace_one :update_one
 
     def update_many(documents, connection, operation_id, session, txn_num)
+      QueryCache.clear_namespace(collection.namespace)
+
       spec = base_spec(operation_id, session).merge(:updates => documents)
       Operation::Update.new(spec).bulk_execute(connection, client: client)
     end

data/lib/mongo/caching_cursor.rb

@@ -0,0 +1,74 @@
+# Copyright (C) 2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+
+  # A Cursor that attempts to load documents from memory first before hitting
+  # the database if the same query has already been executed.
+  #
+  # @api semiprivate
+  class CachingCursor < Cursor
+
+    # @return [ Array <BSON::Document> ] The cursor's cached documents.
+    # @api private
+    attr_reader :cached_docs
+
+    # We iterate over the cached documents if they exist already in the
+    # cursor otherwise proceed as normal.
+    #
+    # @example Iterate over the documents.
+    #   cursor.each do |doc|
+    #     # ...
+    #   end
+    def each
+      if @cached_docs
+        @cached_docs.each do |doc|
+          yield doc
+        end
+
+        unless closed?
+          # StopIteration raised by try_next ends this loop.
+          loop do
+            document = try_next
+            yield document if document
+          end
+        end
+      else
+        super
+      end
+    end
+
+    # Get a human-readable string representation of +Cursor+.
+    #
+    # @example Inspect the cursor.
+    #   cursor.inspect
+    #
+    # @return [ String ] A string representation of a +Cursor+ instance.
+    def inspect
+      "#<Mongo::CachingCursor:0x#{object_id} @view=#{@view.inspect}>"
+    end
+
+    # Acquires the next document for cursor iteration and then
+    # inserts that document in the @cached_docs array.
+    #
+    # @api private
+    def try_next
+      @cached_docs ||= []
+      document = super
+      @cached_docs << document if document
+
+      document
+    end
+  end
+end

data/lib/mongo/client.rb

@@ -101,6 +101,7 @@ module Mongo
       :ssl_verify,
       :ssl_verify_certificate,
       :ssl_verify_hostname,
+      :ssl_verify_ocsp_endpoint,
       :truncate_logs,
       :user,
       :wait_queue_timeout,
@@ -315,7 +316,7 @@ module Mongo
     #   for selecting a server for an operation.
     # @option options [ Float ] :socket_timeout The timeout, in seconds, to
     #   execute operations on a socket.
-    # @option options [ true, false ] :ssl Whether to use SSL.
+    # @option options [ true, false ] :ssl Whether to use TLS.
     # @option options [ String ] :ssl_ca_cert The file containing concatenated
     #   certificate authority certificates used to validate certs passed from the
     #   other end of the connection. Intermediate certificates should NOT be
@@ -462,6 +463,8 @@ module Mongo
         @srv_records = nil
       end
 
+      options = self.class.canonicalize_ruby_options(options)
+
       # Special handling for sdam_proc as it is only used during client
       # construction
       sdam_proc = options.delete(:sdam_proc)
@@ -478,6 +481,12 @@ module Mongo
       end
       options = merged_options
 
+      options.keys.each do |k|
+        if options[k].nil?
+          options.delete(k)
+        end
+      end
+
       @options = validate_new_options!(options)
 =begin WriteConcern object support
       if @options[:write_concern].is_a?(WriteConcern::Base)
@@ -605,15 +614,12 @@ module Mongo
 
     # Get a summary of the client state.
     #
-    # @note This method is experimental and subject to change.
+    # @note The exact format and layout of the returned summary string is
+    #   not part of the driver's public API and may be changed at any time.
     #
-    # @example Inspect the client.
-    #   client.summary
-    #
-    # @return [ String ] Summary string.
+    # @return [ String ] The summary string.
     #
     # @since 2.7.0
-    # @api experimental
     def summary
       "#<Client cluster=#{cluster.summary}>"
     end
@@ -769,7 +775,6 @@ module Mongo
       options[:read_concern]
     end
 
-
     # Get the write concern for this client. If no option was provided, then a
     # default single server acknowledgement will be used.
     #
@@ -1022,6 +1027,23 @@ module Mongo
       end
     end
 
+    class << self
+      # Lowercases auth mechanism properties, if given, in the specified
+      # options, then converts the options to an instance of Options::Redacted.
+      #
+      # @api private
+      def canonicalize_ruby_options(options)
+        Options::Redacted.new(Hash[options.map do |k, v|
+          if k == :auth_mech_properties || k == 'auth_mech_properties'
+            if v
+              v = Hash[v.map { |pk, pv| [pk.downcase, pv] }]
+            end
+          end
+          [k, v]
+        end])
+      end
+    end
+
     private
 
     # Create a new encrypter object using the client's auto encryption options
@@ -1107,6 +1129,23 @@ module Mongo
     # but does not check for interactions between combinations of options.
     def validate_new_options!(opts = Options::Redacted.new)
       return Options::Redacted.new unless opts
+      if opts[:read_concern]
+        # Raise an error for non user-settable options
+        if opts[:read_concern][:after_cluster_time]
+          raise Mongo::Error::InvalidReadConcern.new(
+            'The after_cluster_time read_concern option cannot be specified by the user'
+          )
+        end
+
+        given_keys = opts[:read_concern].keys.map(&:to_s)
+        allowed_keys = ['level']
+        invalid_keys = given_keys - allowed_keys
+        # Warn that options are invalid but keep it and forward to the server
+        unless invalid_keys.empty?
+          log_warn("Read concern has invalid keys: #{invalid_keys.join(',')}.")
+        end
+      end
+
       Lint.validate_underscore_read_preference(opts[:read])
       Lint.validate_read_concern_option(opts[:read_concern])
       opts.each.inject(Options::Redacted.new) do |_options, (k, v)|

data/lib/mongo/cluster/topology/single.rb

@@ -133,7 +133,7 @@ module Mongo
 
         def validate_options(options, cluster)
           if cluster.servers_list.length > 1
-            raise ArgumentError, 'Cannot instantiate a single topology with more than one server in the cluster'
+            raise ArgumentError, "Cannot instantiate a single topology with more than one server in the cluster: #{cluster.servers_list.map(&:address).map(&:seed).join(', ')}"
           end
 
           super(options, cluster)

data/lib/mongo/cluster.rb

@@ -950,9 +950,9 @@ module Mongo
         # Start SRV monitor
         @srv_monitor_lock.synchronize do
           unless @srv_monitor
-            monitor_options = options.merge(
-              timeout: options[:connect_timeout] || Server::CONNECT_TIMEOUT)
-            @srv_monitor = _srv_monitor = Srv::Monitor.new(self, monitor_options)
+            monitor_options = Utils.shallow_symbolize_keys(options.merge(
+              timeout: options[:connect_timeout] || Server::CONNECT_TIMEOUT))
+            @srv_monitor = _srv_monitor = Srv::Monitor.new(self, **monitor_options)
             finalizer = lambda do
               _srv_monitor.stop!
             end

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

@@ -89,6 +89,16 @@ module Mongo
           self.class.new(view, pipeline, options.merge(explain: true)).first
         end
 
+        # Whether this aggregation will write its result to a database collection.
+        #
+        # @return [ Boolean ] Whether the aggregation will write its result
+        #   to a collection.
+        #
+        # @api private
+        def write?
+          pipeline.any? { |op| op.key?('$out') || op.key?(:$out) || op.key?('$merge') || op.key?(:$merge) }
+        end
+
         private
 
         def server_selector
@@ -114,10 +124,6 @@ module Mongo
           description.standalone? || description.mongos? || description.primary? || secondary_ok?
         end
 
-        def write?
-          pipeline.any? { |op| op.key?('$out') || op.key?(:$out) || op.key?('$merge') || op.key?(:$merge) }
-        end
-
         def secondary_ok?
           !write?
         end
@@ -136,6 +142,21 @@ module Mongo
             raise Error::UnsupportedCollation.new
           end
         end
+
+        # Skip, sort, limit, projection are specified as pipeline stages
+        # rather than as options.
+        def cache_options
+          {
+            namespace: collection.namespace,
+            selector: pipeline,
+            read_concern: view.read_concern,
+            read_preference: view.read_preference,
+            collation: options[:collation],
+            # Aggregations can read documents from more than one collection,
+            # so they will be cleared on every write operation.
+            multi_collection: true,
+          }
+        end
       end
     end
   end

data/lib/mongo/collection/view/builder/find_command.rb

@@ -52,21 +52,6 @@ module Mongo
             collation: 'collation'
           ).freeze
 
-          def_delegators :@view, :collection, :database, :filter, :options, :read
-
-          # Get the specification for an explain command that wraps the find
-          # command.
-          #
-          # @example Get the explain spec.
-          #   builder.explain_specification
-          #
-          # @return [ Hash ] The specification.
-          #
-          # @since 2.2.0
-          def explain_specification
-            { selector: { explain: find_command }, db_name: database.name, read: read, session: @session }
-          end
-
           # Create the find command builder.
           #
           # @example Create the find command builder.
@@ -81,6 +66,8 @@ module Mongo
             @session = session
           end
 
+          def_delegators :@view, :collection, :database, :filter, :options, :read
+
           # Get the specification to pass to the find command operation.
           #
           # @example Get the specification.
@@ -90,18 +77,51 @@ module Mongo
           #
           # @since 2.2.0
           def specification
-            { selector: find_command, db_name: database.name, read: read, session: @session }
+            {
+              selector: find_command,
+              db_name: database.name,
+              read: read,
+              session: @session,
+            }
+          end
+
+          # Get the specification for an explain command that wraps the find
+          # command.
+          #
+          # @example Get the explain spec.
+          #   builder.explain_specification
+          #
+          # @return [ Hash ] The specification.
+          #
+          # @since 2.2.0
+          def explain_specification
+            {
+              selector: {
+                explain: find_command,
+              },
+              db_name: database.name,
+              read: read,
+              session: @session,
+              # We should always have options{:explain] set if we are explaining.
+              # The explain field is not sent to the server, it will be
+              # processed in the operation layer.
+              explain: options[:explain],
+            }
           end
 
           private
 
           def find_command
-            document = BSON::Document.new('find' => collection.name, 'filter' => filter)
+            document = BSON::Document.new(
+              find: collection.name,
+              filter: filter,
+            )
             if collection.read_concern
               document[:readConcern] = Options::Mapper.transform_values_to_strings(
                 collection.read_concern)
             end
-            command = Options::Mapper.transform_documents(convert_flags(options), MAPPINGS, document)
+            command = Options::Mapper.transform_documents(
+              convert_flags(options), MAPPINGS, document)
             if command['oplogReplay']
               log_warn("oplogReplay is deprecated and ignored by MongoDB 4.4 and later")
             end

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

@@ -36,16 +36,25 @@ module Mongo
         # @since 2.2.0
         ALL_PLANS_EXECUTION = 'allPlansExecution'.freeze
 
-        # Get the explain plan for the query.
+        # Get the query plan for the query.
         #
-        # @example Get the explain plan for the query.
-        #   view.explain
+        # @example Get the query plan for the query with execution statistics.
+        #   view.explain(verbosity: :execution_stats)
         #
-        # @return [ Hash ] A single document with the explain plan.
+        # @option opts [ true | false ] :verbose The level of detail
+        #   to return for MongoDB 2.6 servers.
+        # @option opts [ String | Symbol ] :verbosity The type of information
+        #   to return for MongoDB 3.0 and newer servers. If the value is a
+        #   symbol, it will be stringified and converted from underscore
+        #   style to camel case style (e.g. :query_planner => "queryPlanner").
+        #
+        # @return [ Hash ] A single document with the query plan.
+        #
+        # @see https://docs.mongodb.com/manual/reference/method/db.collection.explain/#db.collection.explain
         #
         # @since 2.0.0
-        def explain
-          self.class.new(collection, selector, options.merge(explain_options)).first
+        def explain(**opts)
+          self.class.new(collection, selector, options.merge(explain_options(**opts))).first
         end
 
         private
@@ -54,9 +63,19 @@ module Mongo
           !!options[:explain]
         end
 
-        def explain_options
+        # @option opts [ true | false ] :verbose The level of detail
+        #   to return for MongoDB 2.6 servers.
+        # @option opts [ String | Symbol ] :verbosity The type of information
+        #   to return for MongoDB 3.0 and newer servers. If the value is a
+        #   symbol, it will be stringified and converted from underscore
+        #   style to camel case style (e.g. :query_planner => "queryPlanner").
+        def explain_options(**opts)
           explain_limit = limit || 0
-          { :limit => -explain_limit.abs, :explain => true }
+          # Note: opts will never be nil here.
+          if Symbol === opts[:verbosity]
+            opts[:verbosity] = Utils.camelize(opts[:verbosity])
+          end
+          { limit: -explain_limit.abs, explain: opts }
         end
       end
     end

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

@@ -35,19 +35,34 @@ module Mongo
         #
         # @yieldparam [ Hash ] Each matching document.
         def each
-          @cursor = nil
-          session = client.send(:get_session, @options)
-          @cursor = if respond_to?(:write?, true) && write?
-            server = server_selector.select_server(cluster, nil, session)
-            result = send_initial_query(server, session)
-            Cursor.new(view, result, server, session: session)
+          @cursor = if use_query_cache? && cached_cursor
+            cached_cursor
           else
-            read_with_retry_cursor(session, server_selector, view) do |server|
-              send_initial_query(server, session)
-            end
+            session = client.send(:get_session, @options)
+            select_cursor(session)
+          end
+
+          if use_query_cache?
+            # No need to store the cursor in the query cache if there is
+            # already a cached cursor stored at this key.
+            QueryCache.set(@cursor, **cache_options) unless cached_cursor
+
+            # If a query with a limit is performed, the query cache will
+            # re-use results from an earlier query with the same or larger
+            # limit, and then impose the lower limit during iteration.
+            limit_for_cached_query = respond_to?(:limit) ? limit : nil
           end
+
           if block_given?
-            @cursor.each do |doc|
+            # Ruby versions 2.5 and older do not support arr[0..nil] syntax, so
+            # this must be a separate conditional.
+            cursor_to_iterate = if limit_for_cached_query
+              @cursor.to_a[0...limit_for_cached_query]
+            else
+              @cursor
+            end
+
+            cursor_to_iterate.each do |doc|
               yield doc
             end
           else
@@ -77,6 +92,46 @@ module Mongo
 
         private
 
+        def select_cursor(session)
+          if respond_to?(:write?, true) && write?
+            server = server_selector.select_server(cluster, nil, session)
+            result = send_initial_query(server, session)
+
+            # RUBY-2367: This will be updated to allow the query cache to
+            # cache cursors with multi-batch results.
+            if use_query_cache?
+              CachingCursor.new(view, result, server, session: session)
+            else
+              Cursor.new(view, result, server, session: session)
+            end
+          else
+            read_with_retry_cursor(session, server_selector, view) do |server|
+              send_initial_query(server, session)
+            end
+          end
+        end
+
+        def cached_cursor
+          QueryCache.get(**cache_options)
+        end
+
+        def cache_options
+          # NB: this hash is passed as keyword argument and must have symbol
+          # keys.
+          {
+            namespace: collection.namespace,
+            selector: selector,
+            skip: skip,
+            sort: sort,
+            limit: limit,
+            projection: projection,
+            collation: collation,
+            read_concern: read_concern,
+            read_preference: read_preference
+
+          }
+        end
+
         def initial_query_op(server, session)
           if server.with_connection { |connection| connection.features }.find_command_enabled?
             initial_command_op(session)
@@ -92,10 +147,11 @@ module Mongo
         end
 
         def initial_command_op(session)
+          builder = Builder::FindCommand.new(self, session)
           if explained?
-            Operation::Explain.new(Builder::FindCommand.new(self, session).explain_specification)
+            Operation::Explain.new(builder.explain_specification)
           else
-            Operation::Find.new(Builder::FindCommand.new(self, session).specification)
+            Operation::Find.new(builder.specification)
           end
         end
 
@@ -103,6 +159,10 @@ module Mongo
           validate_collation!(server, collation)
           initial_query_op(server, session).execute(server, client: client)
         end
+
+        def use_query_cache?
+          QueryCache.enabled? && !collection.system_collection?
+        end
       end
     end
   end

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

@@ -45,7 +45,17 @@ module Mongo
         #
         # @since 2.0.0
         def aggregate(pipeline, options = {})
-          Aggregation.new(self, pipeline, options)
+          aggregation = Aggregation.new(self, pipeline, options)
+
+          # Because the $merge and $out pipeline stages write documents to the
+          # collection, it is necessary to clear the cache when they are performed.
+          #
+          # Opt to clear the entire cache rather than one namespace because
+          # the $out and $merge stages do not have to write to the same namespace
+          # on which the aggregation is performed.
+          QueryCache.clear if aggregation.write?
+
+          aggregation
         end
 
         # Allows the server to write temporary data to disk while executing
@@ -90,7 +100,7 @@ module Mongo
         # @param [ Integer ] batch_size The size of each batch of results.
         #
         # @return [ Integer, View ] Either the batch_size value or a
-        # new +View+.
+        #   new +View+.
         #
         # @since 2.0.0
         def batch_size(batch_size = nil)