paper_trail 9.2.0 → 14.0.0

data/lib/paper_trail/events/base.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Events
+    # We refer to times in the lifecycle of a record as "events". There are
+    # three events:
+    #
+    # - create
+    #   - `after_create` we call `RecordTrail#record_create`
+    # - update
+    #   - `after_update` we call `RecordTrail#record_update`
+    #   - `after_touch` we call `RecordTrail#record_update`
+    #   - `RecordTrail#save_with_version` calls `RecordTrail#record_update`
+    #   - `RecordTrail#update_columns` is also referred to as an update, though
+    #     it uses `RecordTrail#record_update_columns` rather than
+    #     `RecordTrail#record_update`
+    # - destroy
+    #   - `before_destroy` or `after_destroy` we call `RecordTrail#record_destroy`
+    #
+    # The value inserted into the `event` column of the versions table can also
+    # be overridden by the user, with `paper_trail_event`.
+    #
+    # @api private
+    class Base
+      E_FORBIDDEN_METADATA_KEY = <<-EOS.squish
+        Forbidden metadata key: %s. As of PT 14, the following metadata keys are
+        forbidden: %s
+      EOS
+      FORBIDDEN_METADATA_KEYS = %i[
+        created_at
+        id
+        item_id
+        item_subtype
+        item_type
+        updated_at
+      ].freeze
+
+      # @api private
+      def initialize(record, in_after_callback)
+        @record = record
+        @in_after_callback = in_after_callback
+      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.
+      #
+      # @api private
+      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
+
+      private
+
+      # @api private
+      def assert_metadatum_key_is_permitted(key)
+        return unless FORBIDDEN_METADATA_KEYS.include?(key.to_sym)
+        raise PaperTrail::InvalidOption,
+          format(E_FORBIDDEN_METADATA_KEY, key, FORBIDDEN_METADATA_KEYS)
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      #
+      # @api private
+      def attribute_changed_in_latest_version?(attr_name)
+        if @in_after_callback
+          @record.saved_change_to_attribute?(attr_name.to_s)
+        else
+          @record.attribute_changed?(attr_name.to_s)
+        end
+      end
+
+      # @api private
+      def nonskipped_attributes_before_change(is_touch)
+        record_attributes = @record.attributes.except(*@record.paper_trail_options[:skip])
+        record_attributes.each_key do |k|
+          if @record.class.column_names.include?(k)
+            record_attributes[k] = attribute_in_previous_version(k, is_touch)
+          end
+        end
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      #
+      # Event can be any of the three (create, update, destroy).
+      #
+      # @api private
+      def attribute_in_previous_version(attr_name, is_touch)
+        if @in_after_callback && !is_touch
+          # For most events, we want the original value of the attribute, before
+          # the last save.
+          @record.attribute_before_last_save(attr_name.to_s)
+        else
+          # We are either performing a `record_destroy` or a
+          # `record_update(is_touch: true)`.
+          @record.attribute_in_database(attr_name.to_s)
+        end
+      end
+
+      # @api private
+      def calculated_ignored_array
+        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
+      end
+
+      # @api private
+      def changed_and_not_ignored
+        skip = @record.paper_trail_options[:skip]
+        (changed_in_latest_version - calculated_ignored_array) - skip
+      end
+
+      # @api private
+      def changed_in_latest_version
+        # Memoized to reduce memory usage
+        @changed_in_latest_version ||= changes_in_latest_version.keys
+      end
+
+      # Memoized to reduce memory usage
+      #
+      # @api private
+      def changes_in_latest_version
+        @changes_in_latest_version ||= load_changes_in_latest_version
+      end
+
+      # @api private
+      def evaluate_only
+        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
+      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.
+      #
+      # @api private
+      def ignored_attr_has_changed?
+        ignored = calculated_ignored_array + @record.paper_trail_options[:skip]
+        ignored.any? && (changed_in_latest_version & ignored).any?
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      #
+      # @api private
+      def load_changes_in_latest_version
+        if @in_after_callback
+          @record.saved_changes
+        else
+          @record.changes
+        end
+      end
+
+      # PT 10 has a new optional column, `item_subtype`
+      #
+      # @api private
+      def merge_item_subtype_into(data)
+        if @record.class.paper_trail.version_class.columns_hash.key?("item_subtype")
+          data.merge!(item_subtype: @record.class.name)
+        end
+      end
+
+      # Updates `data` from the model's `meta` option and from `controller_info`.
+      # Metadata is always recorded; that means all three events (create, update,
+      # destroy) and `update_columns`.
+      #
+      # @api private
+      def merge_metadata_into(data)
+        merge_metadata_from_model_into(data)
+        merge_metadata_from_controller_into(data)
+      end
+
+      # Updates `data` from `controller_info`.
+      #
+      # @api private
+      def merge_metadata_from_controller_into(data)
+        metadata = PaperTrail.request.controller_info || {}
+        metadata.keys.each { |k| assert_metadatum_key_is_permitted(k) }
+        data.merge(metadata)
+      end
+
+      # Updates `data` from the model's `meta` option.
+      #
+      # @api private
+      def merge_metadata_from_model_into(data)
+        @record.paper_trail_options[:meta].each do |k, v|
+          assert_metadatum_key_is_permitted(k)
+          data[k] = model_metadatum(v, data[:event])
+        end
+      end
+
+      # Given a `value` from the model's `meta` option, returns an object to be
+      # persisted. The `value` can be a simple scalar value, but it can also
+      # be a symbol that names a model method, or even a Proc.
+      #
+      # @api private
+      def model_metadatum(value, event)
+        if value.respond_to?(:call)
+          value.call(@record)
+        elsif value.is_a?(Symbol) && @record.respond_to?(value, true)
+          metadatum_from_model_method(event, value)
+        else
+          value
+        end
+      end
+
+      # The model method can either be an attribute or a non-attribute method.
+      #
+      # If it is an attribute that is changing in an existing object,
+      # be sure to grab the correct version.
+      #
+      # @api private
+      def metadatum_from_model_method(event, method)
+        if event != "create" &&
+            @record.has_attribute?(method) &&
+            attribute_changed_in_latest_version?(method)
+          attribute_in_previous_version(method, false)
+        else
+          @record.send(method)
+        end
+      end
+
+      # @api private
+      def notable_changes
+        changes_in_latest_version.delete_if { |k, _v|
+          notably_changed.exclude?(k)
+        }
+      end
+
+      # @api private
+      def notably_changed
+        # Memoized to reduce memory usage
+        @notably_changed ||= begin
+          only = evaluate_only
+          cani = changed_and_not_ignored
+          only.empty? ? cani : (cani & only)
+        end
+      end
+
+      # Returns hash of attributes (with appropriate attributes serialized),
+      # omitting attributes to be skipped.
+      #
+      # @api private
+      def object_attrs_for_paper_trail(is_touch)
+        attrs = nonskipped_attributes_before_change(is_touch)
+        AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs)
+        attrs
+      end
+
+      # @api private
+      def prepare_object_changes(changes)
+        changes = serialize_object_changes(changes)
+        recordable_object_changes(changes)
+      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`.
+      #
+      # @api private
+      # @param changes HashWithIndifferentAccess
+      def recordable_object_changes(changes)
+        if PaperTrail.config.object_changes_adapter.respond_to?(:diff)
+          # We'd like to avoid the `to_hash` here, because it increases memory
+          # usage, but that would be a breaking change because
+          # `object_changes_adapter` expects a plain `Hash`, not a
+          # `HashWithIndifferentAccess`.
+          changes = PaperTrail.config.object_changes_adapter.diff(changes.to_hash)
+        end
+
+        if @record.class.paper_trail.version_class.object_changes_col_is_json?
+          changes
+        else
+          PaperTrail.serializer.dump(changes)
+        end
+      end
+
+      # Returns a boolean indicating whether to store serialized version diffs
+      # in the `object_changes` column of the version record.
+      #
+      # @api private
+      def record_object_changes?
+        @record.class.paper_trail.version_class.column_names.include?("object_changes")
+      end
+
+      # Returns a boolean indicating whether to store the original object during save.
+      #
+      # @api private
+      def record_object?
+        @record.class.paper_trail.version_class.column_names.include?("object")
+      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`.
+      #
+      # @api private
+      def recordable_object(is_touch)
+        if @record.class.paper_trail.version_class.object_col_is_json?
+          object_attrs_for_paper_trail(is_touch)
+        else
+          PaperTrail.serializer.dump(object_attrs_for_paper_trail(is_touch))
+        end
+      end
+
+      # @api private
+      def serialize_object_changes(changes)
+        AttributeSerializers::ObjectChangesAttribute.
+          new(@record.class).
+          serialize(changes)
+
+        # We'd like to convert this `HashWithIndifferentAccess` to a plain
+        # `Hash`, but we don't, to save memory.
+        changes
+      end
+    end
+  end
+end

