paper_trail 5.2.3 → 11.0.0

data/lib/paper_trail/record_history.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   # Represents the history of a single record.
   # @api private
@@ -26,7 +28,7 @@ module PaperTrail
         @versions.select(primary_key).order(primary_key.asc)
       else
         @versions.
-          select([timestamp, primary_key]).
+          select([table[:created_at], primary_key]).
           order(@version_class.timestamp_sort_order)
       end
     end
@@ -45,13 +47,5 @@ module PaperTrail
     def table
       @version_class.arel_table
     end
-
-    # @return - Arel::Attribute - Attribute representing the timestamp column
-    #   of the version table, usually named `created_at` (the rails convention)
-    #   but not always.
-    # @api private
-    def timestamp
-      table[PaperTrail.timestamp_field]
-    end
   end
 end

data/lib/paper_trail/record_trail.rb

@@ -1,42 +1,18 @@
+# frozen_string_literal: true
+
+require "paper_trail/events/create"
+require "paper_trail/events/destroy"
+require "paper_trail/events/update"
+
 module PaperTrail
   # Represents the "paper trail" for a single record.
   class RecordTrail
+    RAILS_GTE_5_1 = ::ActiveRecord.gem_version >= ::Gem::Version.new("5.1.0.beta1")
+
     def initialize(record)
       @record = record
     end
 
-    # Utility method for reifying. Anything executed inside the block will
-    # appear like a new record.
-    def appear_as_new_record
-      @record.instance_eval {
-        alias :old_new_record? :new_record?
-        alias :new_record? :present?
-      }
-      yield
-      @record.instance_eval { alias :new_record? :old_new_record? }
-    end
-
-    def attributes_before_change
-      changed = @record.changed_attributes.select { |k, _v|
-        @record.class.column_names.include?(k)
-      }
-      @record.attributes.merge(changed)
-    end
-
-    def changed_and_not_ignored
-      ignore = @record.paper_trail_options[:ignore].dup
-      # Remove Hash arguments and then evaluate whether the attributes (the
-      # keys of the hash) should also get pushed into the collection.
-      ignore.delete_if do |obj|
-        obj.is_a?(Hash) &&
-          obj.each { |attr, condition|
-            ignore << attr if condition.respond_to?(:call) && condition.call(@record)
-          }
-      end
-      skip = @record.paper_trail_options[:skip]
-      @record.changed - ignore - skip
-    end
-
     # Invoked after rollbacks to ensure versions records are not created for
     # changes that never actually took place. Optimization: Use lazy `reset`
     # instead of eager `reload` because, in many use cases, the association will
@@ -51,43 +27,12 @@ module PaperTrail
       @record.send("#{@record.class.version_association_name}=", nil)
     end
 
-    # Determines whether it is appropriate to generate a new version
-    # instance. A timestamp-only update (e.g. only `updated_at` changed) is
-    # considered notable unless an ignored attribute was also changed.
-    def changed_notably?
-      if ignored_attr_has_changed?
-        timestamps = @record.send(:timestamp_attributes_for_update_in_model).map(&:to_s)
-        (notably_changed - timestamps).any?
-      else
-        notably_changed.any?
-      end
-    end
-
+    # Is PT enabled for this particular record?
     # @api private
-    def changes
-      notable_changes = @record.changes.delete_if { |k, _v|
-        !notably_changed.include?(k)
-      }
-      AttributeSerializers::ObjectChangesAttribute.
-        new(@record.class).
-        serialize(notable_changes)
-      notable_changes.to_hash
-    end
-
     def enabled?
-      PaperTrail.enabled? && PaperTrail.enabled_for_controller? && enabled_for_model?
-    end
-
-    def enabled_for_model?
-      @record.class.paper_trail.enabled?
-    end
-
-    # An attributed is "ignored" if it is listed in the `:ignore` option
-    # and/or the `:skip` option.  Returns true if an ignored attribute has
-    # changed.
-    def ignored_attr_has_changed?
-      ignored = @record.paper_trail_options[:ignore] + @record.paper_trail_options[:skip]
-      ignored.any? && (@record.changed & ignored).any?
+      PaperTrail.enabled? &&
+        PaperTrail.request.enabled? &&
+        PaperTrail.request.enabled_for_model?(@record.class)
     end
 
     # Returns true if this instance is the current, live one;
