mongo 2.15.0 → 2.18.1

data/lib/mongo/collection/view.rb

@@ -141,6 +141,8 @@ module Mongo
       # @option options [ Hash ] :read The read preference to use for the
       #   query. If none is provided, the collection's default read preference
       #   is used.
+      # @option options [ Hash ] :read_concern The read concern to use for
+      #   the query.
       # @option options [ true | false ] :show_disk_loc Return disk location
       #   info as a field in each doc.
       # @option options [ Integer ] :skip The number of documents to skip.
@@ -153,7 +155,19 @@ module Mongo
       def initialize(collection, filter = {}, options = {})
         validate_doc!(filter)
         @collection = collection
-        parse_parameters!(BSON::Document.new(filter), BSON::Document.new(options))
+
+        filter = BSON::Document.new(filter)
+        options = BSON::Document.new(options)
+
+        # This is when users pass $query in filter and other modifiers
+        # alongside?
+        query = filter.delete(:$query)
+        # This makes modifiers contain the filter if filter wasn't
+        # given via $query but as top-level keys, presumably
+        # downstream code ignores non-modifier keys in the modifiers?
+        modifiers = filter.merge(options.delete(:modifiers) || {})
+        @filter = (query || filter).freeze
+        @options = Operation::Find::Builder::Modifiers.map_driver_options(modifiers).merge!(options).freeze
       end
 
       # Get a human-readable string representation of +View+.
@@ -189,30 +203,10 @@ module Mongo
         @filter = other.filter.dup
       end
 
-      def parse_parameters!(filter, options)
-        query = filter.delete(QUERY)
-        modifiers = (filter || {}).merge(options.delete(MODIFIERS) || {})
-        @filter = (query || filter).freeze
-        @options = Builder::Modifiers.map_driver_options(modifiers).merge!(options).freeze
-      end
-
       def new(options)
         View.new(collection, filter, options)
       end
 
-      def apply_collation!(doc, server, opts = {})
-        if coll = doc[:collation] || opts[:collation] || opts['collation'] || collation
-          validate_collation!(server, coll)
-          doc[:collation] = coll
-        end
-      end
-
-      def validate_collation!(server, coll)
-        if coll && !server.with_connection { |connection| connection.features }.collation_enabled?
-          raise Error::UnsupportedCollation.new
-        end
-      end
-
       def view; self; end
 
       def with_session(opts = {}, &block)

data/lib/mongo/collection.rb

@@ -17,6 +17,8 @@
 
 require 'mongo/bulk_write'
 require 'mongo/collection/view'
+require 'mongo/collection/helpers'
+require 'mongo/collection/queryable_encryption'
 
 module Mongo
 
@@ -27,6 +29,8 @@ module Mongo
   class Collection
     extend Forwardable
     include Retryable
+    include QueryableEncryption
+    include Helpers
 
     # The capped option.
     #
@@ -47,8 +51,8 @@ module Mongo
     # @return [ Hash ] The collection options.
     attr_reader :options
 
-    # Get client, cluster, read preference, and write concern from client.
-    def_delegators :database, :client, :cluster
+    # Get client, cluster, read preference, write concern, and encrypted_fields_map from client.
+    def_delegators :database, :client, :cluster, :encrypted_fields_map
 
     # Delegate to the cluster for the next primary.
     def_delegators :cluster, :next_primary
@@ -58,10 +62,17 @@ module Mongo
     # @since 2.1.0
     CHANGEABLE_OPTIONS = [ :read, :read_concern, :write, :write_concern ].freeze
 
