mongoid 6.3.0 → 6.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5c7e1fbb3fda280fb0e0f74c312b36b7a73dad79
-  data.tar.gz: 92dcab3023e9005560efd4209e3eecd26032b259
+SHA256:
+  metadata.gz: 6df494597043866e131edd0f3ac733a2b9858819d0ea5e64dd71a876dc0f5c92
+  data.tar.gz: 11b00b2c3c74e486c605729487caacbad6b6790ad1168d9f9f25088018187c1d
 SHA512:
-  metadata.gz: 44e65ba1446fc7c42e545b38223d4122e798f85d26aeb93103b85c45e7a4abc17e3b7da9f60853a7a38a24b5d4a258338111759d0b22bb4e5f99611e002eaa0f
-  data.tar.gz: 25b84f09ac4fb6366a0d9782d0865a0a1ae214234fbdbde4ce57146d8bf740823b66f15d4871e4a45b0d3fc5f0557b9f91dd743501713ae6920a430e90bab62e
+  metadata.gz: ef53e2257470d0ba736764568da53a4ccef25e525d1f5782c7e364f313be22f0b6c5bbabab354608da0de5887e7f505602936cc3e701fc1487c0969bcae3061e
+  data.tar.gz: 2fe686e8ad285385f787079a8a065e4ad7311dc1a034be6bcc722611d976b5b9b3bf421fc9a6fab861dce3d296178138c325998bada913e5b8f8d83298b3ee6c

data/Rakefile

@@ -33,3 +33,15 @@ RSpec::Core::RakeTask.new('spec:progress') do |spec|
 end
 
 task :default => :spec
+
+desc "Generate all documentation"
+task :docs => 'docs:yard'
+
+namespace :docs do
+  desc "Generate yard documention"
+  task :yard do
+    out = File.join('yard-docs', Mongoid::VERSION)
+    FileUtils.rm_rf(out)
+    system "yardoc -o #{out} --title mongoid-#{Mongoid::VERSION}"
+  end
+end

data/lib/config/locales/en.yml

@@ -206,6 +206,20 @@ en:
             \_\_\_\_include Mongoid::Document\n
             \_\_\_\_scope :inactive, ->{ where(active: false) }\n
             \_\_end\n\n"
+        invalid_session_use:
+          message: "A session was attempted to be used with a model whose client cannot use
+            that session."
+          summary: "Sessions are started via driver clients (Model#mongo_client) and, in most cases, driver
+            clients are shared across models. When different models have their own clients, a session cannot
+            be obtained via one model and used for operations on another model."
+          resolution: "Only execute operations on the model class or instances of the model through which
+            the session was created. Otherwise, ensure that all models on which operations are executed
+            in the session block share the same driver client. For example, a model may have a different
+            client specified in its 'store_in' options.\n\n"
+        invalid_session_nesting:
+          message: "A session was started while another session was being used."
+          summary: "Sessions cannot be nested. Only one session can be used in a thread at once."
+          resolution: "Only use one session at a time; sessions cannot be nested."
         invalid_storage_options:
           message: "Invalid options passed to %{klass}.store_in: %{options}."
           summary: "The :store_in macro takes only a hash of parameters with
@@ -452,6 +466,13 @@ en:
             with the already defined method %{model_name}, or set the
             configuration option Mongoid.scope_overwrite_exception to false,
             which is its default. In this case a warning will be logged."
+        sessions_not_supported:
+          message: "Sessions are not supported by the connected server(s)."
+          summary: "A session was attempted to be used with a MongoDB server version
+            that doesn't support sessions. Sessions are supported in MongoDB
+            server versions 3.6 and higher."
+          resolution: "Verify that all servers in your deployment are at least
+            version 3.6 or don't attempt to use sessions with older server versions."
         taken:
           "is already taken"
         too_many_nested_attribute_records:

data/lib/mongoid.rb

@@ -42,7 +42,7 @@ module Mongoid
   PLATFORM_DETAILS = "mongoid-#{VERSION}".freeze
 
   # The minimum MongoDB version supported.
-  MONGODB_VERSION = "2.4.0"
+  MONGODB_VERSION = "2.6.0"
 
   # Sets the Mongoid configuration options. Best used by passing a block.
   #
@@ -101,5 +101,5 @@ module Mongoid
   #   Mongoid.database = Mongo::Connection.new.db("test")
   #
   # @since 1.0.0
-  delegate(*(Config.public_instance_methods(false) - [ :logger=, :logger ] << { to: Config }))
+  delegate(*(Config.public_instance_methods(false) - [ :logger=, :logger ]), to: Config)
 end

data/lib/mongoid/clients.rb

