paper_trail 11.1.0 → 15.2.0

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

@@ -0,0 +1,34 @@
+# 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 |app|
+      # `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
+
+      if Gem::Version.new(::Rails::VERSION::STRING) >= Gem::Version.new("7.1")
+        app.deprecators[:paper_trail] = PaperTrail.deprecator
+      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

@@ -53,6 +53,10 @@ module PaperTrail
       #   - 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`.
+      # - :synchronize_version_creation_timestamp - By default, paper trail
+      #   sets the `created_at` field for a new Version equal to the `updated_at`
+      #   column of the model being updated. If you instead want `created_at` to
+      #   populate with the current timestamp, set this option to `false`.
       #
       # Plugins like the experimental `paper_trail-association_tracking` gem
       # may accept additional options.

data/lib/paper_trail/model_config.rb

@@ -18,11 +18,6 @@ module PaperTrail
       `abstract_class`. This is fine, but all application models must be
       configured to use concrete (not abstract) version models.
     STR
-    E_MODEL_LIMIT_REQUIRES_ITEM_SUBTYPE = <<~STR.squish.freeze
-      To use PaperTrail's per-model limit in your %s model, you must have an
-      item_subtype column in your versions table. See documentation sections
-      2.e.1 Per-model limit, and 4.b.1 The optional item_subtype column.
-    STR
     DPR_PASSING_ASSOC_NAME_DIRECTLY_TO_VERSIONS_OPTION = <<~STR.squish
       Passing versions association name as `has_paper_trail versions: %{versions_name}`
       is deprecated. Use `has_paper_trail versions: {name: %{versions_name}}` instead.
@@ -45,22 +40,14 @@ module PaperTrail
       @model_class.after_create { |r|
         r.paper_trail.record_create if r.paper_trail.save_version?
       }
-      return if @model_class.paper_trail_options[:on].include?(:create)
-      @model_class.paper_trail_options[:on] << :create
+      append_option_uniquely(:on, :create)
     end
 
     # Adds a callback that records a version before or after a "destroy" event.
     #
     # @api public
     def on_destroy(recording_order = "before")
-      unless %w[after before].include?(recording_order.to_s)
-        raise ArgumentError, 'recording order can only be "after" or "before"'
-      end
-
-      if recording_order.to_s == "after" && cannot_record_after_destroy?
-        raise E_CANNOT_RECORD_AFTER_DESTROY
-      end
-
+      assert_valid_recording_order_for_on_destroy(recording_order)
       @model_class.send(
         "#{recording_order}_destroy",
         lambda do |r|
@@ -68,9 +55,7 @@ module PaperTrail
           r.paper_trail.record_destroy(recording_order)
         end
       )
-
-      return if @model_class.paper_trail_options[:on].include?(:destroy)
-      @model_class.paper_trail_options[:on] << :destroy
+      append_option_uniquely(:on, :destroy)
     end
 
     # Adds a callback that records a version after an "update" event.
@@ -92,19 +77,28 @@ module PaperTrail
       @model_class.after_update { |r|
         r.paper_trail.clear_version_instance
       }
-      return if @model_class.paper_trail_options[:on].include?(:update)
-      @model_class.paper_trail_options[:on] << :update
+      append_option_uniquely(:on, :update)
     end
 
     # Adds a callback that records a version after a "touch" event.
+    #
+    # Rails < 6.0 (no longer supported by PT) had a bug where dirty-tracking
+    # did not occur during a `touch`.
+    # (https://github.com/rails/rails/issues/33429) See also:
+    # https://github.com/paper-trail-gem/paper_trail/issues/1121
+    # https://github.com/paper-trail-gem/paper_trail/issues/1161
+    # https://github.com/paper-trail-gem/paper_trail/pull/1285
+    #
     # @api public
     def on_touch
       @model_class.after_touch { |r|
-        r.paper_trail.record_update(
-          force: true,
-          in_after_callback: true,
-          is_touch: true
-        )
+        if r.paper_trail.save_version?
+          r.paper_trail.record_update(
+            force: false,
+            in_after_callback: true,
+            is_touch: true
+          )
+        end
       }
     end
 
@@ -117,44 +111,52 @@ module PaperTrail
       @model_class.send :include, ::PaperTrail::Model::InstanceMethods
       setup_options(options)
       setup_associations(options)
-      check_presence_of_item_subtype_column(options)
       @model_class.after_rollback { paper_trail.clear_rolled_back_versions }
       setup_callbacks_from_options options[:on]
     end
 
+    # @api private
     def version_class
