mongoid 8.1.9 → 9.0.0

data/lib/mongoid/touchable.rb

@@ -1,10 +1,38 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
+
+  # Mixin module which is included in Mongoid::Document to add "touch"
+  # functionality to update a document's timestamp(s) atomically.
   module Touchable
 
+    # Used to provide mixin functionality.
+    #
+    # @todo Refactor using ActiveSupport::Concern
     module InstanceMethods
 
+      # Suppresses the invocation of touch callbacks, for the class that
+      # includes this module, for the duration of the block.
+      #
+      # @example Suppress touch callbacks on Person documents:
+      #   person.suppress_touch_callbacks { ... }
+      #
+      # @api private
+      def suppress_touch_callbacks
+        Touchable.suppress_touch_callbacks(self.class.name) { yield }
+      end
+
+      # Queries whether touch callbacks are being suppressed for the class
+      # that includes this module.
+      #
+      # @return [ true | false ] Whether touch callbacks are suppressed.
+      #
+      # @api private
+      def touch_callbacks_suppressed?
+        Touchable.touch_callbacks_suppressed?(self.class.name)
+      end
+
       # Touch the document, in effect updating its updated_at timestamp and
       # optionally the provided field to the current time. If any belongs_to
       # associations exist with a touch option, they will be updated as well.
@@ -22,47 +50,93 @@ module Mongoid
       # @return [ true/false ] false if document is new_record otherwise true.
       def touch(field = nil)
         return false if _root.new_record?
-        current = Time.configured.now
-        field = database_field_name(field)
-        write_attribute(:updated_at, current) if respond_to?("updated_at=")
-        write_attribute(field, current) if field.present?
-
-        # If the document being touched is embedded, touch its parents
-        # all the way through the composition hierarchy to the root object,
-        # because when an embedded document is changed the write is actually
-        # performed by the composition root. See MONGOID-3468.
-        if _parent
-          # This will persist updated_at on this document as well as parents.
-          # TODO support passing the field name to the parent's touch method;
-          # I believe it should be read out of
-          # _association.inverse_association.options but inverse_association
-          # seems to not always/ever be set here. See MONGOID-5014.
-          _parent.touch
-
-          if field
-            # If we are told to also touch a field, perform a separate write
-            # for that field. See MONGOID-5136.
-            # In theory we should combine the writes, which would require
-            # passing the fields to be updated to the parents - MONGOID-5142.
-            sets = set_field_atomic_updates(field)
-            selector = atomic_selector
-            _root.collection.find(selector).update_one(positionally(selector, sets), session: _session)
-          end
-        else
-          # If the current document is not embedded, it is composition root
-          # and we need to persist the write here.
-          touches = touch_atomic_updates(field)
-          unless touches["$set"].blank?
-            selector = atomic_selector
-            _root.collection.find(selector).update_one(positionally(selector, touches), session: _session)
-          end
+
+        begin
+          touches = _gather_touch_updates(Time.current, field)
+          _root.send(:persist_atomic_operations, '$set' => touches) if touches.present?
+          _run_touch_callbacks_from_root
+        ensure
+          _clear_touch_updates(field)
         end
 
-        # Callbacks are invoked on the composition root first and on the
-        # leaf-most embedded document last.
-        run_callbacks(:touch)
         true
       end