@@ -96,237 +41,143 @@ module PaperTrail
       source_version.nil?
     end
 
-    # @api private
-    def merge_metadata(data)
-      # First we merge the model-level metadata in `meta`.
-      @record.paper_trail_options[:meta].each do |k, v|
-        data[k] =
-          if v.respond_to?(:call)
-            v.call(@record)
-          elsif v.is_a?(Symbol) && @record.respond_to?(v, true)
-            # If it is an attribute that is changing in an existing object,
-            # be sure to grab the current version.
-            if @record.has_attribute?(v) &&
-                @record.send("#{v}_changed?".to_sym) &&
-                data[:event] != "create"
-              @record.send("#{v}_was".to_sym)
-            else
-              @record.send(v)
-            end
-          else
-            v
-          end
-      end
-
-      # Second we merge any extra data from the controller (if available).
-      data.merge(PaperTrail.controller_info || {})
-    end
-
     # Returns the object (not a Version) as it became next.
     # NOTE: if self (the item) was not reified from a version, i.e. it is the
     #  "live" item, we return nil.  Perhaps we should return self instead?
     def next_version
       subsequent_version = source_version.next
       subsequent_version ? subsequent_version.reify : @record.class.find(@record.id)
-    rescue # TODO: Rescue something more specific
+    rescue StandardError # TODO: Rescue something more specific
       nil
     end
 
-    def notably_changed
-      only = @record.paper_trail_options[:only].dup
-      # Remove Hash arguments and then evaluate whether the attributes (the
-      # keys of the hash) should also get pushed into the collection.
-      only.delete_if do |obj|
-        obj.is_a?(Hash) &&
-          obj.each { |attr, condition|
-            only << attr if condition.respond_to?(:call) && condition.call(@record)
-          }
-      end
-      only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
-    end
-
-    # Returns hash of attributes (with appropriate attributes serialized),
-    # omitting attributes to be skipped.
-    def object_attrs_for_paper_trail
-      attrs = attributes_before_change.except(*@record.paper_trail_options[:skip])
-      AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs)
-      attrs
-    end
-
     # Returns who put `@record` into its current state.
+    #
+    # @api public
     def originator
       (source_version || versions.last).try(:whodunnit)
     end
 
     # Returns the object (not a Version) as it was most recently.
+    #
+    # @api public
     def previous_version
       (source_version ? source_version.previous : versions.last).try(:reify)
     end
 
     def record_create
       return unless enabled?
-      data = {
-        event: @record.paper_trail_event || "create",
-        whodunnit: PaperTrail.whodunnit
-      }
-      if @record.respond_to?(:updated_at)
-        data[PaperTrail.timestamp_field] = @record.updated_at
-      end
-      if record_object_changes? && changed_notably?
-        data[:object_changes] = recordable_object_changes
-      end
-      add_transaction_id_to(data)
-      versions_assoc = @record.send(@record.class.versions_association_name)
-      version = versions_assoc.create! merge_metadata(data)
-      update_transaction_id(version)
-      save_associations(version)
-    end
 
-    def record_destroy
-      if enabled? && !@record.new_record?
-        data = {
-          item_id: @record.id,
-          item_type: @record.class.base_class.name,
-          event: @record.paper_trail_event || "destroy",
-          object: recordable_object,
-          whodunnit: PaperTrail.whodunnit
-        }
-        add_transaction_id_to(data)
-        version = @record.class.paper_trail.version_class.create(merge_metadata(data))
-        if version.errors.any?
-          log_version_errors(version, :destroy)
-        else
-          @record.send("#{@record.class.version_association_name}=", version)
-          @record.send(@record.class.versions_association_name).reset
-          update_transaction_id(version)
-          save_associations(version)
-        end
+      build_version_on_create(in_after_callback: true).tap do |version|
+        version.save!
+        # Because the version object was created using version_class.new instead
+        # of versions_assoc.build?, the association cache is unaware. So, we
+        # invalidate the `versions` association cache with `reset`.
+        versions.reset
       end
     end
 
-    # Returns a boolean indicating whether to store serialized version diffs
-    # in the `object_changes` column of the version record.
+    # PT-AT extends this method to add its transaction id.
+    #
     # @api private
-    def record_object_changes?
-      @record.paper_trail_options[:save_changes] &&
-        @record.class.paper_trail.version_class.column_names.include?("object_changes")
+    def data_for_create
+      {}
     end
 