-      @_version_class ||= @model_class.version_class_name.constantize
+      @version_class ||= @model_class.version_class_name.constantize
     end
 
     private
 
+    # @api private
+    def append_option_uniquely(option, value)
+      collection = @model_class.paper_trail_options.fetch(option)
+      return if collection.include?(value)
+      collection << value
+    end
+
     # Raises an error if the provided class is an `abstract_class`.
     # @api private
     def assert_concrete_activerecord_class(class_name)
       if class_name.constantize.abstract_class?
-        raise format(E_HPT_ABSTRACT_CLASS, @model_class, class_name)
+        raise Error, format(E_HPT_ABSTRACT_CLASS, @model_class, class_name)
       end
     end
 
-    def cannot_record_after_destroy?
-      ::ActiveRecord::Base.belongs_to_required_by_default
+    # @api private
+    def assert_valid_recording_order_for_on_destroy(recording_order)
+      unless %w[after before].include?(recording_order.to_s)
+        raise ArgumentError, 'recording order can only be "after" or "before"'
+      end
+
+      if recording_order.to_s == "after" && cannot_record_after_destroy?
+        raise Error, E_CANNOT_RECORD_AFTER_DESTROY
+      end
     end
 
-    # Some options require the presence of the `item_subtype` column. Currently
-    # only `limit`, but in the future there may be others.
-    #
-    # @api private
-    def check_presence_of_item_subtype_column(options)
-      return unless options.key?(:limit)
-      return if version_class.item_subtype_column_present?
-      raise format(E_MODEL_LIMIT_REQUIRES_ITEM_SUBTYPE, @model_class.name)
+    def cannot_record_after_destroy?
+      ::ActiveRecord::Base.belongs_to_required_by_default
     end
 
     def check_version_class_name(options)
       # @api private - `version_class_name`
       @model_class.class_attribute :version_class_name
       if options[:class_name]