data/lib/paper_trail/events/create.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "paper_trail/events/base"
+
+module PaperTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Create < Base
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item: @record,
+          event: @record.paper_trail_event || "create",
+          whodunnit: PaperTrail.request.whodunnit
+        }
+        if @record.respond_to?(:updated_at)
+          data[:created_at] = @record.updated_at
+        end
+        if record_object_changes? && changed_notably?
+          changes = notable_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+    end
+  end
+end

data/lib/paper_trail/events/destroy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "paper_trail/events/base"
+
+module PaperTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Destroy < Base
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item_id: @record.id,
+          item_type: @record.class.base_class.name,
+          event: @record.paper_trail_event || "destroy",
+          whodunnit: PaperTrail.request.whodunnit
+        }
+        if record_object?
+          data[:object] = recordable_object(false)
+        end
+        if record_object_changes?
+          data[:object_changes] = prepare_object_changes(notable_changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+
+      private
+
+      # Rails' implementation (eg. `@record.saved_changes`) returns nothing on
+      # destroy, so we have to build the hash we want.
+      #
+      # @override
+      def changes_in_latest_version
+        @record.attributes.transform_values { |value| [value, nil] }
+      end
+    end
+  end
+end

data/lib/paper_trail/events/update.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "paper_trail/events/base"
+
+module PaperTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Update < Base
+      # - is_touch - [boolean] - Used in the two situations that are touch-like:
+      #   - `after_touch` we call `RecordTrail#record_update`
+      # - force_changes - [Hash] - Only used by `RecordTrail#update_columns`,
+      #   because there dirty-tracking is off, so it has to track its own changes.
+      #
+      # @api private
+      def initialize(record, in_after_callback, is_touch, force_changes)
+        super(record, in_after_callback)
+        @is_touch = is_touch
+        @force_changes = force_changes
+      end
+
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item: @record,
+          event: @record.paper_trail_event || "update",
+          whodunnit: PaperTrail.request.whodunnit
+        }
+        if record_object?
+          data[:object] = recordable_object(@is_touch)
+        end
+        merge_object_changes_into(data)
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+
+      # If it is a touch event, and changed are empty, it is assumed to be
+      # implicit `touch` mutation, and will a version is created.
+      #
+      # See https://github.com/rails/rails/commit/dcb825902d79d0f6baba956f7c6ec5767611353e
+      #
+      # @api private
+      def changed_notably?
+        if @is_touch && changes_in_latest_version.empty?
+          true
+        else
+          super
+        end
+      end
+
+      private
+
+      # @api private
+      def merge_object_changes_into(data)
+        if record_object_changes?
+          changes = @force_changes.nil? ? notable_changes : @force_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+      end
+
+      # `touch` cannot record `object_changes` because rails' `touch` does not
+      # perform dirty-tracking. Specifically, methods from `Dirty`, like
+      # `saved_changes`, return the same values before and after `touch`.
+      #
+      # See https://github.com/rails/rails/issues/33429
+      #
+      # @api private
+      def record_object_changes?
+        !@is_touch && super
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/active_record.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
-# This file only needs to be loaded if the gem is being used outside of Rails,
-# since otherwise the model(s) will get loaded in via the `Rails::Engine`.
+# Either ActiveRecord has already been loaded by the Lazy Load Hook in our
+# Railtie, or else we load it now.
+require "active_record"
+::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
+
+# Now we can load the parts of PT that depend on AR.
+require "paper_trail/has_paper_trail"
+require "paper_trail/reifier"
 require "paper_trail/frameworks/active_record/models/paper_trail/version"
