mongoid-ultra 9.0.0.0.alpha1

data/lib/mongoid/persistable/updatable.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Persistable
+
+    # Defines behavior for persistence operations that update existing
+    # documents.
+    module Updatable
+
+      # Update a single attribute and persist the entire document.
+      # This skips validation but fires the callbacks.
+      #
+      # @example Update the attribute.
+      #   person.update_attribute(:title, "Sir")
+      #
+      # @param [ Symbol | String ] name The name of the attribute.
+      # @param [ Object ] value The new value of the attribute.a
+      #
+      # @raise [ Errors::ReadonlyAttribute ] If the field cannot be changed due
+      #   to being flagged as read-only.
+      #
+      # @return [ true | false ] True if save was successful, false if not.
+      def update_attribute(name, value)
+        as_writable_attribute!(name, value) do |access|
+          normalized = name.to_s
+          process_attribute(normalized, value)
+          save(validate: false)
+        end
+      end
+
+      # Update the document attributes in the database.
+      #
+      # @example Update the document's attributes
+      #   document.update(:title => "Sir")
+      #
+      # @param [ Hash ] attributes The attributes to update.
+      #
+      # @return [ true | false ] True if validation passed, false if not.
+      def update(attributes = {})
+        assign_attributes(attributes)
+        save
+      end
+      alias :update_attributes :update
+
+      # Update the document attributes in the database and raise an error if
+      # validation failed.
+      #
+      # @example Update the document's attributes.
+      #   document.update!(:title => "Sir")
+      #
+      # @param [ Hash ] attributes The attributes to update.
+      #
+      # @raise [ Errors::Validations ] If validation failed.
+      # @raise [ Errors::Callbacks ] If a callback returns false.
+      #
+      # @return [ true | false ] True if validation passed.
+      def update!(attributes = {})
+        result = update_attributes(attributes)
+        unless result
+          fail_due_to_validation! unless errors.empty?
+          fail_due_to_callback!(:update_attributes!)
+        end
+        result
+      end
+      alias :update_attributes! :update!
+
+      private
+
+      # Initialize the atomic updates.
+      #
+      # @api private
+      #
+      # @example Initialize the atomic updates.
+      #   document.init_atomic_updates
+      #
+      # @return [ Array<Hash> ] The updates and conflicts.
+      def init_atomic_updates
+        updates = atomic_updates
+        conflicts = updates.delete(:conflicts) || {}
+        [ updates, conflicts ]
+      end
+
+      # Prepare the update for execution. Validates and runs callbacks, etc.
+      #
+      # @api private
+      #
+      # @example Prepare for update.
+      #   document.prepare_update do
+      #     collection.update(atomic_selector)
+      #   end
+      #
+      # @param [ Hash ] options The options.
+      #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time.
+      #
+      # @return [ true | false ] The result of the update.
+      def prepare_update(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
+        enforce_immutability_of_id_field!
+        return false if performing_validations?(options) &&
+          invalid?(options[:context] || :update)
+        process_flagged_destroys
+        update_children = cascadable_children(:update)
+        process_touch_option(options, update_children) do
+          run_all_callbacks_for_update(update_children) do
+            result = yield(self)
+            self.previously_new_record = false
+            post_process_persist(result, options)
+            true
+          end
+        end
+      end
+
+      # Update the document in the database.
+      #
+      # @example Update an existing document.
+      #   document.update
+      #
+      # @param [ Hash ] options Options to pass to update.
+      #
+      # @option options [ true | false ] :validate Whether or not to validate.
+      #
+      # @return [ true | false ] True if succeeded, false if not.
+      def update_document(options = {})
+        prepare_update(options) do
+          updates, conflicts = init_atomic_updates
+          unless updates.empty?
+            coll = collection(_root)
+            selector = atomic_selector
+            coll.find(selector).update_one(positionally(selector, updates), session: _session)
+
+            # The following code applies updates which would cause
+            # path conflicts in MongoDB, for example when changing attributes
+            # of foo.0.bars while adding another foo. Each conflicting update
+            # is applied using its own write.
+            #
+            # TODO: MONGOID-5026: reduce the number of writes performed by
+            # more intelligently combining the writes such that there are
+            # fewer conflicts.
+            conflicts.each_pair do |modifier, changes|
+
+              # Group the changes according to their root key which is
+              # the top-level association name.
+              # This handles at least the cases described in MONGOID-4982.
+              conflicting_change_groups = changes.group_by do |key, _|
+                key.split(".", 2).first
+              end.values
+
+              # Apply changes in batches. Pop one change from each
+              # field-conflict group round-robin until all changes
+              # have been applied.
+              while batched_changes = conflicting_change_groups.map(&:pop).compact.to_h.presence
+                coll.find(selector).update_one(
+                  positionally(selector, modifier => batched_changes),
+                  session: _session,
+                )
+              end
+            end
+          end
+        end
+      end
+
+      # If there is a touch option and it is false, this method will call the
+      # timeless method so that the updated_at attribute is not updated. It
+      # will call the timeless method on all of the cascadable children as
+      # well. Note that timeless is cleared in the before_update callback.
+      #
+      # @param [ Hash ] options The options.
+      # @param [ Array<Document> ] children The children that the :update
+      #   callbacks will be executed on.
+      #
+      # @option options [ true | false ] :touch Whether or not the updated_at
+      #   attribute will be updated with the current time.
+      def process_touch_option(options, children)
+        if options.fetch(:touch, true)
+          yield
+        else
+          timeless
+          children.each(&:timeless)
+          suppress_touch_callbacks { yield }
+        end
+      end
+
+      # Checks to see if the _id field has been modified. If it has, and if
+      # the document has already been persisted, this is an error. Otherwise,
+      # returns without side-effects.
+      #
+      # Note that if `Mongoid::Config.immutable_ids` is false, this will do
+      # nothing.
+      #
+      # @raise [ Errors::ImmutableAttribute ] if _id has changed, and document
+      #   has been persisted.
+      def enforce_immutability_of_id_field!
+        # special case here: we *do* allow the _id to be mutated if it was
+        # previously nil. This addresses an odd case exposed in
+        # has_one/proxy_spec.rb where `person.create_address` would
+        # (somehow?) create the address with a nil _id first, before then
+        # saving it *again* with the correct _id.
+
+        if _id_changed? && !_id_was.nil? && persisted?
+          if Mongoid::Config.immutable_ids
+            raise Errors::ImmutableAttribute.new(:_id, _id)
+          else
+            Mongoid::Warnings.warn_mutable_ids
+          end
+        end
+      end
+
+      # Consolidates all the callback invocations into a single place, to
+      # avoid cluttering the logic in #prepare_update.
+      #
+      # @param [ Array<Document> ] update_children The children that the
+      #   :update callbacks will be executed on.
+      def run_all_callbacks_for_update(update_children)
+        run_callbacks(:commit, with_children: true, skip_if: -> { in_transaction? }) do
+          run_callbacks(:save, with_children: false) do
+            run_callbacks(:update, with_children: false) do
+              run_callbacks(:persist_parent, with_children: false) do
+                _mongoid_run_child_callbacks(:save) do
+                  _mongoid_run_child_callbacks(:update, children: update_children) do
+                    yield
+                  end # _mongoid_run_child_callbacks :update
+                end # _mongoid_run_child_callbacks :save
+              end # :persist_parent
+            end # :update
+          end # :save
+        end # :commit
+      end
+
+    end
+  end
+end

data/lib/mongoid/persistable/upsertable.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Persistable
+
+    # Defines behavior for persistence operations that upsert documents.
+    module Upsertable
+
+      # Perform an upsert of the document. If the document does not exist in the
+      # database, then Mongo will insert a new one, otherwise the fields will get
+      # overwritten with new values on the existing document.
+      #
+      # If the replace option is true, unspecified attributes will be dropped,
+      # and if it is false, unspecified attributes will be maintained. The
+      # replace option defaults to false in Mongoid 9.
+      #
+      # @example Upsert the document.
+      #   document.upsert
+      #
+      # @example Upsert the document with replace.
+      #   document.upsert(replace: true)
+      #
+      # @example Upsert with extra attributes to use when inserting.
+      #   document.upsert(set_on_insert: { created_at: DateTime.now })
+      #
+      # @param [ Hash ] options The validation options.
+      #
+      # @option options [ true | false ] :validate Whether or not to validate.
+      # @option options [ true | false ] :replace Whether or not to replace
+      #   the document on upsert.
+      # @option options [ Hash ] :set_on_insert The attributes to include if
+      #   the document does not already exist.
+      #
+      # @return [ true ] True.
+      def upsert(options = {})
+        prepare_upsert(options) do
+          if options[:replace]
+            if options[:set_on_insert]
+              raise ArgumentError, "cannot specify :set_on_insert with `replace: true`"
+            end
+
+            collection.find(atomic_selector).replace_one(
+              as_attributes, upsert: true, session: _session)
+          else
+            attrs = { "$set" => as_attributes }
+            attrs["$setOnInsert"] = options[:set_on_insert] if options[:set_on_insert]
+
+            collection.find(atomic_selector).update_one(
+              attrs, upsert: true, session: _session)
+          end
+        end
+      end
+
+      private
+
+      # Prepare the upsert for execution.
+      #
+      # @api private
+      #
+      # @example Prepare the upsert
+      #   document.prepare_upsert do
+      #     collection.find(selector).update(as_document)
+      #   end
+      #
+      # @param [ Hash ] options The options hash.
+      #
+      # @option options [ true | false ] :validate Whether or not to validate.
+      #
+      # @return [ true | false ] If the operation succeeded.
+      def prepare_upsert(options = {})
+        raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
+        return false if performing_validations?(options) && invalid?(:upsert)
+        result = run_callbacks(:upsert) do
+          yield(self)
+          true
+        end
+        self.new_record = false
+        post_process_persist(result, options) and result
+      end
+    end
+  end
+end

data/lib/mongoid/persistable.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require "mongoid/persistable/creatable"
+require "mongoid/persistable/deletable"
+require "mongoid/persistable/destroyable"
+require "mongoid/persistable/incrementable"
+require "mongoid/persistable/logical"
+require "mongoid/persistable/maxable"
+require "mongoid/persistable/minable"
+require "mongoid/persistable/multipliable"
+require "mongoid/persistable/poppable"
+require "mongoid/persistable/pullable"
+require "mongoid/persistable/pushable"
+require "mongoid/persistable/renamable"
+require "mongoid/persistable/savable"
+require "mongoid/persistable/settable"
+require "mongoid/persistable/updatable"
+require "mongoid/persistable/upsertable"
+require "mongoid/persistable/unsettable"
+
+module Mongoid
+
+  # Contains general behavior for persistence operations.
+  module Persistable
+    extend ActiveSupport::Concern
+    include Creatable
+    include Deletable
+    include Destroyable
+    include Incrementable
+    include Logical
+    include Maxable
+    include Minable
+    include Multipliable
+    include Poppable
+    include Positional
+    include Pullable
+    include Pushable
+    include Renamable
+    include Savable
+    include Settable
+    include Updatable
+    include Upsertable
+    include Unsettable
+
+    # The atomic operations that deal with arrays or sets in the db.
+    LIST_OPERATIONS = [ "$addToSet", "$push", "$pull", "$pullAll" ].freeze
+
+    # Execute operations atomically (in a single database call) for everything
+    # that would happen inside the block. This method supports nesting further
+    # calls to atomically, which will behave according to the options described
+    # below.
+    #
+    # An option join_context can be given which, when true, will merge the
+    # operations declared by the given block with the atomically block wrapping
+    # the current invocation for the same document, if one exists. If this
+    # block or any other block sharing the same context raises before
+    # persisting, then all the operations of that context will not be
+    # persisted, and will also be reset in memory.
+    #
+    # When join_context is false, the given block of operations will be
+    # persisted independently of other contexts. Failures in other contexts will
+    # not affect this one, so long as this block was able to run and persist
+    # changes.
+    #
+    # The default value of join_context is set by the global configuration
+    # option join_contexts, whose own default is false.
+    #
+    # @example Execute the operations atomically.
+    #   document.atomically do
+    #     document.set(name: "Tool").inc(likes: 10)
+    #   end
+    #
+    # @example Execute some inner operations atomically, but independently from the outer operations.
+    #
+    #   document.atomically do
+    #     document.inc likes: 10
+    #     document.atomically join_context: false do
+    #       # The following is persisted to the database independently.
+    #       document.unset :origin
+    #     end
+    #     document.atomically join_context: true do
+    #       # The following is persisted along with the other outer operations.
+    #       document.inc member_count: 3
+    #     end
+    #     document.set name: "Tool"
+    #   end
+    #
+    # @param [ true | false ] join_context Join the context (i.e. merge
+    #   declared atomic operations) of the atomically block wrapping this one
+    #   for the same document, if one exists.
+    #
+    # @return [ true | false ] If the operation succeeded.
+    def atomically(join_context: nil)
+      join_context = Mongoid.join_contexts if join_context.nil?
+      call_depth = @atomic_depth ||= 0
+      has_own_context = call_depth.zero? || !join_context
+      @atomic_updates_to_execute_stack ||= []
+      _mongoid_push_atomic_context if has_own_context
+
+      if block_given?
+        @atomic_depth += 1
+        yield(self)
+        @atomic_depth -= 1
+      end
+
+      if has_own_context
+        persist_atomic_operations @atomic_context
+        _mongoid_remove_atomic_context_changes
+      end
+
+      true
+    rescue Exception => e
+      _mongoid_reset_atomic_context_changes! if has_own_context
+      raise e
+    ensure
+      _mongoid_pop_atomic_context if has_own_context
+
+      if call_depth.zero?
+        @atomic_depth = nil
+        @atomic_updates_to_execute_stack = nil
+      end
+    end
+
+    # Raise an error if validation failed.
+    #
+    # @example Raise the validation error.
+    #   Person.fail_due_to_validation!(person)
+    #
+    # @raise [ Errors::Validations ] The validation error.
+    def fail_due_to_validation!
+      raise Errors::Validations.new(self)
+    end
+
+    # Raise an error if a callback failed.
+    #
+    # @example Raise the callback error.
+    #   Person.fail_due_to_callback!(person, :create!)
+    #
+    # @param [ Symbol ] method The method being called.
+    #
+    # @raise [ Errors::Callback ] The callback error.
+    def fail_due_to_callback!(method)
+      raise Errors::Callback.new(self.class, method)
+    end
+
+    private
+
+    # Are we executing an atomically block on the current document?
+    #
+    # @api private
+    #
+    # @example Are we executing atomically?
+    #   document.executing_atomically?
+    #
+    # @return [ true | false ] If we are current executing atomically.
+    def executing_atomically?
+      !@atomic_updates_to_execute_stack.nil?
+    end
+
+    # Post process the persistence operation.
+    #
+    # @api private
+    #
+    # @example Post process the persistence operation.
+    #   document.post_process_persist(true)
+    #
+    # @param [ Object ] result The result of the operation.
+    # @param [ Hash ] options The options.
+    #
+    # @option options [ true | false ] :validate Whether or not to validate.
+    #
+    # @return [ true ] true.
+    def post_process_persist(result, options = {})
+      post_persist unless result == false
+      errors.clear unless performing_validations?(options)
+      if in_transaction?
+        Threaded.add_modified_document(_session, self)
+      end
+      true
+    end
+
+    # Prepare an atomic persistence operation. Yields an empty hash to be sent
+    # to the update.
+    #
+    # @api private
+    #
+    # @example Prepare the atomic operation.
+    #   document.prepare_atomic_operation do |coll, selector, opts|
+    #     ...
+    #   end
+    #
+    # @return [ Object ] The result of the operation.
+    def prepare_atomic_operation
+      raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
+      operations = yield({})
+      persist_or_delay_atomic_operation(operations)
+      self
+    end
+
+    # Process the atomic operations - this handles the common behavior of
+    # iterating through each op, getting the aliased field name, and removing
+    # appropriate dirty changes.
+    #
+    # @api private
+    #
+    # @example Process the atomic operations.
+    #   document.process_atomic_operations(pulls) do |field, value|
+    #     ...
+    #   end
+    #
+    # @param [ Hash ] operations The atomic operations.
+    #
+    # @return [ Hash ] The operations.
+    def process_atomic_operations(operations)
+      operations.each do |field, value|
+        access = database_field_name(field)
+        yield(access, value)
+        remove_change(access) unless executing_atomically?
+      end
+    end
+
+    # Remove the dirty changes for all fields changed in the current atomic
+    # context.
+    #
+    # @api private
+    #
+    # @example Remove the current atomic context's dirty changes.
+    #   document._mongoid_remove_atomic_context_changes
+    def _mongoid_remove_atomic_context_changes
+      return unless executing_atomically?
+      _mongoid_atomic_context_changed_fields.each { |f| remove_change f }
+    end
+
+    # Reset the attributes for all fields changed in the current atomic
+    # context.
+    #
+    # @api private
+    #
+    # @example Reset the current atomic context's changed attributes.
+    #   document._mongoid_reset_atomic_context_changes!
+    def _mongoid_reset_atomic_context_changes!
+      return unless executing_atomically?
+      _mongoid_atomic_context_changed_fields.each { |f| reset_attribute! f }
+    end
+
+    # Push a new atomic context onto the stack.
+    #
+    # @api private
+    #
+    # @example Push a new atomic context onto the stack.
+    #   document._mongoid_push_atomic_context
+    def _mongoid_push_atomic_context
+      return unless executing_atomically?
+      @atomic_context = {}
+      @atomic_updates_to_execute_stack << @atomic_context
+    end
+
+    # Pop an atomic context off the stack.
+    #
+    # @api private
+    #
+    # @example Pop an atomic context off the stack.
+    #   document._mongoid_pop_atomic_context
+    def _mongoid_pop_atomic_context
+      return unless executing_atomically?
+      @atomic_updates_to_execute_stack.pop
+      @atomic_context = @atomic_updates_to_execute_stack.last
+    end
+
+    # Return the current atomic context's changed fields.
+    #
+    # @api private
+    #
+    # @example Return the current atomic context's changed fields.
+    #   document._mongoid_atomic_context_changed_fields
+    #
+    # @return [ Array ] The changed fields.
+    def _mongoid_atomic_context_changed_fields
+      @atomic_context.values.flat_map(&:keys)
+    end
+
+    # If we are in an atomically block, add the operations to the delayed group,
+    # otherwise persist immediately.
+    #
+    # @api private
+    #
+    # @example Persist immediately or delay the operations.
+    #   document.persist_or_delay_atomic_operation(ops)
+    #
+    # @param [ Hash ] operation The operation.
+    def persist_or_delay_atomic_operation(operation)
+      if executing_atomically?
+        operation.each do |(name, hash)|
+          @atomic_context[name] ||= {}
+          @atomic_context[name].merge!(hash)
+        end
+      else
+        persist_atomic_operations(operation)
+      end
+    end
+
+    # Persist the atomic operations.
+    #
+    # @api private
+    #
+    # @example Persist the atomic operations.
+    #   persist_atomic_operations(ops)
+    #
+    # @param [ Hash ] operations The atomic operations.
+    def persist_atomic_operations(operations)
+      if persisted? && operations && !operations.empty?
+        selector = atomic_selector
+        _root.collection.find(selector).update_one(positionally(selector, operations), session: _session)
+      end
+    end
+  end
+end