@@ -3,12 +3,14 @@ require "mongoid/clients/factory"
 require "mongoid/clients/validators"
 require "mongoid/clients/storage_options"
 require "mongoid/clients/options"
+require "mongoid/clients/sessions"
 
 module Mongoid
   module Clients
     extend ActiveSupport::Concern
     include StorageOptions
     include Options
+    include Sessions
 
     class << self
 

data/lib/mongoid/clients/sessions.rb

@@ -0,0 +1,113 @@
+module Mongoid
+  module Clients
+
+    # Encapsulates behavior for getting a session from the client of a model class or instance,
+    # setting the session on the current thread, and yielding to a block.
+    # The session will be closed after the block completes or raises an error.
+    #
+    # @since 6.4.0
+    module Sessions
+
+      # Execute a block within the context of a session.
+      #
+      # @example Execute some operations in the context of a session.
+      #   band.with_session(causal_consistency: true) do
+      #     band.records << Record.create
+      #     band.name = 'FKA Twigs'
+      #     band.save
+      #     band.reload
+      #   end
+      #
+      # @param [ Hash ] options The session options. Please see the driver
+      #   documentation for the available session options.
+      #
+      # @note You cannot do any operations in the block using models or objects
+      #   that use a different client; the block will execute all operations
+      #   in the context of the implicit session and operations on any models using
+      #   another client will fail. For example, if you set a client using store_in on a
+      #   particular model and execute an operation on it in the session context block,
+      #   that operation can't use the block's session and an error will be raised.
+      #   An error will also be raised if sessions are nested.
+      #
+      # @raise [ Errors::InvalidSessionUse ] If an operation is attempted on a model using another
+      #   client from which the session was started or if sessions are nested.
+      #
+      # @return [ Object ] The result of calling the block.
+      #
+      # @yieldparam [ Mongo::Session ] The session being used for the block.
+      #
+      # @since 6.4.0
+      def with_session(options = {})
+        raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting) if Threaded.get_session
+        session = persistence_context.client.start_session(options)
+        Threaded.set_session(session)
+        yield(session)
+      rescue Mongo::Error::InvalidSession => ex
+        if ex.message == Mongo::Session::SESSIONS_NOT_SUPPORTED
+          raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
+        end
+        raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
+      ensure
+        Threaded.clear_session
+      end
+
+      private
+
+      def _session
+        Threaded.get_session
+      end
+
+      module ClassMethods
+
+        # Execute a block within the context of a session.
+        #
+        # @example Execute some operations in the context of a session.
+        #   Band.with_session(causal_consistency: true) do
+        #     band = Band.create
+        #     band.records << Record.new
+        #     band.save
+        #     band.reload.records
+        #   end
+        #
+        # @param [ Hash ] options The session options. Please see the driver
+        #   documentation for the available session options.
+        #
+        # @note You cannot do any operations in the block using models or objects
+        #   that use a different client; the block will execute all operations
+        #   in the context of the implicit session and operations on any models using
+        #   another client will fail. For example, if you set a client using store_in on a
+        #   particular model and execute an operation on it in the session context block,
+        #   that operation can't use the block's session and an error will be raised.
+        #   You also cannot nest sessions.
+        #
+        # @raise [ Errors::InvalidSessionUse ] If an operation is attempted on a model using another
+        #   client from which the session was started or if sessions are nested.
+        #
+        # @return [ Object ] The result of calling the block.
+        #
+        # @yieldparam [ Mongo::Session ] The session being used for the block.
+        #
+        # @since 6.4.0
+        def with_session(options = {})
+          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_nesting) if Threaded.get_session
+          session = persistence_context.client.start_session(options)
+          Threaded.set_session(session)
+          yield(session)
+        rescue Mongo::Error::InvalidSession => ex
+          if ex.message == Mongo::Session::SESSIONS_NOT_SUPPORTED
+            raise Mongoid::Errors::InvalidSessionUse.new(:sessions_not_supported)
+          end
+          raise Mongoid::Errors::InvalidSessionUse.new(:invalid_session_use)
+        ensure
+          Threaded.clear_session
+        end
+
+        private
+
+        def _session
+          Threaded.get_session
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/clients/storage_options.rb

@@ -61,6 +61,7 @@ module Mongoid
         # @since 4.0.0
         def reset_storage_options!
           self.storage_options = storage_options_defaults.dup
+          PersistenceContext.clear(self)
         end
 
         # Get the default storage options.

data/lib/mongoid/contextual/aggregable/mongo.rb

@@ -23,7 +23,7 @@ module Mongoid
         #
         # @since 3.0.0
         def aggregates(field)