-    def record_update(force)
-      if enabled? && (force || changed_notably?)
-        data = {
-          event: @record.paper_trail_event || "update",
-          object: recordable_object,
-          whodunnit: PaperTrail.whodunnit
-        }
-        if @record.respond_to?(:updated_at)
-          data[PaperTrail.timestamp_field] = @record.updated_at
-        end
-        if record_object_changes?
-          data[:object_changes] = recordable_object_changes
-        end
-        add_transaction_id_to(data)
-        versions_assoc = @record.send(@record.class.versions_association_name)
-        version = versions_assoc.create(merge_metadata(data))
-        if version.errors.any?
-          log_version_errors(version, :update)
-        else
-          update_transaction_id(version)
-          save_associations(version)
-        end
+    # `recording_order` is "after" or "before". See ModelConfig#on_destroy.
+    #
+    # @api private
+    # @return - The created version object, so that plugins can use it, e.g.
+    # paper_trail-association_tracking
+    def record_destroy(recording_order)
+      return unless enabled? && !@record.new_record?
+      in_after_callback = recording_order == "after"
+      event = Events::Destroy.new(@record, in_after_callback)
+
+      # Merge data from `Event` with data from PT-AT. We no longer use
+      # `data_for_destroy` but PT-AT still does.
+      data = event.data.merge(data_for_destroy)
+
+      version = @record.class.paper_trail.version_class.create(data)
+      if version.errors.any?
+        log_version_errors(version, :destroy)
+      else
+        assign_and_reset_version_association(version)
+        version
       end
     end
 
-    # Returns an object which can be assigned to the `object` attribute of a
-    # nascent version record. If the `object` column is a postgres `json`
-    # column, then a hash can be used in the assignment, otherwise the column
-    # is a `text` column, and we must perform the serialization here, using
-    # `PaperTrail.serializer`.
+    # PT-AT extends this method to add its transaction id.
+    #
     # @api private
-    def recordable_object
-      if @record.class.paper_trail.version_class.object_col_is_json?
-        object_attrs_for_paper_trail
+    def data_for_destroy
+      {}
+    end
+
+    # @api private
+    # @return - The created version object, so that plugins can use it, e.g.
+    # paper_trail-association_tracking
+    def record_update(force:, in_after_callback:, is_touch:)
+      return unless enabled?
+
+      version = build_version_on_update(
+        force: force,
+        in_after_callback: in_after_callback,
+        is_touch: is_touch
+      )
+      return unless version
+
+      if version.save
+        # Because the version object was created using version_class.new instead
+        # of versions_assoc.build?, the association cache is unaware. So, we
+        # invalidate the `versions` association cache with `reset`.
+        versions.reset
+        version
       else
-        PaperTrail.serializer.dump(object_attrs_for_paper_trail)
+        log_version_errors(version, :update)
       end
     end
 
-    # Returns an object which can be assigned to the `object_changes`
-    # attribute of a nascent version record. If the `object_changes` column is
-    # a postgres `json` column, then a hash can be used in the assignment,
-    # otherwise the column is a `text` column, and we must perform the
-    # serialization here, using `PaperTrail.serializer`.
+    # PT-AT extends this method to add its transaction id.
+    #
     # @api private
-    def recordable_object_changes
-      if @record.class.paper_trail.version_class.object_changes_col_is_json?
-        changes
+    def data_for_update
+      {}
+    end
+
+    # @api private
+    # @return - The created version object, so that plugins can use it, e.g.
+    # paper_trail-association_tracking
+    def record_update_columns(changes)
+      return unless enabled?
+      event = Events::Update.new(@record, false, false, changes)
+
+      # Merge data from `Event` with data from PT-AT. We no longer use
+      # `data_for_update_columns` but PT-AT still does.
+      data = event.data.merge(data_for_update_columns)
+
+      versions_assoc = @record.send(@record.class.versions_association_name)
+      version = versions_assoc.create(data)
+      if version.errors.any?
+        log_version_errors(version, :update)
       else
-        PaperTrail.serializer.dump(changes)
+        version
       end
     end
 
