mongo 2.13.1 → 2.14.0.rc1

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

@@ -18,6 +18,7 @@ module Mongo
     # Custom behavior for operations that support the bypassdocumentvalidation option.
     #
     # @since 2.5.2
+    # @api private
     module BypassDocumentValidation
 
       private

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/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

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/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