-          result = collection.find.aggregate(pipeline(field)).to_a
+          result = collection.find.aggregate(pipeline(field), session: _session).to_a
           if result.empty?
             { "count" => 0, "sum" => nil, "avg" => nil, "min" => nil, "max" => nil }
           else

data/lib/mongoid/contextual/map_reduce.rb

@@ -165,13 +165,13 @@ module Mongoid
       def raw
         validate_out!
         cmd = command
-        opts = { read: cmd.delete(:read).options } if cmd[:read]
-        @map_reduce.database.command(cmd, opts || {}).first
+        opts = { read: cmd.delete(:read) } if cmd[:read]
+        @map_reduce.database.command(cmd, (opts || {}).merge(session: _session)).first
       end
       alias :results :raw
 
       # Execute the map/reduce, returning the raw output.
-      # Useful when you don't care about map/reduce's ouptut.
+      # Useful when you don't care about map/reduce's output.
       #
       # @example Run the map reduce
       #   map_reduce.execute
@@ -249,6 +249,10 @@ module Mongoid
       def validate_out!
         raise Errors::NoMapReduceOutput.new({}) unless @map_reduce.out
       end
+
+      def _session
+        criteria.send(:_session)
+      end
     end
   end
 end

data/lib/mongoid/contextual/memory.rb

@@ -48,7 +48,8 @@ module Mongoid
         end
         unless removed.empty?
           collection.find(selector).update_one(
-            positionally(selector, "$pullAll" => { path => removed })
+            positionally(selector, "$pullAll" => { path => removed }),
+            session: _session
           )
         end
         deleted
@@ -303,7 +304,7 @@ module Mongoid
           updates["$set"].merge!(doc.atomic_updates["$set"] || {})
           doc.move_changes
         end
-        collection.find(selector).update_one(updates) unless updates["$set"].empty?
+        collection.find(selector).update_one(updates, session: _session) unless updates["$set"].empty?
       end
 
       # Get the limiting value.
@@ -444,6 +445,10 @@ module Mongoid
         doc._parent.remove_child(doc)
         doc.destroyed = true
       end
+
+      def _session
+        @criteria.send(:_session)
+      end
     end
   end
 end

data/lib/mongoid/contextual/mongo.rb

@@ -95,7 +95,8 @@ module Mongoid
       def destroy
         each.inject(0) do |count, doc|
           doc.destroy
-          count += 1
+          count += 1 if acknowledged_write?
+          count
         end
       end
       alias :destroy_all :destroy
@@ -340,7 +341,7 @@ module Mongoid
         @criteria, @klass, @cache = criteria, criteria.klass, criteria.options[:cache]
         @collection = @klass.collection
         criteria.send(:merge_type_selection)
-        @view = collection.find(criteria.selector)
+        @view = collection.find(criteria.selector, session: _session)
         apply_options
       end
 
@@ -704,6 +705,14 @@ module Mongoid
         yield(doc)
         documents.push(doc) if cacheable?
       end
+
+      def _session
+        @criteria.send(:_session)
+      end
+
+      def acknowledged_write?
+        collection.write_concern.nil? || collection.write_concern.acknowledged?
+      end
     end
   end
 end

data/lib/mongoid/criteria.rb

@@ -28,6 +28,7 @@ module Mongoid
     include Scopable
     include Clients::Options
     include Options
+    include Clients::Sessions
 
     # Static array used to check with method missing - we only need to ever
     # instantiate once.

data/lib/mongoid/criteria/modifiable.rb

@@ -3,6 +3,10 @@ module Mongoid
   class Criteria
     module Modifiable
 
+      # @attribute [r] create_attrs Additional attributes to add to the Document upon creation.
+      # @api private
+      attr_reader :create_attrs
+
       # Build a document given the selector and return it.
       # Complex criteria, such as $in and $or operations will get ignored.
       #
@@ -57,6 +61,9 @@ module Mongoid
 
       # Define attributes with which new documents will be created.
       #
+      # Note that if `find_or_create_by` is called after this in a method chain, the attributes in
+      # the query will override those from this method.
+      #
       # @example Define attributes to be used when a new document is created.
       #   Person.create_with(job: 'Engineer').find_or_create_by(employer: 'MongoDB')
       #
@@ -64,7 +71,9 @@ module Mongoid
       #
       # @since 5.1.0
       def create_with(attrs = {})
-        where(selector.merge(attrs))
+        tap do
+          (@create_attrs ||= {}).merge!(attrs)
+        end
       end
 
       # Find the first +Document+ given the conditions, or creates a new document
@@ -172,7 +181,8 @@ module Mongoid
       #
       # @since 3.0.0
       def create_document(method, attrs = nil, &block)
