mongoid 7.5.4 → 8.1.7

data/lib/mongoid/interceptable.rb

@@ -27,7 +27,7 @@ module Mongoid
       :before_save,
       :before_update,
       :before_upsert,
-      :before_validation
+      :before_validation,
     ].freeze
 
     included do
@@ -37,6 +37,12 @@ module Mongoid
       define_model_callbacks :build, :find, :initialize, :touch, only: :after
       define_model_callbacks :create, :destroy, :save, :update, :upsert
 
+      # This callback is used internally by Mongoid to save association
+      # targets for referenced associations after the parent model is persisted.
+      #
+      # @api private
+      define_model_callbacks :persist_parent
+
       attr_accessor :before_callback_halted
     end
 
@@ -47,7 +53,7 @@ module Mongoid
     #
     # @param [ Symbol ] kind The type of callback.
     #
-    # @return [ true, false ] If the callback can be executed.
+    # @return [ true | false ] If the callback can be executed.
     def callback_executable?(kind)
       respond_to?("_#{kind}_callbacks")
     end
@@ -60,7 +66,7 @@ module Mongoid
     #
     # @param [ Symbol ] kind The callback kind.
     #
-    # @return [ true, false ] If the document is in a callback state.
+    # @return [ true | false ] If the document is in a callback state.
     def in_callback_state?(kind)
       [ :create, :destroy ].include?(kind) || new_record? || flagged_for_destroy? || changed?
     end
@@ -73,7 +79,7 @@ module Mongoid
     # @example Run only the after save callbacks.
     #   model.run_after_callbacks(:save)
     #
-    # @param [ Array<Symbol> ] kinds The events that are occurring.
+    # @param [ Symbol... ] *kinds The events that are occurring.
     #
     # @return [ Object ] The result of the chain executing.
     def run_after_callbacks(*kinds)
@@ -90,7 +96,7 @@ module Mongoid
     # @example Run only the before save callbacks.
     #   model.run_before_callbacks(:save, :create)
     #
-    # @param [ Array<Symbol> ] kinds The events that are occurring.
+    # @param [ Symbol... ] *kinds The events that are occurring.
     #
     # @return [ Object ] The result of the chain executing.
     def run_before_callbacks(*kinds)
@@ -109,22 +115,167 @@ module Mongoid
     #   end
     #
     # @param [ Symbol ] kind The type of callback to execute.
-    # @param [ Array ] args Any options.
-    #
-    # @return [ Document ] The document
-    ruby2_keywords def run_callbacks(kind, *args, &block)
-      cascadable_children(kind).each do |child|
-        if child.run_callbacks(child_callback_type(kind, child), *args) == false
-          return false
+    # @param [ true | false ] with_children Flag specifies whether callbacks of embedded document should be run.
+    def run_callbacks(kind, with_children: true, &block)
+      if with_children
+        cascadable_children(kind).each do |child|
+          if child.run_callbacks(child_callback_type(kind, child), with_children: with_children) == false
+            return false
+          end
         end
       end
       if callback_executable?(kind)
-        super(kind, *args, &block)
+        super(kind, &block)
       else
         true
       end
     end
 