+    # PT-AT extends this method to add its transaction id.
+    #
+    # @api private
+    def data_for_update_columns
+      {}
+    end
+
     # Invoked via callback when a user attempts to persist a reified
     # `Version`.
     def reset_timestamp_attrs_for_update_if_needed
       return if live?
       @record.send(:timestamp_attributes_for_update_in_model).each do |column|
-        # ActiveRecord 4.2 deprecated `reset_column!` in favor of
-        # `restore_column!`.
-        if @record.respond_to?("restore_#{column}!")
-          @record.send("restore_#{column}!")
-        else
-          @record.send("reset_#{column}!")
-        end
-      end
-    end
-
-    # Saves associations if the join table for `VersionAssociation` exists.
-    def save_associations(version)
-      return unless PaperTrail.config.track_associations?
-      save_associations_belongs_to(version)
-      save_associations_habtm(version)
-    end
-
-    def save_associations_belongs_to(version)
-      @record.class.reflect_on_all_associations(:belongs_to).each do |assoc|
-        assoc_version_args = {
-          version_id: version.id,
-          foreign_key_name: assoc.foreign_key
-        }
-
-        if assoc.options[:polymorphic]
-          associated_record = @record.send(assoc.name) if @record.send(assoc.foreign_type)
-          if associated_record && associated_record.class.paper_trail.enabled?
-            assoc_version_args[:foreign_key_id] = associated_record.id
-          end
-        elsif assoc.klass.paper_trail.enabled?
-          assoc_version_args[:foreign_key_id] = @record.send(assoc.foreign_key)
-        end
-
-        if assoc_version_args.key?(:foreign_key_id)
-          PaperTrail::VersionAssociation.create(assoc_version_args)
-        end
-      end
-    end
-
-    def save_associations_habtm(version)
-      # Use the :added and :removed keys to extrapolate the HABTM associations
-      # to before any changes were made
-      @record.class.reflect_on_all_associations(:has_and_belongs_to_many).each do |a|
-        next unless
-          @record.class.paper_trail_save_join_tables.include?(a.name) ||
-              a.klass.paper_trail.enabled?
-        assoc_version_args = {
-          version_id: version.transaction_id,
-          foreign_key_name: a.name
-        }
-        assoc_ids =
-          @record.send(a.name).to_a.map(&:id) +
-          (@record.paper_trail_habtm.try(:[], a.name).try(:[], :removed) || []) -
-          (@record.paper_trail_habtm.try(:[], a.name).try(:[], :added) || [])
-        assoc_ids.each do |id|
-          PaperTrail::VersionAssociation.create(assoc_version_args.merge(foreign_key_id: id))
-        end
+        @record.send("restore_#{column}!")
       end
     end
 
@@ -342,26 +193,41 @@ module PaperTrail
       version
     end
 
-    # Mimics the `touch` method from `ActiveRecord::Persistence`, but also
-    # creates a version. A version is created regardless of options such as
-    # `:on`, `:if`, or `:unless`.
+    # Save, and create a version record regardless of options such as `:on`,
+    # `:if`, or `:unless`.
     #
-    # TODO: look into leveraging the `after_touch` callback from
-    # `ActiveRecord` to allow the regular `touch` method to generate a version
-    # as normal. May make sense to switch the `record_update` method to
-    # leverage an `after_update` callback anyways (likely for v4.0.0)
-    def touch_with_version(name = nil)
-      unless @record.persisted?
-        raise ActiveRecordError, "can not touch on a new record object"
+    # Arguments are passed to `save`.
+    #
+    # This is an "update" event. That is, we record the same data we would in
+    # the case of a normal AR `update`.
+    def save_with_version(*args)
+      ::PaperTrail.request(enabled: false) do
+        @record.save(*args)
+      end
+      record_update(force: true, in_after_callback: false, is_touch: false)
+    end
+
+    # Like the `update_column` method from `ActiveRecord::Persistence`, but also
+    # creates a version to record those changes.
+    # @api public
+    def update_column(name, value)
+      update_columns(name => value)
+    end
+
+    # Like the `update_columns` method from `ActiveRecord::Persistence`, but also
+    # creates a version to record those changes.
+    # @api public
+    def update_columns(attributes)
+      # `@record.update_columns` skips dirty-tracking, so we can't just use
+      # `@record.changes` or @record.saved_changes` from `ActiveModel::Dirty`.
+      # We need to build our own hash with the changes that will be made
+      # directly to the database.
+      changes = {}
+      attributes.each do |k, v|
+        changes[k] = [@record[k], v]
       end
