mongo 2.13.3 → 2.14.0.rc1

data/lib/mongo/operation/shared/causal_consistency_supported.rb

@@ -18,6 +18,7 @@ module Mongo
     # Custom behavior for operations that support causal consistency.
     #
     # @since 2.5.2
+    # @api private
     module CausalConsistencySupported
 
       private

data/lib/mongo/operation/shared/collections_info_or_list_collections.rb

@@ -14,6 +14,8 @@
 
 module Mongo
   module Operation
+
+    # @api private
     module CollectionsInfoOrListCollections
       include PolymorphicLookup
 

data/lib/mongo/operation/shared/executable.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared executable behavior of operations.
     #
     # @since 2.5.2
+    # @api private
     module Executable
 
       include ResponseHandling

data/lib/mongo/operation/shared/idable.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared behavior of operations that require its documents to each have an id.
     #
     # @since 2.5.2
+    # @api private
     module Idable
 
       def documents
@@ -61,4 +62,4 @@ module Mongo
       end
     end
   end
-end
+end

data/lib/mongo/operation/shared/limited.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared behavior of operations that require its documents to each have an id.
     #
     # @since 2.5.2
+    # @api private
     module Limited
 
       private

data/lib/mongo/operation/shared/object_id_generator.rb

@@ -18,6 +18,7 @@ module Mongo
     # The default generator of ids for documents.
     #
     # @since 2.2.0
+    # @api private
     class ObjectIdGenerator
 
       # Generate a new id.

data/lib/mongo/operation/shared/read_preference_supported.rb

@@ -36,44 +36,47 @@ module Mongo
       #
       # @since 2.0.0
       def options(connection)
-        options = super
-        if add_slave_ok_flag?(connection)
-          flags = options[:flags]&.dup || []
-          flags << :slave_ok
-          options = options.merge(flags: flags)
-        end
-        options
+        add_slave_ok_flag_maybe(super, connection)
       end
 
-      # Whether to add the :slave_ok flag to the request based on the
-      # read preference specified in the operation or implied by the topology
-      # that the connection's server is a part of.
+      # Adds :slave_ok flag to options based on the read preference specified
+      # in the operation or implied by the topology that the connection's
+      # server is a part of.
       #
+      # @param [ Hash ] options The options calculated so far.
       # @param [ Server::Connection ] connection The connection that the
       #   operation will be executed on.
       #
-      # @return [ true | false ] Whether the :slave_ok flag should be added.
-      def add_slave_ok_flag?(connection)
-        # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#topology-type-single
-        if connection.description.standalone?
-          # Read preference is never sent to standalones.
-          false
-        elsif connection.server.cluster.single?
-          # In Single topology the driver forces primaryPreferred read
-          # preference mode (via the slave_ok flag, in case of old servers)
-          # so that the query is satisfied.
-          true
-        else
-          # In replica sets and sharded clusters, read preference is passed
-          # to the server if one is specified by the application, and there
-          # is no default.
-          read && read.slave_ok? || false
+      # @return [ Hash ] The new options.
+      def add_slave_ok_flag_maybe(options, connection)
+        add_flag =
+          # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#topology-type-single
+          if connection.description.standalone?
+            # Read preference is never sent to standalones.
+            false
+          elsif connection.server.cluster.single?
+            # In Single topology the driver forces primaryPreferred read
+            # preference mode (via the slave_ok flag, in case of old servers)
+            # so that the query is satisfied.
+            true
+          else
+            # In replica sets and sharded clusters, read preference is passed
+            # to the server if one is specified by the application, and there
+            # is no default.
+            read && read.slave_ok?
+          end
+
+        if add_flag
+          options= options.dup
+          (options[:flags] ||= []) << :slave_ok
         end
+
+        options
       end
 
       def command(connection)
         sel = super
-        add_read_preference_legacy(sel, connection)
+        update_selector_for_read_pref(sel, connection)
       end
 
       # Adds $readPreference field to the command document.
@@ -92,19 +95,14 @@ module Mongo
       #   operation will be executed on.
       #
       # @return [ Hash ] New command document to send to the server.
-      def add_read_preference_legacy(sel, connection)
+      def update_selector_for_read_pref(sel, connection)
         if read && connection.description.mongos? && read_pref = read.to_mongos