+    # Run the callbacks for embedded documents.
+    #
+    # @param [ Symbol ] kind The type of callback to execute.
+    # @param [ Array<Document> ] children Children to execute callbacks on. If
+    #   nil, callbacks will be executed on all cascadable children of
+    #   the document.
+    #
+    # @api private
+    def _mongoid_run_child_callbacks(kind, children: nil, &block)
+      if Mongoid::Config.around_callbacks_for_embeds
+        _mongoid_run_child_callbacks_with_around(kind, children: children, &block)
+      else
+        _mongoid_run_child_callbacks_without_around(kind, children: children, &block)
+      end
+    end
+
+    # Execute the callbacks of given kind for embedded documents including
+    # around callbacks.
+    #
+    # @note This method is prone to stack overflow errors if the document
+    #   has a large number of embedded documents. It is recommended to avoid
+    #   using around callbacks for embedded documents until a proper solution
+    #   is implemented.
+    #
+    # @param [ Symbol ] kind The type of callback to execute.
+    # @param [ Array<Document> ] children Children to execute callbacks on. If
+    #  nil, callbacks will be executed on all cascadable children of
+    #  the document.
+    #
+    #  @api private
+    def _mongoid_run_child_callbacks_with_around(kind, children: nil, &block)
+      child, *tail = (children || cascadable_children(kind))
+      with_children = !Mongoid::Config.prevent_multiple_calls_of_embedded_callbacks
+      if child.nil?
+        block&.call
+      elsif tail.empty?
+        child.run_callbacks(child_callback_type(kind, child), with_children: with_children, &block)
+      else
+        child.run_callbacks(child_callback_type(kind, child), with_children: with_children) do
+          _mongoid_run_child_callbacks_with_around(kind, children: tail, &block)
+        end
+      end
+    end
+
+    # Execute the callbacks of given kind for embedded documents without
+    # around callbacks.
+    #
+    # @param [ Symbol ] kind The type of callback to execute.
+    # @param [ Array<Document> ] children Children to execute callbacks on. If
+    #   nil, callbacks will be executed on all cascadable children of
+    #   the document.
+    #
+    # @api private
+    def _mongoid_run_child_callbacks_without_around(kind, children: nil, &block)
+      children = (children || cascadable_children(kind))
+      callback_list = _mongoid_run_child_before_callbacks(kind, children: children)
+      return false if callback_list == false
+      value = block&.call
+      callback_list.each do |_next_sequence, env|
+        env.value &&= value
+      end
+      return false if _mongoid_run_child_after_callbacks(callback_list: callback_list) == false
+
+      value
+    end
+
+    # Execute the before callbacks of given kind for embedded documents.
+    #
+    # @param [ Symbol ] kind The type of callback to execute.
+    # @param [ Array<Document> ] children Children to execute callbacks on.
+    # @param [ Array<ActiveSupport::Callbacks::CallbackSequence, ActiveSupport::Callbacks::Filters::Environment> ] callback_list List of
+    #   pairs of callback sequence and environment. This list will be later used
+    #   to execute after callbacks in reverse order.
+    #
+    # @api private
+    def _mongoid_run_child_before_callbacks(kind, children: [], callback_list: [])
+      children.each do |child|
+        chain = child.__callbacks[child_callback_type(kind, child)]
+        env = ActiveSupport::Callbacks::Filters::Environment.new(child, false, nil)
+        next_sequence = compile_callbacks(chain)
+        unless next_sequence.final?
+          Mongoid.logger.warn("Around callbacks are disabled for embedded documents. Skipping around callbacks for #{child.class.name}.")
+          Mongoid.logger.warn("To enable around callbacks for embedded documents, set Mongoid::Config.around_callbacks_for_embeds to true.")
+        end
+        next_sequence.invoke_before(env)
+        return false if env.halted
+        env.value = !env.halted
+        callback_list << [next_sequence, env]
+        if (grandchildren = child.send(:cascadable_children, kind))
+          _mongoid_run_child_before_callbacks(kind, children: grandchildren, callback_list: callback_list)
+        end
+      end
+      callback_list
+    end
+
+    # Execute the after callbacks.
+    #
+    # @param [ Array<ActiveSupport::Callbacks::CallbackSequence, ActiveSupport::Callbacks::Filters::Environment> ] callback_list List of
+    #   pairs of callback sequence and environment.
+    def _mongoid_run_child_after_callbacks(callback_list: [])
+      callback_list.reverse_each do |next_sequence, env|
+        next_sequence.invoke_after(env)
+        return false if env.halted
+      end
+    end
+
+    # Returns the stored callbacks to be executed later.
+    #
+    # @return [ Array<Symbol> ] Method symbols of the stored pending callbacks.
+    #
+    # @api private
+    def pending_callbacks
+      @pending_callbacks ||= [].to_set
+    end
+
+    # Stores callbacks to be executed later. A good use case for
+    # this is delaying the after_find and after_initialize callbacks until the
+    # associations are set on the document. This can also be used to delay
+    # applying the defaults on a document.
+    #
+    # @param [ Array<Symbol> ] value Method symbols of the pending callbacks to store.
+    #
+    # @return [ Array<Symbol> ] Method symbols of the stored pending callbacks.
+    #
+    # @api private
+    def pending_callbacks=(value)
+      @pending_callbacks = value
+    end
+
+    # Run the pending callbacks. If the callback is :apply_defaults, we will apply
+    # the defaults for this document. Otherwise, the callback is passed to the
+    # run_callbacks function.
+    #
+    # @api private
+    def run_pending_callbacks
+      pending_callbacks.each do |cb|
+        if [:apply_defaults, :apply_post_processed_defaults].include?(cb)
+          send(cb)
+        else
+          self.run_callbacks(cb, with_children: false)
+        end
+      end
+      pending_callbacks.clear
+    end
+
     private
 
     # We need to hook into this for autosave, since we don't want it firing if