-      attributes = @record.send :timestamp_attributes_for_update_in_model
-      attributes << name if name
-      current_time = @record.send :current_time_from_proper_timezone
-      attributes.each { |column|
-        @record.send(:write_attribute, column, current_time)
-      }
-      @record.record_update(true) unless will_record_after_update?
-      @record.save!(validate: false)
+      @record.update_columns(attributes)
+      record_update_columns(changes)
     end
 
     # Returns the object (not a Version) as it was at the given timestamp.
@@ -376,69 +242,53 @@ module PaperTrail
     # Returns the objects (not Versions) as they were between the given times.
     def versions_between(start_time, end_time)
       versions = send(@record.class.versions_association_name).between(start_time, end_time)
-      versions.collect { |version|
-        version_at(version.send(PaperTrail.timestamp_field))
-      }
+      versions.collect { |version| version_at(version.created_at) }
     end
 
-    # Executes the given method or block without creating a new version.
-    def without_versioning(method = nil)
-      paper_trail_was_enabled = enabled_for_model?
-      @record.class.paper_trail.disable
-      if method
-        if respond_to?(method)
-          public_send(method)
-        else
-          @record.send(method)
-        end
-      else
-        yield @record
-      end
-    ensure
-      @record.class.paper_trail.enable if paper_trail_was_enabled
+    private
+
+    # @api private
+    def assign_and_reset_version_association(version)
+      @record.send("#{@record.class.version_association_name}=", version)
+      @record.send(@record.class.versions_association_name).reset
     end
 
-    # Temporarily overwrites the value of whodunnit and then executes the
-    # provided block.
-    def whodunnit(value)
-      raise ArgumentError, "expected to receive a block" unless block_given?
-      current_whodunnit = PaperTrail.whodunnit
-      PaperTrail.whodunnit = value
-      yield @record
-    ensure
-      PaperTrail.whodunnit = current_whodunnit
+    # @api private
+    def build_version_on_create(in_after_callback:)
+      event = Events::Create.new(@record, in_after_callback)
+
+      # Merge data from `Event` with data from PT-AT. We no longer use
+      # `data_for_create` but PT-AT still does.
+      data = event.data.merge!(data_for_create)
+
+      # Pure `version_class.new` reduces memory usage compared to `versions_assoc.build`
+      @record.class.paper_trail.version_class.new(data)
     end
 
-    private
+    # @api private
+    def build_version_on_update(force:, in_after_callback:, is_touch:)
+      event = Events::Update.new(@record, in_after_callback, is_touch, nil)
+      return unless force || event.changed_notably?
+
+      # Merge data from `Event` with data from PT-AT. We no longer use
+      # `data_for_update` but PT-AT still does. To save memory, we use `merge!`
+      # instead of `merge`.
+      data = event.data.merge!(data_for_update)
 
-    def add_transaction_id_to(data)
-      return unless @record.class.paper_trail.version_class.column_names.include?("transaction_id")
-      data[:transaction_id] = PaperTrail.transaction_id
+      # Using `version_class.new` reduces memory usage compared to
+      # `versions_assoc.build`. It's a trade-off though. We have to clear
+      # the association cache (see `versions.reset`) and that could cause an
+      # additional query in certain applications.
+      @record.class.paper_trail.version_class.new(data)
     end
 
     def log_version_errors(version, action)
-      version.logger.warn(
-        "Unable to create version for #{action} of #{@record.class.name}" +
+      version.logger&.warn(
+        "Unable to create version for #{action} of #{@record.class.name}" \
           "##{@record.id}: " + version.errors.full_messages.join(", ")
       )
     end
 
-    # Returns true if `save` will cause `record_update`
-    # to be called via the `after_update` callback.
-    def will_record_after_update?
-      on = @record.paper_trail_options[:on]
-      on.nil? || on.include?(:update)
-    end
-
-    def update_transaction_id(version)
-      return unless @record.class.paper_trail.version_class.column_names.include?("transaction_id")
-      if PaperTrail.transaction? && PaperTrail.transaction_id.nil?
-        PaperTrail.transaction_id = version.id
-        version.transaction_id = version.id
-        version.save
-      end
-    end
-
     def version
       @record.public_send(@record.class.version_association_name)
     end