-        ::ActiveSupport::Deprecation.warn(
+        PaperTrail.deprecator.warn(
           format(
             DPR_CLASS_NAME_OPTION,
             class_name: options[:class_name].inspect
@@ -190,7 +192,7 @@ module PaperTrail
     def ensure_versions_option_is_hash(options)
       unless options[:versions].is_a?(Hash)
         if options[:versions]
-          ::ActiveSupport::Deprecation.warn(
+          PaperTrail.deprecator.warn(
             format(
               DPR_PASSING_ASSOC_NAME_DIRECTLY_TO_VERSIONS_OPTION,
               versions_name: options[:versions].inspect
@@ -205,6 +207,14 @@ module PaperTrail
       options
     end
 
+    # Process an `ignore`, `skip`, or `only` option.
+    def event_attribute_option(option_name)
+      [@model_class.paper_trail_options[option_name]].
+        flatten.
+        compact.
+        map { |attr| attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s }
+    end
+
     def get_versions_scope(options)
       options[:versions][:scope] || -> { order(model.timestamp_sort_order) }
     end
@@ -239,12 +249,8 @@ module PaperTrail
       @model_class.paper_trail_options = options.dup
 
       %i[ignore skip only].each do |k|
-        @model_class.paper_trail_options[k] = [@model_class.paper_trail_options[k]].
-          flatten.
-          compact.
-          map { |attr| attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s }
+        @model_class.paper_trail_options[k] = event_attribute_option(k)
       end
-
       @model_class.paper_trail_options[:meta] ||= {}
     end
   end

data/lib/paper_trail/queries/versions/where_attribute_changes.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_attribute_changes` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereAttributeChanges
+        # - version_model_class - The class that VersionConcern was mixed into.
+        # - attribute - An attribute that changed. See the public API
+        #   documentation for details.
+        # @api private
+        def initialize(version_model_class, attribute)
+          @version_model_class = version_model_class
+          @attribute = attribute
+        end
+
+        # @api private
+        def execute
+          if PaperTrail.config.object_changes_adapter.respond_to?(:where_attribute_changes)
+            return PaperTrail.config.object_changes_adapter.where_attribute_changes(
+              @version_model_class, @attribute
+            )
+          end
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
+          when :jsonb, :json
+            json
+          else
+            raise UnsupportedColumnType.new(
+              method: "where_attribute_changes",
+              expected: "json or jsonb",
+              actual: column_type
+            )
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          sql = "object_changes -> ? IS NOT NULL"
+
+          @version_model_class.where(sql, @attribute)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/queries/versions/where_object.rb

@@ -19,7 +19,7 @@ module PaperTrail
         # @api private
         def execute
           column = @version_model_class.columns_hash["object"]
-          raise "where_object can't be called without an object column" unless column
+          raise Error, "where_object requires an object column" unless column
 
           case column.type
           when :jsonb

data/lib/paper_trail/queries/versions/where_object_changes.rb

@@ -15,7 +15,7 @@ module PaperTrail
           @version_model_class = version_model_class
 
           # Currently, this `deep_dup` is necessary because the `jsonb` branch
-          # modifies `@attributes`, and that would be a nasty suprise for
+          # modifies `@attributes`, and that would be a nasty surprise for
           # consumers of this class.
           # TODO: Stop modifying `@attributes`, then remove `deep_dup`.
           @attributes = attributes.deep_dup
@@ -23,18 +23,23 @@ module PaperTrail
 
         # @api private
         def execute
-          if PaperTrail.config.object_changes_adapter&.respond_to?(:where_object_changes)
+          if PaperTrail.config.object_changes_adapter.respond_to?(:where_object_changes)
             return PaperTrail.config.object_changes_adapter.where_object_changes(
               @version_model_class, @attributes
             )
           end
-          case @version_model_class.columns_hash["object_changes"].type
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
           when :jsonb
             jsonb
           when :json
             json
           else
-            text
+            raise UnsupportedColumnType.new(
+              method: "where_object_changes",
+              expected: "json or jsonb",
+              actual: column_type
+            )
           end
         end
 
@@ -59,16 +64,6 @@ module PaperTrail
           @attributes.each { |field, value| @attributes[field] = [value] }
           @version_model_class.where("object_changes @> ?", @attributes.to_json)
         end
-
-        # @api private
-        def text
-          arel_field = @version_model_class.arel_table[:object_changes]
-          where_conditions = @attributes.map { |field, value|
-            ::PaperTrail.serializer.where_object_changes_condition(arel_field, field, value)
-          }
-          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
-          @version_model_class.where(where_conditions)
-        end
       end
     end
   end

data/lib/paper_trail/queries/versions/where_object_changes_from.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_object_changes_from` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereObjectChangesFrom
+        # - version_model_class - The class that VersionConcern was mixed into.
+        # - attributes - A `Hash` of attributes and values. See the public API
+        #   documentation for details.
+        # @api private
+        def initialize(version_model_class, attributes)
+          @version_model_class = version_model_class
+          @attributes = attributes
+        end
+
+        # @api private
+        def execute
+          if PaperTrail.config.object_changes_adapter.respond_to?(:where_object_changes_from)
+            return PaperTrail.config.object_changes_adapter.where_object_changes_from(
+              @version_model_class, @attributes
+            )
+          end
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
+          when :jsonb, :json
+            json
+          else
+            raise UnsupportedColumnType.new(
+              method: "where_object_changes_from",
+              expected: "json or jsonb",
+              actual: column_type
+            )
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          predicates = []
+          values = []
+          @attributes.each do |field, value|
+            predicates.push(
+              "(object_changes->>? ILIKE ?)"
+            )
+            values.concat([field, "[#{value.to_json},%"])
+          end
+          sql = predicates.join(" and ")
+          @version_model_class.where(sql, *values)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/queries/versions/where_object_changes_to.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_object_changes_to` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereObjectChangesTo
+        # - version_model_class - The class that VersionConcern was mixed into.
+        # - attributes - A `Hash` of attributes and values. See the public API
+        #   documentation for details.
+        # @api private
+        def initialize(version_model_class, attributes)
+          @version_model_class = version_model_class
+          @attributes = attributes
+        end
+
+        # @api private
+        def execute
+          if PaperTrail.config.object_changes_adapter.respond_to?(:where_object_changes_to)
+            return PaperTrail.config.object_changes_adapter.where_object_changes_to(
+              @version_model_class, @attributes
+            )
+          end
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
+          when :jsonb, :json
+            json
+          else
+            raise UnsupportedColumnType.new(
+              method: "where_object_changes_to",
+              expected: "json or jsonb",
+              actual: column_type
+            )
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          predicates = []
+          values = []
+          @attributes.each do |field, value|
+            predicates.push(
+              "(object_changes->>? ILIKE ?)"
+            )
+            values.concat([field, "[%#{value.to_json}]"])
+          end
+          sql = predicates.join(" and ")
+          @version_model_class.where(sql, *values)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/record_trail.rb

@@ -7,8 +7,6 @@ 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
@@ -27,14 +25,6 @@ module PaperTrail
       @record.send("#{@record.class.version_association_name}=", nil)
     end
 
-    # Is PT enabled for this particular record?
-    # @api private
-    def enabled?
-      PaperTrail.enabled? &&
-        PaperTrail.request.enabled? &&
-        PaperTrail.request.enabled_for_model?(@record.class)
-    end
-
     # Returns true if this instance is the current, live one;
     # returns false if this instance came from a previous version.
     def live?
@@ -77,13 +67,6 @@ module PaperTrail
       end
     end
 
-    # PT-AT extends this method to add its transaction id.
-    #
-    # @api private
-    def data_for_create
-      {}
-    end
-
     # `recording_order` is "after" or "before". See ModelConfig#on_destroy.
     #
     # @api private
@@ -107,14 +90,12 @@ module PaperTrail
       end
     end
 
-    # PT-AT extends this method to add its transaction id.
-    #
-    # @api private
-    def data_for_destroy
-      {}
-    end
-
     # @api private
+    # @param force [boolean] Insert a `Version` even if `@record` has not
+    #   `changed_notably?`.
+    # @param in_after_callback [boolean] True when called from an `after_update`
+    #   or `after_touch` callback.
+    # @param is_touch [boolean] True when called from an `after_touch` callback.
     # @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:)
@@ -138,40 +119,6 @@ module PaperTrail
       end
     end
 
-    # PT-AT extends this method to add its transaction id.
-    #
-    # @api private
-    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
-        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
@@ -196,15 +143,17 @@ module PaperTrail
     # Save, and create a version record regardless of options such as `:on`,
     # `:if`, or `:unless`.
     #
-    # Arguments are passed to `save`.
+    # `in_after_callback`: Indicates if this method is being called within an
+    #                      `after` callback. Defaults to `false`.
+    # `options`: Optional arguments 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)
+    def save_with_version(in_after_callback: false, **options)
       ::PaperTrail.request(enabled: false) do
-        @record.save(*args)
+        @record.save(**options)
       end
-      record_update(force: true, in_after_callback: false, is_touch: false)
+      record_update(force: true, in_after_callback: in_after_callback, is_touch: false)
     end
 
     # Like the `update_column` method from `ActiveRecord::Persistence`, but also
@@ -269,11 +218,23 @@ module PaperTrail
     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?
+      data = event.data
+
+      # Copy the (recently set) `updated_at` from the record to the `created_at`
+      # of the `Version`. Without this feature, these two timestamps would
+      # differ by a few milliseconds. To some people, it seems a little
+      # unnatural to tamper with creation timestamps in this way. But, this
+      # feature has existed for a long time, almost a decade now, and some users
+      # may rely on it now.
+      if @record.respond_to?(:updated_at) &&
+          @record.paper_trail_options[:synchronize_version_creation_timestamp] != false
+        data[:created_at] = @record.updated_at
+      end
 
       # 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)
+      data.merge!(data_for_update)
 
       # Using `version_class.new` reduces memory usage compared to
       # `versions_assoc.build`. It's a trade-off though. We have to clear
@@ -282,13 +243,69 @@ module PaperTrail
       @record.class.paper_trail.version_class.new(data)
     end
 
+    # PT-AT extends this method to add its transaction id.
+    #
+    # @api public
+    def data_for_create
+      {}
+    end
+
+    # PT-AT extends this method to add its transaction id.
+    #
+    # @api public
+    def data_for_destroy
+      {}
+    end
+
+    # PT-AT extends this method to add its transaction id.
+    #
+    # @api public
+    def data_for_update
+      {}
+    end
+
+    # PT-AT extends this method to add its transaction id.
+    #
+    # @api public
+    def data_for_update_columns
+      {}
+    end
+
+    # Is PT enabled for this particular record?
+    # @api private
+    def enabled?
+      PaperTrail.enabled? &&
+        PaperTrail.request.enabled? &&
+        PaperTrail.request.enabled_for_model?(@record.class)
+    end
+
     def log_version_errors(version, action)
       version.logger&.warn(
         "Unable to create version for #{action} of #{@record.class.name}" \
-          "##{@record.id}: " + version.errors.full_messages.join(", ")
+        "##{@record.id}: " + version.errors.full_messages.join(", ")
       )
     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?
+      data = Events::Update.new(@record, false, false, changes).data
+
+      # Merge data from `Event` with data from PT-AT. We no longer use
+      # `data_for_update_columns` but PT-AT still does.
+      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
+        version
+      end
+    end
+
     def version
       @record.public_send(@record.class.version_association_name)
     end