@@ -135,7 +286,7 @@ module Mongoid
     # @example Was a before callback halted?
     #   document.before_callback_halted?
     #
-    # @return [ true, false ] If a before callback was halted.
+    # @return [ true | false ] If a before callback was halted.
     def before_callback_halted?
       !!@before_callback_halted
     end
@@ -175,7 +326,7 @@ module Mongoid
     # @param [ Symbol ] kind The type of callback.
     # @param [ Document ] child The child document.
     #
-    # @return [ true, false ] If the child should fire the callback.
+    # @return [ true | false ] If the child should fire the callback.
     def cascadable_child?(kind, child, association)
       return false if kind == :initialize || kind == :find || kind == :touch
       return false if kind == :validate && association.validate?
@@ -238,7 +389,7 @@ module Mongoid
         end
         self.class.send :define_method, name do
           env = ActiveSupport::Callbacks::Filters::Environment.new(self, false, nil)
-          sequence = chain.compile
+          sequence = compile_callbacks(chain)
           sequence.invoke_before(env)
           env.value = !env.halted
           sequence.invoke_after(env)
@@ -248,5 +399,24 @@ module Mongoid
       end
       send(name)
     end
+
+    # Compile the callback chain.
+    #
+    # This method hides the differences between ActiveSupport implementations
+    # before and after 7.1.
+    #
+    # @param [ ActiveSupport::Callbacks::CallbackChain ] chain The callback chain.
+    # @param [ Symbol | nil ] type The type of callback chain to compile.
+    #
+    # @return [ ActiveSupport::Callbacks::CallbackSequence ] The compiled callback sequence.
+    def compile_callbacks(chain, type = nil)
+      if chain.method(:compile).arity == 0
+        # ActiveSupport < 7.1
+        chain.compile
+      else
+        # ActiveSupport >= 7.1
+        chain.compile(type)
+      end
+    end
   end
 end

data/lib/mongoid/matchable.rb

@@ -15,7 +15,7 @@ module Mongoid
     #
     # @param [ Hash ] selector The MongoDB selector.
     #
-    # @return [ true, false ] True if matches, false if not.
+    # @return [ true | false ] True if matches, false if not.
     def _matches?(selector)
       Matcher::Expression.matches?(self, selector)
     end

data/lib/mongoid/matcher/eq_impl.rb

@@ -46,7 +46,7 @@ module Mongoid
         end
       end
 
-      # Per https://docs.mongodb.com/ruby-driver/current/tutorials/bson-v4/#time-instances,
+      # Per https://www.mongodb.com/docs/ruby-driver/current/tutorials/bson-v4/#time-instances,
       # > Times in BSON (and MongoDB) can only have millisecond precision. When Ruby Time instances
       # are serialized to BSON or Extended JSON, the times are floored to the nearest millisecond.
       #

data/lib/mongoid/matcher/type.rb

@@ -1,7 +1,7 @@
 module Mongoid
   module Matcher
 
-    # @see https://docs.mongodb.com/manual/reference/operator/query/type/
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/type/
     #
     # @api private
     module Type

data/lib/mongoid/matcher.rb

@@ -2,7 +2,6 @@ module Mongoid
 
   # @api private
   module Matcher
-
     # Extracts field values in the document at the specified key.
     #
     # The document can be a Hash or a model instance.
@@ -24,23 +23,42 @@ module Mongoid
     #   an array of values of the `bar` field in each of the hashes in the
     #   `foo` array.
     #