-    # Options that can be used for creating a time-series collection.
-    TIME_SERIES_OPTIONS = {
+    # Options map to transform create collection options.
+    #
+    # @api private
+    CREATE_COLLECTION_OPTIONS = {
       :time_series => :timeseries,
-      :expire_after => :expireAfterSeconds
+      :expire_after => :expireAfterSeconds,
+      :clustered_index => :clusteredIndex,
+      :change_stream_pre_and_post_images => :changeStreamPreAndPostImages,
+      :encrypted_fields => :encryptedFields,
+      :validator => :validator,
+      :view_on => :viewOn
     }
 
     # Check if a collection is equal to another object. Will check the name and
@@ -94,10 +105,14 @@ module Mongo
     # @option options [ Hash ] :write_concern The write concern options.
     #   Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.
     # @option options [ Hash ] :time_series Create a time-series collection.
-    #   See https://docs.mongodb.com/manual/core/timeseries-collections/ for more
+    #   See https://mongodb.com/docs/manual/core/timeseries-collections/ for more
     #   information about time-series collection.
     # @option options [ Integer ] :expire_after Number indicating
     #   after how many seconds old time-series data should be deleted.
+    # @options clustered_index [ Hash ] :clustered_index Create a clustered index.
+    #   This option specifies how this collection should be clustered on _id.
+    #   See https://www.mongodb.com/docs/v5.3/reference/method/db.createCollection/#std-label-db.createCollection.clusteredIndex
+    #   for more information about this option.
     #
     # @since 2.0.0
     def initialize(database, name, options = {})
@@ -241,6 +256,12 @@ module Mongo
     # @option opts [ Hash ] :time_series Create a time-series collection.
     # @option opts [ Integer ] :expire_after Number indicating
     #   after how many seconds old time-series data should be deleted.
+    # @option opts [ Hash ] :change_stream_pre_and_post_images Used to enable
+    #   pre- and post-images on the created collection.
+    # @option opts [ Hash ] :encrypted_fields Hash describing encrypted fields
+    #   for queryable encryption.
+    # @option opts [ Hash ] :validator Hash describing document validation
+    #   options for the collection.
     #
     # @return [ Result ] The result of the command.
     #
@@ -251,11 +272,11 @@ module Mongo
       # TODO put the list of read options in a class-level constant when
       # we figure out what the full set of them is.
       options = Hash[self.options.reject do |key, value|
-        %w(read read_preference).include?(key.to_s)
+        %w(read read_preference read_concern).include?(key.to_s)
       end]
-      options.update(Utils.slice_hash(opts, *TIME_SERIES_OPTIONS.keys))
-      # Converting Ruby spelled time series options to server style.
-      TIME_SERIES_OPTIONS.each do |ruby_key, server_key|
+      options.update(opts.slice(*CREATE_COLLECTION_OPTIONS.keys))
+      # Converting Ruby options to server style.
+      CREATE_COLLECTION_OPTIONS.each do |ruby_key, server_key|
         if options.key?(ruby_key)
           options[server_key] = options.delete(ruby_key)
         end
@@ -269,22 +290,26 @@ module Mongo
         else
           self.write_concern
         end
-        server = next_primary(nil, session)
-        if (options[:collation] || options[Operation::COLLATION]) && !server.with_connection { |connection| connection.features }.collation_enabled?
-          raise Error::UnsupportedCollation
-        end
 
-        Operation::Create.new({
-                                selector: operation,
-                                db_name: database.name,
-                                write_concern: write_concern,
-                                session: session,
-                                }).execute(server, context: Operation::Context.new(client: client, session: session))
+        context = Operation::Context.new(client: client, session: session)
+        maybe_create_qe_collections(opts[:encrypted_fields], client, session) do |encrypted_fields|
+          Operation::Create.new(
+            selector: operation,
+            db_name: database.name,
+            write_concern: write_concern,
+            session: session,
+            # Note that these are collection options, collation isn't
+            # taken from options passed to the create method.
+            collation: options[:collation] || options['collation'],
+            encrypted_fields: encrypted_fields,
+            validator: options[:validator],
+          ).execute(next_primary(nil, session), context: context)
+        end
       end
     end
 
     # Drop the collection. Will also drop all indexes associated with the
-    # collection.
+    # collection, as well as associated queryable encryption collections.
     #
     # @note An error returned if the collection doesn't exist is suppressed.
     #
@@ -301,25 +326,22 @@ module Mongo
     # @since 2.0.0
     def drop(opts = {})
       client.send(:with_session, opts) do |session|
-        temp_write_concern = write_concern
-        write_concern = if opts[:write_concern]
-          WriteConcern.get(opts[:write_concern])
-        else
-          temp_write_concern
+        maybe_drop_emm_collections(opts[:encrypted_fields], client, session) do
+          temp_write_concern = write_concern
+          write_concern = if opts[:write_concern]
+            WriteConcern.get(opts[:write_concern])
+          else
+            temp_write_concern
+          end
+          context = Operation::Context.new(client: client, session: session)
+          operation = Operation::Drop.new({
+            selector: { :drop => name },
+            db_name: database.name,
+            write_concern: write_concern,
+            session: session,
+          })
+          do_drop(operation, session, context)
         end
-        Operation::Drop.new({
-                              selector: { :drop => name },
-                              db_name: database.name,
-                              write_concern: write_concern,
-                              session: session,
-                              }).execute(next_primary(nil, session), context: Operation::Context.new(client: client, session: session))
-      end
-    rescue Error::OperationFailure => ex
-      # NamespaceNotFound
-      if ex.code == 26 || ex.code.nil? && ex.message =~ /ns not found/
-        false
-      else
-        raise
       end
     end
 
@@ -343,7 +365,8 @@ module Mongo
     # @option options [ Integer ] :batch_size The number of documents returned in each batch
     #   of results from MongoDB.
     # @option options [ Hash ] :collation The collation to use.
-    # @option options [ String ] :comment Associate a comment with the query.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     # @option options [ :tailable, :tailable_await ] :cursor_type The type of cursor to use.
     # @option options [ Integer ] :limit The max number of docs to return from the query.
     # @option options [ Integer ] :max_time_ms
@@ -353,14 +376,16 @@ module Mongo
     # @option options [ true, false ] :no_cursor_timeout The server normally times out idle
     #   cursors after an inactivity period (10 minutes) to prevent excess memory use.
     #   Set this option to prevent that.
-    # @option options [ true, false ] :oplog_replay Internal replication use only - driver
-    #   should not set.
+    # @option options [ true, false ] :oplog_replay For internal replication
+    #   use only, applications should not set this option.
     # @option options [ Hash ] :projection The fields to include or exclude from each doc
     #   in the result set.
     # @option options [ Session ] :session The session to use.
     # @option options [ Integer ] :skip The number of docs to skip before returning results.
     # @option options [ Hash ] :sort The key and direction pairs by which the result set
     #   will be sorted.
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ CollectionView ] The collection view.
     #