+
+      # Recursively sets touchable fields on the current document and each of its
+      # parents, including the root node. Returns the combined atomic $set
+      # operations to be performed on the root document.
+      #
+      # @param [ Time ] now The timestamp used for synchronizing the touched time.
+      # @param [ Symbol ] field The name of an additional field to update.
+      #
+      # @return [ Hash<String, Time> ] The touch operations to perform as an atomic $set.
+      #
+      # @api private
+      def _gather_touch_updates(now, field = nil)
+        return if touch_callbacks_suppressed?
+
+        field = database_field_name(field)
+
+        write_attribute(:updated_at, now) if respond_to?("updated_at=")
+        write_attribute(field, now) if field
+
+        touches = _extract_touches_from_atomic_sets(field) || {}
+        touches.merge!(_parent._gather_touch_updates(now) || {}) if _touchable_parent?
+        touches
+      end
+
+      # Clears changes for the model caused by touch operation.
+      #
+      # @param [ Symbol ] field The name of an additional field to update.
+      #
+      # @api private
+      def _clear_touch_updates(field = nil)
+        remove_change(:updated_at)
+        remove_change(field) if field
+        _parent._clear_touch_updates if _touchable_parent?
+      end
+
+      # Recursively runs :touch callbacks for the document and its parents,
+      # beginning with the root document and cascading through each successive
+      # child document.
+      #
+      # @api private
+      def _run_touch_callbacks_from_root
+        return if touch_callbacks_suppressed?
+        _parent._run_touch_callbacks_from_root if _touchable_parent?
+        run_callbacks(:touch)
+      end
+
+      # Indicates whether the parent exists and is touchable.
+      #
+      # @api private
+      def _touchable_parent?
+        _parent && _association&.inverse_association&.touchable?
+      end
+
+      private
+
+      # Extract and remove the atomic updates for the touch operation(s)
+      # from the currently enqueued atomic $set operations.
+      #
+      # @param [ Symbol ] field The optional field.
+      #
+      # @return [ Hash ] The field-value pairs to update atomically.
+      #
+      # @api private
+      def _extract_touches_from_atomic_sets(field = nil)
+        updates = atomic_updates['$set']
+        return {} unless updates
+
+        touchable_keys = Set['updated_at', 'u_at']
+        touchable_keys << field.to_s if field.present?
+
+        updates.keys.each_with_object({}) do |key, touches|
+          if touchable_keys.include?(key.split('.').last)
+            touches[key] = updates.delete(key)
+          end
+        end
+      end
     end
 
     extend self
@@ -73,7 +147,7 @@ module Mongoid
     # @example Add the touchable.
     #   Model.define_touchable!(assoc)
     #
-    # @param [ Association ] association The association metadata.
+    # @param [ Mongoid::Association::Relatable ] association The association metadata.
     #
     # @return [ Class ] The model class.
     def define_touchable!(association)
@@ -82,12 +156,48 @@ module Mongoid
       association.inverse_class.tap do |klass|
         klass.after_save method_name
         klass.after_destroy method_name
-        klass.after_touch method_name
+
+        # Embedded docs handle touch updates recursively within
+        # the #touch method itself
+        klass.after_touch method_name unless association.embedded?
       end
     end
 
+    # Suppresses touch callbacks for the named class, for the duration of
+    # the associated block.
+    #
+    # @api private
+    def suppress_touch_callbacks(name)
+      save, touch_callback_statuses[name] = touch_callback_statuses[name], true
+      yield
+    ensure
+      touch_callback_statuses[name] = save
+    end
+
+    # Queries whether touch callbacks are being suppressed for the named
+    # class.
+    #
+    # @return [ true | false ] Whether touch callbacks are suppressed.
+    #
+    # @api private
+    def touch_callbacks_suppressed?(name)
+      touch_callback_statuses[name]
+    end
+
     private
 
+    # The key to use to store the active touch callback suppression statuses
+    SUPPRESS_TOUCH_CALLBACKS_KEY = "[mongoid]:suppress-touch-callbacks"
+
+    # Returns a hash to be used to store and query the various touch callback
+    # suppression statuses for different classes.
+    #
+    # @return [ Hash ] The hash that contains touch callback suppression
+    #   statuses
+    def touch_callback_statuses
+      Thread.current[SUPPRESS_TOUCH_CALLBACKS_KEY] ||= {}
+    end
+
     # Define the method that will get called for touching belongs_to
     # associations.
     #
@@ -98,7 +208,7 @@ module Mongoid
     #   Model.define_relation_touch_method(:band, :band_updated_at)
     #
     # @param [ Symbol ] name The name of the association.
-    # @param [ Association ] association The association metadata.
+    # @param [ Mongoid::Association::Relatable ] association The association metadata.
     #
     # @return [ Symbol ] The method name.
     def define_relation_touch_method(name, association)
@@ -108,19 +218,14 @@ module Mongoid
                            [ association.relation_class ]
                          end
 
-      relation_classes.each { |c| c.send(:include, InstanceMethods) }
       method_name = "touch_#{name}_after_create_or_destroy"
       association.inverse_class.class_eval do
         define_method(method_name) do
           without_autobuild do
-            if relation = __send__(name)
-              if association.touch_field
-                # Note that this looks up touch_field at runtime, rather than
-                # at method definition time.
-                relation.touch association.touch_field
-              else
-                relation.touch
-              end
+            if !touch_callbacks_suppressed? && relation = __send__(name)
+              # This looks up touch_field at runtime, rather than at method definition time.
+              # If touch_field is nil, it will only touch the default field (updated_at).
+              relation.touch(association.touch_field)
             end
           end
         end