-    # The return value is a two-element array. The first element is the value
-    # retrieved, or an array of values. The second element is a boolean flag
-    # indicating whether an array was expanded at any point during the key
-    # traversal (because the respective document field was an array).
+    # This method can return an individual field value in some document
+    # or an array of values from multiple documents. The array can be returned
+    # because a field value in the specified path is an array of primitive
+    # values (e.g. integers) or because a field value in the specified path
+    # is an array of documents (e.g. a one-to-many embedded association),
+    # in which case the leaf value may be a scalar for each individual document.
+    # If the leaf value is an array and a one-to-many association was traversed,
+    # the return value will be an array of arrays. Note that an individual
+    # field value can also be an array and this case is indistinguishable
+    # from and behaves identically to association traversal for the purposes
+    # of, for example, subsequent array element retrieval.
     #
-    # @param [ Document | Hash ] document The document to extract from.
+    # @param [ Document | Hash | String ] document The document to extract from.
     # @param [ String ] key The key path to extract.
     #
-    # @return [ Array<true | false, Object | Array, true | false> ]
-    #   Whether the value existed in the document, the extracted value
-    #   and the array expansion flag.
+    # @return [ Object | Array ] Field value or values.
     module_function def extract_attribute(document, key)
+      # The matcher system will wind up sending atomic values to this as well,
+      # when attepting to match more complex types. If anything other than a
+      # Document or a Hash is given, we'll short-circuit the logic and just
+      # return an empty array.
+      return [] unless document.is_a?(Hash) || document.is_a?(Document)
+
+      # Performance optimization; if the key does not include a '.' character,
+      # it must reference an immediate attribute of the document.
+      unless key.include?('.')
+        hash = document.respond_to?(:attributes) ? document.attributes : document
+        key = find_exact_key(hash, key)
+        return key ? [ hash[key] ] : []
+      end
+
       if document.respond_to?(:as_attributes, true)
         # If a document has hash fields, as_attributes would keep those fields
         # as Hash instances which do not offer indifferent access.
         # Convert to BSON::Document to get indifferent access on hash fields.
-        document = BSON::Document.new(document.send(:as_attributes))
+        document = document.send(:as_attributes)
       end
 
       current = [document]
@@ -50,8 +68,9 @@ module Mongoid
         current.each do |doc|
           case doc
           when Hash
-            if doc.key?(field)
-              new << doc[field]
+            actual_key = find_exact_key(doc, field)
+            if !actual_key.nil?
+              new << doc[actual_key]
             end
           when Array
             if (index = field.to_i).to_s == field
@@ -61,8 +80,9 @@ module Mongoid
             end
             doc.each do |subdoc|
               if Hash === subdoc
-                if subdoc.key?(field)
-                  new << subdoc[field]
+                actual_key = find_exact_key(subdoc, field)
+                if !actual_key.nil?
+                  new << subdoc[actual_key]
                 end
               end
             end
@@ -74,6 +94,20 @@ module Mongoid
 
       current
     end
+
+    # Indifferent string or symbol key lookup, returning the exact key.
+    #
+    # @param [ Hash ] hash The input hash.
+    # @param [ String | Symbol ] key The key to perform indifferent lookups with.
+    #
+    # @return [ String | Symbol | nil ] The exact key (with the correct type) that exists in the hash, or nil if the key does not exist.
+    module_function def find_exact_key(hash, key)
+      key_s = key.to_s
+      return key_s if hash.key?(key_s)
+
+      key_sym = key.to_sym
+      hash.key?(key_sym) ? key_sym : nil
+    end
   end
 end
 

data/lib/mongoid/persistable/creatable.rb