@@ -384,8 +409,11 @@ 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 [ String ] :hint The index to use for the aggregation.
+    # @option options [ Hash ] :let Mapping of variables to use in the pipeline.
+    #   See the server documentation for details.
     # @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
@@ -412,11 +440,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
@@ -429,6 +481,13 @@ module Mongo
     #   changes that occurred at or 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
@@ -438,7 +497,9 @@ module Mongo
     #
     # @since 2.5.0
     def watch(pipeline = [], options = {})
-      View::ChangeStream.new(View.new(self, {}, options), pipeline, nil, options)
+      view_options = options.dup
+      view_options[:await_data] = true if options[:max_await_time_ms]
+      View::ChangeStream.new(View.new(self, {}, view_options), pipeline, nil, options)
     end
 
     # Gets an estimated number of matching documents in the collection.
@@ -456,6 +517,8 @@ module Mongo
     # @option options [ Hash ] :read The read preference options.
     # @option options [ Hash ] :collation The collation to use.
     # @option options [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Integer ] The document count.
     #
@@ -489,6 +552,9 @@ module Mongo
     #   command to run.
     # @option options :read [ Hash ] The read preference options.
     # @option options :collation [ Hash ] The collation to use.
+    # @option options [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Integer ] The document count.
     #
@@ -505,9 +571,11 @@ module Mongo
     #
     # @param [ Hash ] options Options for the operation.
     #
-    # @option opts :max_time_ms [ Integer ] The maximum amount of time to allow
+    # @option options :max_time_ms [ Integer ] The maximum amount of time to allow
     #   the command to run for on the server.
-    # @option opts [ Hash ] :read The read preference options.
+    # @option options [ Hash ] :read The read preference options.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Integer ] The document count.
     #
@@ -593,7 +661,8 @@ module Mongo
           raise ArgumentError, "Document to be inserted cannot be nil"
         end
 
-        write_with_retry(session, write_concern) do |server, txn_num|
+        context = Operation::Context.new(client: client, session: session)
+        write_with_retry(write_concern, context: context) do |connection, txn_num, context|
           Operation::Insert.new(
             :documents => [ document ],
             :db_name => database.name,
@@ -604,7 +673,8 @@ module Mongo
             :id_generator => client.options[:id_generator],
             :session => session,
             :txn_num => txn_num,
-          ).execute(server, context: Operation::Context.new(client: client, session: session))
+            :comment => opts[:comment]
+          ).execute_with_connection(connection, context: context)
         end
       end
     end