+ActiveRecord::Base.include PaperTrail::Model

data/lib/paper_trail/frameworks/rails/controller.rb

@@ -25,9 +25,7 @@ module PaperTrail
       # @api public
       def user_for_paper_trail
         return unless defined?(current_user)
-        ActiveSupport::VERSION::MAJOR >= 4 ? current_user.try!(:id) : current_user.try(:id)
-      rescue NoMethodError
-        current_user
+        current_user.try(:id) || current_user
       end
 
       # Returns any information about the controller or request that you
@@ -103,9 +101,3 @@ module PaperTrail
     end
   end
 end
-
-if defined?(::ActionController)
-  ::ActiveSupport.on_load(:action_controller) do
-    include ::PaperTrail::Rails::Controller
-  end
-end

data/lib/paper_trail/frameworks/rails/railtie.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Represents code to load within Rails framework. See documentation in
+  # `railties/lib/rails/railtie.rb`.
+  # @api private
+  class Railtie < ::Rails::Railtie
+    # PaperTrail only has one initializer.
+    #
+    # We specify `before: "load_config_initializers"` to ensure that the PT
+    # initializer happens before "app initializers" (those defined in
+    # the app's `config/initalizers`).
+    initializer "paper_trail", before: "load_config_initializers" do
+      # `on_load` is a "lazy load hook". It "declares a block that will be
+      # executed when a Rails component is fully loaded". (See
+      # `active_support/lazy_load_hooks.rb`)
+      ActiveSupport.on_load(:action_controller) do
+        require "paper_trail/frameworks/rails/controller"
+
+        # Mix our extensions into `ActionController::Base`, which is `self`
+        # because of the `class_eval` in `lazy_load_hooks.rb`.
+        include PaperTrail::Rails::Controller
+      end
+
+      ActiveSupport.on_load(:active_record) do
+        require "paper_trail/frameworks/active_record"
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/rails.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-require "paper_trail/frameworks/rails/controller"
-require "paper_trail/frameworks/rails/engine"
+require "paper_trail/frameworks/rails/railtie"