-          # If the read preference contains only mode and mode is secondary
-          # preferred and we are sending to a pre-OP_MSG server, this read
-          # preference is indicated by the :slave_ok wire protocol flag
-          # and $readPreference command parameter isn't sent.
-          if read_pref != {mode: 'secondaryPreferred'}
-            Mongo::Lint.validate_camel_case_read_preference(read_pref)
-            sel = sel[:$query] ? sel : {:$query => sel}
-            sel = sel.merge(:$readPreference => read_pref)
-          end
+          Mongo::Lint.validate_camel_case_read_preference(read_pref)
+          sel = sel[:$query] ? sel : {:$query => sel}
+          sel = sel.merge(:$readPreference => read_pref)
+        else
+          sel
         end
-        sel
       end
     end
   end

data/lib/mongo/operation/shared/result/aggregatable.rb

@@ -19,6 +19,7 @@ module Mongo
       # Defines custom behavior of bulk write results
       #
       # @since 2.0.0
+      # @api private
       module Aggregatable
 
         # Aggregate the write errors returned from this result.

data/lib/mongo/operation/shared/sessions_supported.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared behavior of operations that support a session.
     #
     # @since 2.5.2
+    # @api private
     module SessionsSupported
 
       private
@@ -170,10 +171,9 @@ module Mongo
         elsif connection.description.mongos?
           # When server is a mongos:
           # - $readPreference is never sent when mode is 'primary'
+          # - When mode is 'secondaryPreferred' $readPreference is only sent
+          #   when a non-mode field (i.e. tag_sets) is present
           # - Otherwise $readPreference is sent
-          # When mode is 'secondaryPreferred' $readPreference is currently
-          # required to only be sent when a non-mode field (i.e. tag_sets)
-          # is present, but this causes wrong behavior (DRIVERS-1642).
           if read
             doc = read.to_mongos
             if doc

data/lib/mongo/operation/shared/specifiable.rb

@@ -19,6 +19,7 @@ module Mongo
     # various values from the spec.
     #
     # @since 2.0.0
+    # @api private
     module Specifiable
 
       # The field for database name.

data/lib/mongo/operation/shared/write.rb

@@ -18,6 +18,7 @@ module Mongo
     # Shared behavior of operations that write (update, insert, delete).
     #
     # @since 2.5.2
+    # @api private
     module Write
 
       include ResponseHandling

data/lib/mongo/operation/shared/write_concern_supported.rb

@@ -18,6 +18,7 @@ module Mongo
     # Custom behavior for operations that support write concern.
     #
     # @since 2.5.2
+    # @api private
     module WriteConcernSupported
 
       private

data/lib/mongo/operation/update/legacy/result.rb

@@ -21,17 +21,20 @@ module Mongo
         # version <= 2.4.
         #
         # @since 2.0.0
+        # @api semiprivate
         class Result < Operation::Result
           include Operation::Result::UseLegacyErrorParser
 
           # Whether an existing document was updated.
           #
           # @since 2.0.0
+          # @api private
           UPDATED_EXISTING = 'updatedExisting'.freeze
 
           # The upserted docs field in the result.
           #
           # @since 2.0.0
+          # @api private
           UPSERTED = 'upserted'.freeze
 
           # Get the number of documents matched.
@@ -42,6 +45,7 @@ module Mongo
           # @return [ Integer ] The matched count.
           #
           # @since 2.0.0
+          # @api public
           def matched_count
             return 0 unless acknowledged?
             if upsert?
@@ -59,6 +63,7 @@ module Mongo
           # @return [ nil ] Always omitted for legacy versions.
           #
           # @since 2.0.0
+          # @api public
           def modified_count; end
 
           # The identifier of the inserted document if an upsert
@@ -70,6 +75,7 @@ module Mongo
           # @return [ Object ] The upserted id.
           #
           # @since 2.0.0
+          # @api public
           def upserted_id
             first[UPSERTED] if upsert?
           end
@@ -82,6 +88,7 @@ module Mongo
           # @return [ Integer ] The number upserted.
           #
           # @since 2.4.2
+          # @api public
           def upserted_count
             upsert? ? n : 0
           end

data/lib/mongo/operation/update/result.rb

@@ -19,16 +19,19 @@ module Mongo
       # Defines custom behavior of results for an update.
       #
       # @since 2.0.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # The number of modified docs field in the result.
         #
         # @since 2.0.0