data/lib/mongoid/traversable.rb

@@ -1,59 +1,106 @@
 # frozen_string_literal: true
 
-require "mongoid/fields/validators/macro"
+require 'mongoid/fields/validators/macro'
 
 module Mongoid
-
-  # Provides behavior around traversing the document graph.
+  # Mixin module included in Mongoid::Document to provide behavior
+  # around traversing the document graph.
   module Traversable
     extend ActiveSupport::Concern
-    # This code is extracted from ActiveSupport so that we do not depend on
-    # their private API that may change at any time.
-    # This code should be reviewed and maybe removed when implementing
-    # https://jira.mongodb.org/browse/MONGOID-5832
-    class << self
-      # @api private
-      def __redefine(owner, name, value)
-        if owner.singleton_class?
-          owner.redefine_method(name) { value }
-          owner.send(:public, name)
-        end
-        owner.redefine_singleton_method(name) { value }
-        owner.singleton_class.send(:public, name)
-        owner.redefine_singleton_method("#{name}=") do |new_value|
-          if owner.equal?(self)
-            value = new_value
-          else
-            ::Mongoid::Traversable.redefine(self, name, new_value)
-          end
-        end
-        owner.singleton_class.send(:public, "#{name}=")
+
+    # Class-level methods for the Traversable behavior.
+    module ClassMethods
+      # Determines if the document is a subclass of another document.
+      #
+      # @example Check if the document is a subclass.
+      #   Square.hereditary?
+      #
+      # @return [ true | false ] True if hereditary, false if not.
+      def hereditary?
+        !!(superclass < Mongoid::Document)
+      end
+
+      # When inheriting, we want to copy the fields from the parent class and
+      # set the on the child to start, mimicking the behavior of the old
+      # class_inheritable_accessor that was deprecated in Rails edge.
+      #
+      # @example Inherit from this class.
+      #   Person.inherited(Doctor)
+      #
+      # @param [ Class ] subclass The inheriting class.
+      #
+      # rubocop:disable Metrics/AbcSize
+      def inherited(subclass)
+        super
+        @_type = nil
+        subclass.aliased_fields = aliased_fields.dup
+        subclass.localized_fields = localized_fields.dup
+        subclass.fields = fields.dup
+        subclass.pre_processed_defaults = pre_processed_defaults.dup
+        subclass.post_processed_defaults = post_processed_defaults.dup
+        subclass._declared_scopes = Hash.new { |_hash, key| _declared_scopes[key] }
+        subclass.discriminator_value = subclass.name
+
+        # We need to do this here because the discriminator_value method is
+        # overridden in the subclass above.
+        subclass.include DiscriminatorRetrieval
+
+        # We only need the _type field if inheritance is in play, but need to
+        # add to the root class as well for backwards compatibility.
+        return if fields.key?(discriminator_key)
+
+        default_proc = -> { self.class.discriminator_value }
+        field(discriminator_key, default: default_proc, type: String)
       end
+      # rubocop:enable Metrics/AbcSize
     end
 
+    # `_parent` is intentionally not implemented via attr_accessor because
+    # of the need to use a double underscore for the instance variable.
+    # Associations automatically create backing variables prefixed with a
+    # single underscore, which would conflict with this accessor if a model
+    # were to declare a `parent` association.
+
+    # Retrieves the parent document of this document.
+    #
+    # @return [ Mongoid::Document | nil ] the parent document
+    #
+    # @api private
     def _parent
-      @__parent ||= nil
+      @__parent || nil
     end
 
-    def _parent=(p)
-      @__parent = p
+    # Sets the parent document of this document.
+    #
+    # @param [ Mongoid::Document | nil ] document the document to set as
+    #   the parent document.
+    #
+    # @returns [ Mongoid::Document ] The parent document.
+    #
+    # @api private
+    def _parent=(document)
+      @__parent = document
     end
 
     # Module used for prepending to the various discriminator_*= methods
     #
     # @api private
     module DiscriminatorAssignment
+      # Sets the discriminator key.
+      #
+      # @param [ String ] value The discriminator key to set.
+      #
+      # @api private
+      # rubocop:disable Metrics/AbcSize
       def discriminator_key=(value)
