paper_trail 5.2.3 → 11.0.0

data/lib/paper_trail/model_config.rb

@@ -1,4 +1,4 @@
-require "active_support/core_ext"
+# frozen_string_literal: true
 
 module PaperTrail
   # Configures an ActiveRecord model, mostly at application boot time, but also
@@ -6,77 +6,120 @@ module PaperTrail
   class ModelConfig
     E_CANNOT_RECORD_AFTER_DESTROY = <<-STR.strip_heredoc.freeze
       paper_trail.on_destroy(:after) is incompatible with ActiveRecord's
-      belongs_to_required_by_default and has no effect. Please use :before
+      belongs_to_required_by_default. Use on_destroy(:before)
       or disable belongs_to_required_by_default.
     STR
+    E_HPT_ABSTRACT_CLASS = <<~STR.squish.freeze
+      An application model (%s) has been configured to use PaperTrail (via
+      `has_paper_trail`), but the version model it has been told to use (%s) is
+      an `abstract_class`. This could happen when an advanced feature called
+      Custom Version Classes (http://bit.ly/2G4ch0G) is misconfigured. When all
+      version classes are custom, PaperTrail::Version is configured to be an
+      `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.
+      The hash you pass to `versions:` is now passed directly to `has_many`.
+    STR
+    DPR_CLASS_NAME_OPTION = <<~STR.squish
+      Passing Version class name as `has_paper_trail class_name: %{class_name}`
+      is deprecated. Use `has_paper_trail versions: {class_name: %{class_name}}`
+      instead. The hash you pass to `versions:` is now passed directly to `has_many`.
+    STR
 
     def initialize(model_class)
       @model_class = model_class
     end
 
-    # Switches PaperTrail off for this class.
-    def disable
-      ::PaperTrail.enabled_for_model(@model_class, false)
-    end
-
-    # Switches PaperTrail on for this class.
-    def enable
-      ::PaperTrail.enabled_for_model(@model_class, true)
-    end
-
-    def enabled?
-      return false unless @model_class.include?(::PaperTrail::Model::InstanceMethods)
-      ::PaperTrail.enabled_for_model?(@model_class)
-    end
-
     # Adds a callback that records a version after a "create" event.
+    #
+    # @api public
     def on_create
-      @model_class.after_create :record_create, if: ->(m) { m.paper_trail.save_version? }
+      @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
     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)
+      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?
-        ::ActiveSupport::Deprecation.warn(E_CANNOT_RECORD_AFTER_DESTROY)
+        raise E_CANNOT_RECORD_AFTER_DESTROY
       end
 
-      @model_class.send "#{recording_order}_destroy", :record_destroy,
-        if: ->(m) { m.paper_trail.save_version? }
+      @model_class.send(
+        "#{recording_order}_destroy",
+        lambda do |r|
+          return unless r.paper_trail.save_version?
+          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
     end
 
     # Adds a callback that records a version after an "update" event.
+    #
+    # @api public
     def on_update
-      @model_class.before_save :reset_timestamp_attrs_for_update_if_needed!, on: :update
-      @model_class.after_update :record_update, if: ->(m) { m.paper_trail.save_version? }
-      @model_class.after_update :clear_version_instance!
+      @model_class.before_save { |r|
+        r.paper_trail.reset_timestamp_attrs_for_update_if_needed
+      }
+      @model_class.after_update { |r|
+        if r.paper_trail.save_version?
+          r.paper_trail.record_update(
+            force: false,
+            in_after_callback: true,
+            is_touch: false
+          )
+        end
+      }
+      @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
     end
 
+    # Adds a callback that records a version after a "touch" event.
+    # @api public
+    def on_touch
+      @model_class.after_touch { |r|
+        r.paper_trail.record_update(
+          force: true,
+          in_after_callback: true,
+          is_touch: true
+        )
+      }
+    end
+
     # Set up `@model_class` for PaperTrail. Installs callbacks, associations,
     # "class attributes", instance methods, and more.
     # @api private
     def setup(options = {})
-      options[:on] ||= [:create, :update, :destroy]
+      options[:on] ||= %i[create update destroy touch]
       options[:on] = Array(options[:on]) # Support single symbol
       @model_class.send :include, ::PaperTrail::Model::InstanceMethods
-      if ::ActiveRecord::VERSION::STRING < "4.2"
-        @model_class.send :extend, AttributeSerializers::LegacyActiveRecordShim
-      end
       setup_options(options)
       setup_associations(options)
-      setup_transaction_callbacks
+      check_presence_of_item_subtype_column(options)
+      @model_class.after_rollback { paper_trail.clear_rolled_back_versions }
       setup_callbacks_from_options options[:on]
-      setup_callbacks_for_habtm options[:join_tables]
     end
 
     def version_class
@@ -85,60 +128,100 @@ module PaperTrail
 
     private
 
-    def active_record_gem_version
-      Gem::Version.new(ActiveRecord::VERSION::STRING)
+    # 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)
+      end
     end
 
     def cannot_record_after_destroy?
-      Gem::Version.new(ActiveRecord::VERSION::STRING).release >= Gem::Version.new("5") &&
-        ::ActiveRecord::Base.belongs_to_required_by_default
+      ::ActiveRecord::Base.belongs_to_required_by_default
+    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)
     end
 
-    def habtm_assocs_not_skipped
-      @model_class.reflect_on_all_associations(:has_and_belongs_to_many).
-        reject { |a| @model_class.paper_trail_options[:skip].include?(a.name.to_s) }
+    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(
+          format(
+            DPR_CLASS_NAME_OPTION,
+            class_name: options[:class_name].inspect
+          ),
+          caller(1)
+        )
+        options[:versions][:class_name] = options[:class_name]
+      end
+      @model_class.version_class_name = options[:versions][:class_name] || "PaperTrail::Version"
+      assert_concrete_activerecord_class(@model_class.version_class_name)
+    end
+
+    def check_versions_association_name(options)
+      # @api private - versions_association_name
+      @model_class.class_attribute :versions_association_name
+      @model_class.versions_association_name = options[:versions][:name] || :versions
+    end
+
+    def define_has_many_versions(options)
+      options = ensure_versions_option_is_hash(options)
+      check_version_class_name(options)
+      check_versions_association_name(options)
+      scope = get_versions_scope(options)
+      @model_class.has_many(
+        @model_class.versions_association_name,
+        scope,
+        class_name: @model_class.version_class_name,
+        as: :item,
+        **options[:versions].except(:name, :scope)
+      )
+    end
+
+    def ensure_versions_option_is_hash(options)
+      unless options[:versions].is_a?(Hash)
+        if options[:versions]
+          ::ActiveSupport::Deprecation.warn(
+            format(
+              DPR_PASSING_ASSOC_NAME_DIRECTLY_TO_VERSIONS_OPTION,
+              versions_name: options[:versions].inspect
+            ),
+            caller(1)
+          )
+        end
+        options[:versions] = {
+          name: options[:versions]
+        }
+      end
+      options
+    end
+
+    def get_versions_scope(options)
+      options[:versions][:scope] || -> { order(model.timestamp_sort_order) }
     end
 
     def setup_associations(options)
+      # @api private - version_association_name
       @model_class.class_attribute :version_association_name
       @model_class.version_association_name = options[:version] || :version
 
       # The version this instance was reified from.
+      # @api public
       @model_class.send :attr_accessor, @model_class.version_association_name
 
-      @model_class.class_attribute :version_class_name
-      @model_class.version_class_name = options[:class_name] || "PaperTrail::Version"
-
-      @model_class.class_attribute :versions_association_name
-      @model_class.versions_association_name = options[:versions] || :versions
-
+      # @api public - paper_trail_event
       @model_class.send :attr_accessor, :paper_trail_event
 
-      # In rails 4, the `has_many` syntax for specifying order uses a lambda.
-      if ::ActiveRecord::VERSION::MAJOR >= 4
-        @model_class.has_many(
-          @model_class.versions_association_name,
-          -> { order(model.timestamp_sort_order) },
-          class_name: @model_class.version_class_name,
-          as: :item
-        )
-      else
-        @model_class.has_many(
-          @model_class.versions_association_name,
-          class_name: @model_class.version_class_name,
-          as: :item,
-          order: @model_class.paper_trail.version_class.timestamp_sort_order
-        )
-      end
-    end
-
-    # Adds callbacks to record changes to habtm associations such that on save
-    # the previous version of the association (if changed) can be interpreted.
-    def setup_callbacks_for_habtm(join_tables)
-      @model_class.send :attr_accessor, :paper_trail_habtm
-      @model_class.class_attribute :paper_trail_save_join_tables
-      @model_class.paper_trail_save_join_tables = Array.wrap(join_tables)
-      habtm_assocs_not_skipped.each(&method(:setup_habtm_change_callbacks))
+      define_has_many_versions(options)
     end
 
     def setup_callbacks_from_options(options_on = [])
@@ -147,23 +230,15 @@ module PaperTrail
       end
     end
 
-    def setup_habtm_change_callbacks(assoc)
-      assoc_name = assoc.name
-      %w(add remove).each do |verb|
-        @model_class.send(:"before_#{verb}_for_#{assoc_name}").send(
-          :<<,
-          lambda do |*args|
-            update_habtm_state(assoc_name, :"before_#{verb}", args[-2], args.last)
-          end
-        )
-      end
-    end
-
     def setup_options(options)
+      # @api public - paper_trail_options - Let's encourage plugins to use eg.
+      # `paper_trail_options[:versions][:class_name]` rather than
+      # `version_class_name` because the former is documented and the latter is
+      # not.
       @model_class.class_attribute :paper_trail_options
       @model_class.paper_trail_options = options.dup
 
-      [:ignore, :skip, :only].each do |k|
+      %i[ignore skip only].each do |k|
         @model_class.paper_trail_options[k] = [@model_class.paper_trail_options[k]].
           flatten.
           compact.
@@ -171,33 +246,6 @@ module PaperTrail
       end
 
       @model_class.paper_trail_options[:meta] ||= {}
-      if @model_class.paper_trail_options[:save_changes].nil?
-        @model_class.paper_trail_options[:save_changes] = true
-      end
-    end
-
-    # Reset the transaction id when the transaction is closed.
-    def setup_transaction_callbacks
-      @model_class.after_commit { PaperTrail.clear_transaction_id }
-      @model_class.after_rollback { PaperTrail.clear_transaction_id }
-      @model_class.after_rollback { paper_trail.clear_rolled_back_versions }
-    end
-
-    def update_habtm_state(name, callback, model, assoc)
-      model.paper_trail_habtm ||= {}
-      model.paper_trail_habtm[name] ||= { removed: [], added: [] }
-      state = model.paper_trail_habtm[name]
-      assoc_id = assoc.id
-      case callback
-      when :before_add
-        state[:added] |= [assoc_id]
-        state[:removed] -= [assoc_id]
-      when :before_remove
-        state[:removed] |= [assoc_id]
-        state[:added] -= [assoc_id]
-      else
-        raise "Invalid callback: #{callback}"
-      end
     end
   end
 end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_object` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereObject
+        # - 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
+          column = @version_model_class.columns_hash["object"]
+          raise "where_object can't be called without an object column" unless column
+
+          case column.type
+          when :jsonb
+            jsonb
+          when :json
+            json
+          else
+            text
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          predicates = []
+          values = []
+          @attributes.each do |field, value|
+            predicates.push "object->>? = ?"
+            values.concat([field, value.to_s])
+          end
+          sql = predicates.join(" and ")
+          @version_model_class.where(sql, *values)
+        end
+
+        # @api private
+        def jsonb
+          @version_model_class.where("object @> ?", @attributes.to_json)
+        end
+
+        # @api private
+        def text
+          arel_field = @version_model_class.arel_table[:object]
+          where_conditions = @attributes.map { |field, value|
+            ::PaperTrail.serializer.where_object_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
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_object_changes` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereObjectChanges
+        # - 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
+
+          # Currently, this `deep_dup` is necessary because the `jsonb` branch
+          # modifies `@attributes`, and that would be a nasty suprise for
+          # consumers of this class.
+          # TODO: Stop modifying `@attributes`, then remove `deep_dup`.
+          @attributes = attributes.deep_dup
+        end
+
+        # @api private
+        def execute
+          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
+          when :jsonb
+            jsonb
+          when :json
+            json
+          else
+            text
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          predicates = []
+          values = []
+          @attributes.each do |field, value|
+            predicates.push(
+              "((object_changes->>? ILIKE ?) OR (object_changes->>? ILIKE ?))"
+            )
+            values.concat([field, "[#{value.to_json},%", field, "[%,#{value.to_json}]%"])
+          end
+          sql = predicates.join(" and ")
+          @version_model_class.where(sql, *values)
+        end
+
+        # @api private
+        def jsonb
+          @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
+end