+        # @api private
         MODIFIED = 'nModified'.freeze
 
         # The upserted docs field in the result.
         #
         # @since 2.0.0
+        # @api private
         UPSERTED = 'upserted'.freeze
 
         # Get the number of documents matched.
@@ -39,6 +42,7 @@ module Mongo
         # @return [ Integer ] The matched count.
         #
         # @since 2.0.0
+        # @api public
         def matched_count
           return 0 unless acknowledged?
           if upsert?
@@ -56,6 +60,7 @@ module Mongo
         # @return [ Integer ] The modified count.
         #
         # @since 2.0.0
+        # @api public
         def modified_count
           return 0 unless acknowledged?
           first[MODIFIED]
@@ -70,6 +75,7 @@ module Mongo
         # @return [ Object ] The upserted id.
         #
         # @since 2.0.0
+        # @api public
         def upserted_id
           return nil unless upsert?
           upsert?.first['_id']
@@ -83,10 +89,12 @@ module Mongo
         # @return [ Integer ] The number upserted.
         #
         # @since 2.4.2
+        # @api public
         def upserted_count
           upsert? ? n : 0
         end
 
+        # @api public
         def bulk_result
           BulkResult.new(@replies, connection_description)
         end

data/lib/mongo/operation/users_info/result.rb

@@ -20,13 +20,16 @@ module Mongo
       # usersInfo command.
       #
       # @since 2.1.0
+      # @api semiprivate
       class Result < Operation::Result
 
         # The field name for the users document in a usersInfo result.
         #
         # @since 2.1.0
+        # @api private
         USERS = 'users'.freeze
 
+        # @api public
         def documents
           reply.documents.first[USERS]
         end

data/lib/mongo/operation.rb

@@ -50,6 +50,8 @@ require 'mongo/operation/create_index'
 require 'mongo/operation/drop_index'
 
 module Mongo
+
+  # @api private
   module Operation
 
     # The q field constant.

data/lib/mongo/protocol/msg.rb

@@ -43,8 +43,8 @@ module Mongo
       #   Msg.new([:more_to_come], {}, { ismaster: 1 },
       #           { type: 1, payload: { identifier: 'documents', sequence: [..] } })
       #
-      # @param [ Array<Symbol> ] flags The flag bits. Currently supported
-      #   values are :more_to_come and :checksum_present.
+      # @param [ Array<Symbol> ] flags The flag bits. Current supported values
+      #   are :more_to_come and :checksum_present.
       # @param [ Hash ] options The options.
       # @param [ BSON::Document, Hash ] main_document The document that will
       #   become the payload type 0 section. Can contain global args as they

data/lib/mongo/protocol/query.rb

@@ -46,18 +46,18 @@ module Mongo
       # @example Find all user ids.
       #   Query.new('xgen', 'users', {}, :fields => {:id => 1})
       #
-      # @param [ String, Symbol ] database The database to query.
-      # @param [ String, Symbol ] collection The collection to query.
-      # @param [ Hash ] selector The query selector.
-      # @param [ Hash ] options The additional query options.
+      # @param database [String, Symbol] The database to query.
+      # @param collection [String, Symbol] The collection to query.
+      # @param selector [Hash] The query selector.
+      # @param options [Hash] The additional query options.
       #
-      # @option options [ Array<Symbol> ] :flags The flag bits.
-      #   Currently supported values are :await_data, :exhaust,
-      #   :no_cursor_timeout, :oplog_replay, :partial, :slave_ok,
-      #   :tailable_cursor.
-      # @option options [ Integer ] :limit The number of documents to return.
-      # @option options [ Hash ] :project The projection.
-      # @option options [ Integer ] :skip The number of documents to skip.
+      # @option options :project [Hash] The projection.
+      # @option options :skip [Integer] The number of documents to skip.
+      # @option options :limit [Integer] The number of documents to return.
+      # @option options :flags [Array] The flags for the query message.
+      #
+      #   Supported flags: +:tailable_cursor+, +:slave_ok+, +:oplog_replay+,
+      #   +:no_cursor_timeout+, +:await_data+, +:exhaust+, +:partial+
       def initialize(database, collection, selector, options = {})
         @database = database
         @namespace = "#{database}.#{collection}"

data/lib/mongo/query_cache.rb