data/lib/paper_trail/has_paper_trail.rb

@@ -12,7 +12,7 @@ module PaperTrail
   # `.paper_trail` and `#paper_trail`.
   module Model
     def self.included(base)
-      base.send :extend, ClassMethods
+      base.extend ClassMethods
     end
 
     # :nodoc:
@@ -23,18 +23,18 @@ module PaperTrail
       # Options:
       #
       # - :on - The events to track (optional; defaults to all of them). Set
-      #   to an array of `:create`, `:update`, `:destroy` as desired.
-      # - :class_name - The name of a custom Version class.  This class should
-      #   inherit from `PaperTrail::Version`.
+      #   to an array of `:create`, `:update`, `:destroy` and `:touch` as desired.
+      # - :class_name (deprecated) - The name of a custom Version class that
+      #   includes `PaperTrail::VersionConcern`.
       # - :ignore - An array of attributes for which a new `Version` will not be
-      #   created if only they change. It can also aceept a Hash as an
+      #   created if only they change. It can also accept a Hash as an
       #   argument where the key is the attribute to ignore (a `String` or
       #   `Symbol`), which will only be ignored if the value is a `Proc` which
       #   returns truthily.
       # - :if, :unless - Procs that allow to specify conditions when to save
       #   versions for an object.
       # - :only - Inverse of `ignore`. A new `Version` will be created only
-      #   for these attributes if supplied it can also aceept a Hash as an
+      #   for these attributes if supplied it can also accept a Hash as an
       #   argument where the key is the attribute to track (a `String` or
       #   `Symbol`), which will only be counted if the value is a `Proc` which
       #   returns truthily.
@@ -47,22 +47,25 @@ module PaperTrail
       #   are called with `self`, i.e. the model with the paper trail).  See
       #   `PaperTrail::Controller.info_for_paper_trail` for how to store data
       #   from the controller.
-      # - :versions - The name to use for the versions association.  Default
-      #   is `:versions`.
+      # - :versions - Either,
+      #   - A String (deprecated) - The name to use for the versions
+      #     association.  Default is `:versions`.
+      #   - A Hash - options passed to `has_many`, plus `name:` and `scope:`.
       # - :version - The name to use for the method which returns the version
       #   the instance was reified from. Default is `:version`.
-      # - :save_changes - Whether or not to save changes to the object_changes
-      #   column if it exists. Default is true
-      # - :join_tables - If the model has a has_and_belongs_to_many relation
-      #   with an unpapertrailed model, passing the name of the association to
-      #   the join_tables option will paper trail the join table but not save
-      #   the other model, allowing reification of the association but with the
-      #   other models latest state (if the other model is paper trailed, this
-      #   option does nothing)
+      #
+      # Plugins like the experimental `paper_trail-association_tracking` gem
+      # may accept additional options.
+      #
+      # You can define a default set of options via the configurable
+      # `PaperTrail.config.has_paper_trail_defaults` hash in your applications
+      # initializer. The hash can contain any of the following options and will
+      # provide an overridable default for all models.
       #
       # @api public
       def has_paper_trail(options = {})
-        paper_trail.setup(options)
+        defaults = PaperTrail.config.has_paper_trail_defaults
+        paper_trail.setup(defaults.merge(options))
       end
 
       # @api public