@@ -100,15 +100,25 @@ module Mongoid
       #
       # @return [ Document ] The document.
       def prepare_insert(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
         return self if performing_validations?(options) &&
           invalid?(options[:context] || :create)
-        result = run_callbacks(:save) do
-          run_callbacks(:create) do
-            yield(self)
-            post_process_insert
+        run_callbacks(:save, with_children: false) do
+          run_callbacks(:create, with_children: false) do
+            run_callbacks(:persist_parent, with_children: false) do
+              _mongoid_run_child_callbacks(:save) do
+                _mongoid_run_child_callbacks(:create) do
+                  result = yield(self)
+                  if !result.is_a?(Document) || result.errors.empty?
+                    post_process_insert
+                    post_process_persist(result, options)
+                  end
+                end
+              end
+            end
           end
         end
-        post_process_persist(result, options) and self
+        self
       end
 
       module ClassMethods
@@ -123,10 +133,10 @@ module Mongoid
         # @example Create multiple new documents.
         #   Person.create({ title: "Mr" }, { title: "Mrs" })
         #
-        # @param [ Hash, Array ] attributes The attributes to create with, or an
+        # @param [ Hash | Array ] attributes The attributes to create with, or an
         #   Array of multiple attributes for multiple documents.
         #
-        # @return [ Document, Array<Document> ] The newly created document(s).
+        # @return [ Document | Array<Document> ] The newly created document(s).
         def create(attributes = nil, &block)
           _creating do
             if attributes.is_a?(::Array)
@@ -150,10 +160,10 @@ module Mongoid
         # @example Create multiple new documents.
         #   Person.create!({ title: "Mr" }, { title: "Mrs" })
         #
-        # @param [ Hash, Array ] attributes The attributes to create with, or an
+        # @param [ Hash | Array ] attributes The attributes to create with, or an
         #   Array of multiple attributes for multiple documents.
         #
-        # @return [ Document, Array<Document> ] The newly created document(s).
+        # @return [ Document | Array<Document> ] The newly created document(s).
         def create!(attributes = nil, &block)
           _creating do
             if attributes.is_a?(::Array)

data/lib/mongoid/persistable/deletable.rb

@@ -16,7 +16,6 @@ module Mongoid
       #
       # @return [ TrueClass ] True.
       def delete(options = {})
-        raise Errors::ReadonlyDocument.new(self.class) if readonly?
         prepare_delete do
           unless options[:persist] == false
             if embedded?
@@ -86,7 +85,7 @@ module Mongoid
       #
       # @param [ Hash ] options The delete options.
       #
-      # @return [ true, false ] If the parent should be notified.
+      # @return [ true | false ] If the parent should be notified.
       def notifying_parent?(options = {})
         !options.delete(:suppress)
       end
@@ -102,6 +101,7 @@ module Mongoid
       #
       # @return [ Object ] The result of the block.
       def prepare_delete
+        raise Errors::ReadonlyDocument.new(self.class) if readonly?
         yield(self)
         freeze
         self.destroyed = true

data/lib/mongoid/persistable/destroyable.rb

@@ -14,7 +14,7 @@ module Mongoid
       #
       # @param [ Hash ] options Options to pass to destroy.
       #
-      # @return [ true, false ] True if successful, false if not.
+      # @return [ true | false ] True if successful, false if not.
       def destroy(options = nil)
         raise Errors::ReadonlyDocument.new(self.class) if readonly?
         self.flagged_for_destroy = true

data/lib/mongoid/persistable/savable.rb

@@ -14,7 +14,13 @@ module Mongoid
       #
       # @param [ Hash ] options Options to pass to the save.
       #
-      # @return [ true, false ] True is success, false if not.
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time. When this option is
+      #   false, none of the embedded documents will be touched. This option is
+      #   ignored when saving a new document, and the created_at and updated_at
+      #   will be set to the current time.
+      #
+      # @return [ true | false ] True if success, false if not.
       def save(options = {})
         if new_record?
           !insert(options).new_record?
@@ -31,10 +37,16 @@ module Mongoid
       #
       # @param [ Hash ] options Options to pass to the save.
       #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time. When this option is
+      #   false, none of the embedded documents will be touched.This option is
+      #   ignored when saving a new document, and the created_at and updated_at
+      #   will be set to the current time.
+      #
       # @raise [ Errors::Validations ] If validation failed.
       # @raise [ Errors::Callback ] If a callback returns false.
       #
-      # @return [ true, false ] True if validation passed.
+      # @return [ true | false ] True if validation passed.
       def save!(options = {})
         unless save(options)
           fail_due_to_validation! unless errors.empty?

data/lib/mongoid/persistable/unsettable.rb

@@ -13,8 +13,8 @@ module Mongoid
       # @example Unset the values.
       #   document.unset(:first_name, :last_name, :middle)
       #
-      # @param [ Array<String, Symbol> ] fields The names of the fields to
-      #   unset.
+      # @param [ [ String | Symbol | Array<String | Symbol>]... ] *fields
+      #   The names of the field(s) to unset.
       #
       # @return [ Document ] The document.
       def unset(*fields)