-        if hereditary?
-          raise Errors::InvalidDiscriminatorKeyTarget.new(self, self.superclass)
-        end
+        raise Errors::InvalidDiscriminatorKeyTarget.new(self, superclass) if hereditary?
 
         _mongoid_clear_types
 
         if value
           Mongoid::Fields::Validators::Macro.validate_field_name(self, value)
           value = value.to_s
-          ::Mongoid::Traversable.__redefine(self, 'discriminator_key', value)
+          super
         else
           # When discriminator key is set to nil, replace the class's definition
           # of the discriminator key reader (provided by class_attribute earlier)
@@ -67,14 +114,20 @@ module Mongoid
         # an existing field.
         # This condition also checks if the class has any descendants, because
         # if it doesn't then it doesn't need a discriminator key.
-        if !fields.has_key?(self.discriminator_key) && !descendants.empty?
-          default_proc = lambda { self.class.discriminator_value }
-          field(self.discriminator_key, default: default_proc, type: String)
-        end
+        return unless !fields.key?(discriminator_key) && !descendants.empty?
+
+        default_proc = -> { self.class.discriminator_value }
+        field(discriminator_key, default: default_proc, type: String)
       end
+      # rubocop:enable Metrics/AbcSize
 
+      # Returns the discriminator key.
+      #
+      # @return [ String ] The discriminator key.
+      #
+      # @api private
       def discriminator_value=(value)
-        value ||= self.name
+        value ||= name
         _mongoid_clear_types
         add_discriminator_mapping(value)
         @discriminator_value = value
@@ -90,10 +143,9 @@ module Mongoid
     #
     # @api private
     module DiscriminatorRetrieval
-
       # Get the name on the reading side if the discriminator_value is nil
       def discriminator_value
-        @discriminator_value || self.name
+        @discriminator_value || name
       end
     end
 
@@ -118,7 +170,7 @@ module Mongoid
       # @param [ Class ] The class the discriminator_value was set on
       #
       # @api private
-      def self.add_discriminator_mapping(value, klass=self)
+      def self.add_discriminator_mapping(value, klass = self)
         self.discriminator_mapping ||= {}
         self.discriminator_mapping[value] = klass
         superclass.add_discriminator_mapping(value, klass) if hereditary?
@@ -143,8 +195,17 @@ module Mongoid
     # @return [ Array<Document> ] All child documents in the hierarchy.
     #
     # @api private
-    def _children
-      @__children ||= collect_children
+    def _children(reset: false)
+      # See discussion above for the `_parent` method, as to why the variable
+      # here needs to have two underscores.
+      #
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      if reset
+        @__children = nil
+      else
+        @__children ||= collect_children
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
     end
 
     # Get all descendant +Documents+ of this +Document+ recursively.
@@ -157,8 +218,17 @@ module Mongoid
     # @return [ Array<Document> ] All descendant documents in the hierarchy.
     #
     # @api private
-    def _descendants
-      @__descendants ||= collect_descendants
+    def _descendants(reset: false)
+      # See discussion above for the `_parent` method, as to why the variable
+      # here needs to have two underscores.
+      #
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      if reset
+        @__descendants = nil
+      else
+        @__descendants ||= collect_descendants
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
     end
 
     # Collect all the children of this document.
@@ -167,16 +237,14 @@ module Mongoid
     #
     # @api private
     def collect_children
-      children = []
-      embedded_relations.each_pair do |name, association|
-        without_autobuild do
-          child = send(name)
-          if child
-            children += Array.wrap(child)
+      [].tap do |children|
+        embedded_relations.each_pair do |name, _association|
+          without_autobuild do
+            child = send(name)
+            children.concat(Array.wrap(child)) if child
           end
         end
       end
-      children
     end
 
     # Collect all the descendants of this document.
@@ -186,21 +254,15 @@ module Mongoid
     # @api private
     def collect_descendants
       children = []
-      to_expand = []
+      to_expand = _children
       expanded = {}
-      embedded_relations.each_pair do |name, association|
-        without_autobuild do
-          child = send(name)
-          if child
-            to_expand += Array.wrap(child)
-          end
-        end
-      end
+
       until to_expand.empty?
         expanding = to_expand
         to_expand = []
         expanding.each do |child|
           next if expanded[child]
+
           # Don't mark expanded if _id is nil, since documents are compared by
           # their _ids, multiple embedded documents with nil ids will compare
           # equally, and some documents will not be expanded.
@@ -209,6 +271,7 @@ module Mongoid
           to_expand += child._children
         end
       end
+
       children
     end
 