@@ -646,6 +716,8 @@ module Mongo
     # @option options [ true, false ] :bypass_document_validation Whether or
     #   not to skip document level validation.
     # @option options [ Session ] :session The session to use for the set of operations.
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ BulkWrite::Result ] The result of the operation.
     #
@@ -666,6 +738,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ Result ] The response from the database.
     #
@@ -686,6 +760,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ Result ] The response from the database.
     #
@@ -734,6 +810,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ Result ] The response from the database.
     #
@@ -761,6 +839,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ Result ] The response from the database.
     #
@@ -788,6 +868,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ Result ] The response from the database.
     #
@@ -816,6 +898,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ BSON::Document, nil ] The document, if found.
     #
@@ -854,6 +938,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ BSON::Document ] The document.
     #
@@ -890,6 +976,8 @@ module Mongo
     # @option options [ Session ] :session The session to use.
     # @option options [ Hash | String ] :hint The index to use for this operation.
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
+    # @option options [ Hash ] :let Mapping of variables to use in the command.
+    #   See the server documentation for details.
     #
     # @return [ BSON::Document ] The document.
     #

data/lib/mongo/config/options.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Config
+
+    # Encapsulates logic for setting options.
+    module Options
+
+      # Get the defaults or initialize a new empty hash.
+      #
+      # @return [ Hash ] The default options.
+      def defaults
+        @defaults ||= {}
+      end
+
+      # Define a configuration option with a default.
+      #
+      # @param [ Symbol ] name The name of the configuration option.
+      # @param [ Hash ] options Extras for the option.
+      #
+      # @option options [ Object ] :default The default value.
+      def option(name, options = {})
+        defaults[name] = settings[name] = options[:default]
+
+        class_eval do
+          # log_level accessor is defined specially below
+          define_method(name) do
+            settings[name]
+          end
+
+          define_method("#{name}=") do |value|
+            settings[name] = value
+          end
+
+          define_method("#{name}?") do
+            !!send(name)
+          end
+        end
+      end
+
+      # Reset the configuration options to the defaults.
+      #
+      # @example Reset the configuration options.
+      #   config.reset
+      #
+      # @return [ Hash ] The defaults.
+      def reset
+        settings.replace(defaults)
+      end
+
+      # Get the settings or initialize a new empty hash.
+      #
+      # @example Get the settings.
+      #   options.settings
+      #
+      # @return [ Hash ] The setting options.
+      def settings
+        @settings ||= {}
+      end
+    end
+  end
+end

data/lib/mongo/config/validators/option.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Config
+    module Validators
+
+      # Validator for configuration options.
+      #
+      # @api private
+      module Option
+        extend self
+
+        # Validate a configuration option.
+        #
+        # @example Validate a configuration option.
+        #
+        # @param [ String ] option The name of the option.
+        def validate(option)
+          unless Config.settings.keys.include?(option.to_sym)
+            raise Mongo::Error::InvalidConfigOption.new(option)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "mongo/config/options"
+require "mongo/config/validators/option"
+
+module Mongo
+
+  # This module defines configuration options for Mongo.
+  #
+  # @api private
+  module Config
+    extend Forwardable
+    extend Options
+    extend self
+
+    # When this flag is off, an aggregation done on a view will be executed over
+    # the documents included in that view, instead of all documents in the
+    # collection. When this flag is on, the view fiter is ignored.
+    option :broken_view_aggregate, default: true
+
+    # When this flag is set to false, the view options will be correctly
+    # propagated to readable methods.
+    option :broken_view_options, default: true
+
+    # When this flag is set to true, the update and replace methods will
+    # validate the paramters and raise an error if they are invalid.
+    option :validate_update_replace, default: false
+
+    # Set the configuration options.
+    #
+    # @example Set the options.
+    #   config.options = { validate_update_replace: true }
+    #
+    # @param [ Hash ] options The configuration options.
+    def options=(options)
+      options.each_pair do |option, value|
+        Validators::Option.validate(option)
+        send("#{option}=", value)
+      end
+    end
+  end
+end