-        attributes = selector.reduce(attrs ? attrs.dup : {}) do |hash, (key, value)|
+        attrs = (create_attrs || {}).merge(attrs || {})
+        attributes = selector.reduce(attrs) do |hash, (key, value)|
           unless invalid_key?(hash, key) || invalid_embedded_doc?(value)
             hash[key] = value
           end

data/lib/mongoid/criteria/queryable/mergeable.rb

@@ -259,7 +259,9 @@ module Mongoid
         def prepare(field, operator, value)
           unless operator =~ /exists|type|size/
             value = value.__expand_complex__
-            serializer = serializers[field]
+            field = field.to_s
+            name = aliases[field] || field
+            serializer = serializers[name]
             value = serializer ? serializer.evolve(value) : value
           end
           selection = { operator => value }

data/lib/mongoid/criteria/queryable/selectable.rb

@@ -24,7 +24,7 @@ module Mongoid
         # @since 2.0.0
         POLYGON = "Polygon"
 
-        # @attribute [rw] negating If the next spression is negated.
+        # @attribute [rw] negating If the next expression is negated.
         # @attribute [rw] selector The query selector.
         attr_accessor :negating, :selector
 
@@ -134,13 +134,21 @@ module Mongoid
           ::Boolean.evolve(value)
         end
 
-        # Add a $geoIntersects or $geoWithin selection. Symbol operators must be used as shown in
-        # the examples to expand the criteria.
+        # Add a $geoIntersects or $geoWithin selection. Symbol operators must
+        # be used as shown in the examples to expand the criteria.
         #
         # @note The only valid geometry shapes for a $geoIntersects are:
         #   :intersects_line, :intersects_point, and :intersects_polygon.
         #
-        # @note The only valid geometry shape for a $geoWithin is :within_polygon
+        # @note The only valid options for a $geoWithin query are the geometry
+        #   shape :within_polygon and the operator :within_box.
+        #
+        # @note The :within_box operator for the $geoWithin query expects the
+        #   lower left (south west) coordinate pair as the first argument and
+        #   the upper right (north east) as the second argument.
+        #   Important: When latitude and longitude are passed, longitude is
+        #   expected as the first element of the coordinate pair.
+        #   Source: https://docs.mongodb.com/manual/reference/operator/query/box/
         #
         # @example Add a geo intersect criterion for a line.
         #   query.geo_spacial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])
@@ -154,6 +162,9 @@ module Mongoid
         # @example Add a geo within criterion for a polygon.
         #   query.geo_spacial(:location.within_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])
         #
+        # @example Add a geo within criterion for a box.
+        #   query.geo_spacial(:location.within_box => [[ 1, 10 ], [ 2, 10 ])
+        #
         # @param [ Hash ] criterion The criterion.
         #
         # @return [ Selectable ] The cloned selectable.
@@ -174,6 +185,7 @@ module Mongoid
         key :within_polygon, :override, "$geoWithin", "$geometry" do |value|
           { "type" => POLYGON, "coordinates" => value }
         end
+        key :within_box, :override, "$geoWithin", "$box"
 
         # Add the $gt criterion to the selector.
         #
@@ -501,6 +513,11 @@ module Mongoid
         # @example Construct a text search selector with options.
         #   selectable.text_search("testing", :$language => "fr")
         #
+        # @note Per https://docs.mongodb.com/manual/reference/operator/query/text/
+        #   it is not currently possible to supply multiple text search
+        #   conditions in a query. Mongoid will build such a query but the
+        #   server will return an error when trying to execute it.
+        #
         # @param [ String, Symbol ] terms A string of terms that MongoDB parses
         #   and uses to query the text index.
         # @param [ Hash ] opts Text search options. See MongoDB documentation
@@ -512,9 +529,19 @@ module Mongoid
         def text_search(terms, opts = nil)
           clone.tap do |query|
             if terms
-              criterion = { :$text => { :$search => terms } }
-              criterion[:$text].merge!(opts) if opts
-              query.selector = criterion
+              criterion = {'$text' => { '$search' => terms }}
+              criterion['$text'].merge!(opts) if opts
+              if query.selector['$text']
+                # Per https://docs.mongodb.com/manual/reference/operator/query/text/
+                # multiple $text expressions are not currently supported by
+                # MongoDB server, but build the query correctly instead of
+                # overwriting previous text search condition with the currently
+                # given one.
+                Mongoid.logger.warn('Multiple $text expressions per query are not currently supported by the server')
+                query.selector = {'$and' => [query.selector]}.merge(criterion)
+              else
+                query.selector = query.selector.merge(criterion)
+              end
             end
           end
         end