@@ -256,7 +319,7 @@ module Mongoid
     def remove_child(child)
       name = child.association_name
       if child.embedded_one?
-        self.attributes.delete(child._association.store_as)
+        attributes.delete(child._association.store_as)
         remove_ivar(name)
       else
         relation = send(name)
@@ -283,9 +346,9 @@ module Mongoid
     #
     # @api private
     def _reset_memoized_descendants!
-      _parent._reset_memoized_descendants! if _parent
-      @__children = nil
-      @__descendants = nil
+      _parent&._reset_memoized_descendants!
+      _children reset: true
+      _descendants reset: true
     end
 
     # Return the root document in the object graph. If the current document
@@ -297,7 +360,7 @@ module Mongoid
     # @return [ Document ] The root document in the hierarchy.
     def _root
       object = self
-      while (object._parent) do object = object._parent; end
+      object = object._parent while object._parent
       object
     end
 
@@ -310,63 +373,5 @@ module Mongoid
     def _root?
       _parent ? false : true
     end
-
-    module ClassMethods
-
-      # Determines if the document is a subclass of another document.
-      #
-      # @example Check if the document is a subclass.
-      #   Square.hereditary?
-      #
-      # @return [ true | false ] True if hereditary, false if not.
-      def hereditary?
-        !!(Mongoid::Document > superclass)
-      end
-
-      # Returns the root class of the STI tree that the current
-      # class participates in. If the class is not an STI subclass, this
-      # returns the class itself.
-      #
-      # @return [ Mongoid::Document ] the root of the STI tree
-      def root_class
-        root = self
-        root = root.superclass while root.hereditary?
-
-        root
-      end
-
-      # When inheriting, we want to copy the fields from the parent class and
-      # set the on the child to start, mimicking the behavior of the old
-      # class_inheritable_accessor that was deprecated in Rails edge.
-      #
-      # @example Inherit from this class.
-      #   Person.inherited(Doctor)
-      #
-      # @param [ Class ] subclass The inheriting class.
-      def inherited(subclass)
-        super
-        @_type = nil
-        subclass.aliased_fields = aliased_fields.dup
-        subclass.localized_fields = localized_fields.dup
-        subclass.fields = fields.dup
-        subclass.pre_processed_defaults = pre_processed_defaults.dup
-        subclass.post_processed_defaults = post_processed_defaults.dup
-        subclass._declared_scopes = Hash.new { |hash,key| self._declared_scopes[key] }
-        subclass.discriminator_value = subclass.name
-
-        # We need to do this here because the discriminator_value method is
-        # overridden in the subclass above.
-        class << subclass
-          include DiscriminatorRetrieval
-        end
-
-        # We only need the _type field if inheritance is in play, but need to
-        # add to the root class as well for backwards compatibility.
-        unless fields.has_key?(self.discriminator_key)
-          default_proc = lambda { self.class.discriminator_value }
-          field(self.discriminator_key, default: default_proc, type: String)
-        end
-      end
-    end
   end
 end

data/lib/mongoid/utils.rb

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
 module Mongoid
-
+  # Utility functions for Mongoid.
+  #
   # @api private
   module Utils
+    extend self
+
+    # A unique placeholder value that will never accidentally collide with
+    # valid values. This is useful as a default keyword argument value when
+    # you want the argument to be optional, but you also want to be able to
+    # recognize that the caller did not provide a value for it.
+    PLACEHOLDER = Object.new.freeze
+
+    # Asks if the given value is a placeholder or not.
+    #
+    # @param [ Object ] value the value to compare
+    #
+    # @return [ true | false ] if the value is a placeholder or not.
+    def placeholder?(value)
+      value == PLACEHOLDER
+    end
 
     # This function should be used if you need to measure time.
     # @example Calculate elapsed time.
@@ -15,8 +32,21 @@ module Mongoid
     # @see https://blog.dnsimple.com/2018/03/elapsed-time-with-ruby-the-right-way/
     #
     # @return [Float] seconds according to monotonic clock
-    module_function def monotonic_time
+    #
+    # @api private
+    def monotonic_time
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
+
+    # Returns true if the string is any of the following values: "1",
+    # "yes", "true", "on". Anything else is assumed to be false. Case is
+    # ignored, as are leading or trailing spaces.
+    #
+    # @param [ String ] string the string value to consider
+    #
+    # @return [ true | false ]
+    def truthy_string?(string)
+      %w[ 1 yes true on ].include?(string.strip.downcase)
+    end
   end
 end