@@ -0,0 +1,242 @@
+# 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
+  module QueryCache
+    class << self
+
+      # Set whether the cache is enabled.
+      #
+      # @example Set if the cache is enabled.
+      #   QueryCache.enabled = true
+      #
+      # @param [ true, false ] value The enabled value.
+      def enabled=(value)
+        Thread.current["[mongo]:query_cache:enabled"] = value
+      end
+
+      # Is the query cache enabled on the current thread?
+      #
+      # @example Is the query cache enabled?
+      #   QueryCache.enabled?
+      #
+      # @return [ true, false ] If the cache is enabled.
+      def enabled?
+        !!Thread.current["[mongo]:query_cache:enabled"]
+      end
+
+      # Execute the block while using the query cache.
+      #
+      # @example Execute with the cache.
+      #   QueryCache.cache { collection.find }
+      #
+      # @return [ Object ] The result of the block.
+      def cache
+        enabled = enabled?
+        self.enabled = true
+        begin
+          yield
+        ensure
+          self.enabled = enabled
+        end
+      end
+
+      # Execute the block with the query cache disabled.
+      #
+      # @example Execute without the cache.
+      #   QueryCache.uncached { collection.find }
+      #
+      # @return [ Object ] The result of the block.
+      def uncached
+        enabled = enabled?
+        self.enabled = false
+        begin
+          yield
+        ensure
+          self.enabled = enabled
+        end
+      end
+
+      # Get the cached queries.
+      #
+      # @example Get the cached queries from the current thread.
+      #   QueryCache.cache_table
+      #
+      # @return [ Hash ] The hash of cached queries.
+      private def cache_table
+        Thread.current["[mongo]:query_cache"] ||= {}
+      end
+
+      # Clear the query cache.
+      #
+      # @example Clear the cache.
+      #   QueryCache.clear
+      #
+      # @return [ nil ] Always nil.
+      def clear
+        Thread.current["[mongo]:query_cache"] = nil
+      end
+
+      # Clear the section of the query cache storing cursors with results
+      # from this namespace.
+      #
+      # @param [ String ] namespace The namespace to be cleared, in the format
+      #   "database.collection".
+      #
+      # @return [ nil ] Always nil.
+      #
+      # @api private
+      def clear_namespace(namespace)
+        cache_table.delete(namespace)
+        # The nil key is where cursors are stored that could potentially read from
+        # multiple collections. This key should be cleared on every write operation
+        # to prevent returning stale data.
+        cache_table.delete(nil)
+        nil
+      end
+
+      # Store a CachingCursor instance in the query cache associated with the
+      # specified query options.
+      #
+      # @param [ Mongo::CachingCursor ] cursor The CachingCursor instance to store.
+      #
+      # @option opts [ String | nil ] namespace The namespace of the query,
+      #   in the format "database_name.collection_name".
+      # @option opts [ Array, Hash ] selector The selector passed to the query.
+      #   For most queries, this will be a Hash, but for aggregations, this
+      #   will be an Array representing the aggregation pipeline. May not be nil.
+      # @option opts [ Integer | nil ] skip The skip value of the query.
+      # @option opts [ Hash | nil ] sort The order of the query results
+      #   (e.g. { name: -1 }).
+      # @option opts [ Integer | nil ] limit The limit value of the query.
+      # @option opts [ Hash | nil ] projection The projection of the query
+      #   results (e.g. { name: 1 }).
+      # @option opts [ Hash | nil ] collation The collation of the query
+      #   (e.g. { "locale" => "fr_CA" }).
+      # @option opts [ Hash | nil ] read_concern The read concern of the query
+      #   (e.g. { level: :majority }).
+      # @option opts [ Hash | nil ] read_preference The read preference of
+      #   the query (e.g. { mode: :secondary }).
+      # @option opts [ Boolean | nil ] multi_collection Whether the query
+      #   results could potentially come from multiple collections. When true,
+      #   these results will be stored under the nil namespace key and cleared
+      #   on every write command.
+      #
+      # @return [ true ] Always true.
+      #
+      # @api private
+      def set(cursor, **opts)
+        _cache_key = cache_key(**opts)
+        _namespace_key = namespace_key(**opts)
+
+        cache_table[_namespace_key] ||= {}
+        cache_table[_namespace_key][_cache_key] = cursor
+
+        true
+      end
+
+      # For the given query options, retrieve a cached cursor that can be used
+      # to obtain the correct query results, if one exists in the cache.
+      #
+      # @option opts [ String | nil ] namespace The namespace of the query,
+      #   in the format "database_name.collection_name".
+      # @option opts [ Array, Hash ] selector The selector passed to the query.
+      #   For most queries, this will be a Hash, but for aggregations, this
+      #   will be an Array representing the aggregation pipeline. May not be nil.
+      # @option opts [ Integer | nil ] skip The skip value of the query.
+      # @option opts [ Hash | nil ] sort The order of the query results
+      #   (e.g. { name: -1 }).
+      # @option opts [ Integer | nil ] limit The limit value of the query.
+      # @option opts [ Hash | nil ] projection The projection of the query
+      #   results (e.g. { name: 1 }).
+      # @option opts [ Hash | nil ] collation The collation of the query
+      #   (e.g. { "locale" => "fr_CA" }).
+      # @option opts [ Hash | nil ] read_concern The read concern of the query
+      #   (e.g. { level: :majority }).
+      # @option opts [ Hash | nil ] read_preference The read preference of
+      #   the query (e.g. { mode: :secondary }).
+      # @option opts [ Boolean | nil ] multi_collection Whether the query
+      #   results could potentially come from multiple collections. When true,
+      #   these results will be stored under the nil namespace key and cleared
+      #   on every write command.
+      #
+      # @return [ Mongo::CachingCursor | nil ] Returns a CachingCursor if one
+      #   exists in the query cache, otherwise returns nil.
+      #
+      # @api private
+      def get(**opts)
+        limit = opts[:limit]
+        _namespace_key = namespace_key(**opts)
+        _cache_key = cache_key(**opts)
+
+        namespace_hash = cache_table[_namespace_key]
+        return nil unless namespace_hash
+
+        caching_cursor = namespace_hash[_cache_key]
+        return nil unless caching_cursor
+
+        caching_cursor_limit = caching_cursor.view.limit
+
+        # There are two scenarios in which a caching cursor could fulfill the
+        # query:
+        # 1. The query has a limit, and the stored cursor has no limit or
+        #    a larger limit.
+        # 2. The query has no limit and the stored cursor has no limit.
+        #
+        # Otherwise, return nil because the stored cursor will not satisfy
+        # the query.
+        if limit && (caching_cursor_limit.nil? || caching_cursor_limit >= limit)
+          caching_cursor
+        elsif limit.nil? && caching_cursor_limit.nil?
+          caching_cursor
+        else
+          nil
+        end
+      end
+
+      private
+
+      def cache_key(**opts)
+        unless opts[:namespace]
+          raise ArgumentError.new("Cannot generate cache key without namespace")
+        end
+        unless opts[:selector]
+          raise ArgumentError.new("Cannot generate cache key without selector")
+        end
+
+        [
+          opts[:namespace],
+          opts[:selector],
+          opts[:skip],
+          opts[:sort],
+          opts[:projection],
+          opts[:collation],
+          opts[:read_concern],
+          opts[:read_preference]
+        ]
+      end
+
+      # If the cached results can come from multiple collections, store this
+      # cursor under the nil namespace to be cleared on every write operation.
+      # Otherwise, store it under the specified namespace.
+      def namespace_key(**opts)
+        if opts[:multi_collection]
+          nil
+        else
+          opts[:namespace]
+        end
+      end
+    end
+  end
+end

data/lib/mongo/retryable.rb

@@ -59,7 +59,14 @@ module Mongo
     def read_with_retry_cursor(session, server_selector, view, &block)
       read_with_retry(session, server_selector) do |server|
         result = yield server
-        Cursor.new(view, result, server, session: session)
+
+        # RUBY-2367: This will be updated to allow the query cache to
+        # cache cursors with multi-batch results.
+        if QueryCache.enabled? && !view.collection.system_collection?
+          CachingCursor.new(view, result, server, session: session)
+        else
+          Cursor.new(view, result, server, session: session)
+        end
       end
     end
 

data/lib/mongo/server/connection_common.rb

@@ -105,8 +105,8 @@ module Mongo
           options.select { |k, v| k.to_s.start_with?('ssl') }
         else
           # Due to the way options are propagated from the client, if we
-          # decide that we don't want to use TLS we need to have the ssl
-          # options explicitly set to false or the value provided to the
+          # decide that we don't want to use TLS we need to have the :ssl
+          # option explicitly set to false or the value provided to the
           # connection might be overwritten by the default inherited from
           # the client.
           {ssl: false}