paper_trail 5.2.3 → 11.0.0

data/lib/paper_trail/attribute_serializers/attribute_serializer_factory.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "paper_trail/type_serializers/postgres_array_serializer"
+
+module PaperTrail
+  module AttributeSerializers
+    # Values returned by some Active Record serializers are
+    # not suited for writing JSON to a text column. This factory
+    # replaces certain default Active Record serializers
+    # with custom PaperTrail ones.
+    module AttributeSerializerFactory
+      AR_PG_ARRAY_CLASS = "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array"
+
+      def self.for(klass, attr)
+        active_record_serializer = klass.type_for_attribute(attr)
+        if active_record_serializer.class.name == AR_PG_ARRAY_CLASS
+          TypeSerializers::PostgresArraySerializer.new(
+            active_record_serializer.subtype,
+            active_record_serializer.delimiter
+          )
+        else
+          active_record_serializer
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require "paper_trail/attribute_serializers/attribute_serializer_factory"
+
 module PaperTrail
   # :nodoc:
   module AttributeSerializers
@@ -6,8 +10,7 @@ module PaperTrail
     # to an attribute of type `ActiveRecord::Type::Integer`.
     #
     # This implementation depends on the `type_for_attribute` method, which was
-    # introduced in rails 4.2. In older versions of rails, we shim this method
-    # with `LegacyActiveRecordShim`.
+    # introduced in rails 4.2. As of PT 8, we no longer support rails < 4.2.
     class CastAttributeSerializer
       def initialize(klass)
         @klass = klass
@@ -29,50 +32,18 @@ module PaperTrail
       end
     end
 
-    if ::ActiveRecord::VERSION::MAJOR >= 5
-      # This implementation uses AR 5's `serialize` and `deserialize`.
-      class CastAttributeSerializer
-        def serialize(attr, val)
-          @klass.type_for_attribute(attr).serialize(val)
-        end
-
-        def deserialize(attr, val)
-          if defined_enums[attr] && val.is_a?(::String)
-            # Because PT 4 used to save the string version of enums to `object_changes`
-            val
-          else
-            @klass.type_for_attribute(attr).deserialize(val)
-          end
-        end
+    # Uses AR 5's `serialize` and `deserialize`.
+    class CastAttributeSerializer
+      def serialize(attr, val)
+        AttributeSerializerFactory.for(@klass, attr).serialize(val)
       end
-    else
-      # This implementation uses AR 4.2's `type_cast_for_database`. For
-      # versions of AR < 4.2 we provide an implementation of
-      # `type_cast_for_database` in our shim attribute type classes,
-      # `NoOpAttribute` and `SerializedAttribute`.
-      class CastAttributeSerializer
-        def serialize(attr, val)
-          castable_val = val
-          if defined_enums[attr]
-            # `attr` is an enum. Find the number that corresponds to `val`. If `val` is
-            # a number already, there won't be a corresponding entry, just use `val`.
-            castable_val = defined_enums[attr][val] || val
-          end
-          @klass.type_for_attribute(attr).type_cast_for_database(castable_val)
-        end
 
-        def deserialize(attr, val)
-          if defined_enums[attr] && val.is_a?(::String)
-            # Because PT 4 used to save the string version of enums to `object_changes`
-            val
-          else
-            val = @klass.type_for_attribute(attr).type_cast_from_database(val)
-            if defined_enums[attr]
-              defined_enums[attr].key(val)
-            else
-              val
-            end
-          end
+      def deserialize(attr, val)
+        if defined_enums[attr] && val.is_a?(::String)
+          # Because PT 4 used to save the string version of enums to `object_changes`
+          val
+        else
+          AttributeSerializerFactory.for(@klass, attr).deserialize(val)
         end
       end
     end

data/lib/paper_trail/attribute_serializers/object_attribute.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/cast_attribute_serializer"
 
 module PaperTrail

data/lib/paper_trail/attribute_serializers/object_changes_attribute.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/cast_attribute_serializer"
 
 module PaperTrail

data/lib/paper_trail/cleaner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   # Utilities for deleting version records.
   module Cleaner
@@ -52,7 +54,7 @@ module PaperTrail
     # versions.
     # @api private
     def group_versions_by_date(versions)
-      versions.group_by { |v| v.send(PaperTrail.timestamp_field).to_date }
+      versions.group_by { |v| v.created_at.to_date }
     end
   end
 end

data/lib/paper_trail/compatibility.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Rails does not follow SemVer, makes breaking changes in minor versions.
+  # Breaking changes are expected, and are generally good for the rails
+  # ecosystem. However, they often require dozens of hours to fix, even with the
+  # [help of experts](https://github.com/paper-trail-gem/paper_trail/pull/899).
+  #
+  # It is not safe to assume that a new version of rails will be compatible with
+  # PaperTrail. PT is only compatible with the versions of rails that it is
+  # tested against. See `.travis.yml`.
+  #
+  # However, as of
+  # [#1213](https://github.com/paper-trail-gem/paper_trail/pull/1213) our
+  # gemspec allows installation with newer, incompatible rails versions. We hope
+  # this will make it easier for contributors to work on compatibility with
+  # newer rails versions. Most PT users should avoid incompatible rails
+  # versions.
+  module Compatibility
+    ACTIVERECORD_GTE = ">= 5.2" # enforced in gemspec
+    ACTIVERECORD_LT = "< 6.1" # not enforced in gemspec
+
+    E_INCOMPATIBLE_AR = <<-EOS
+      PaperTrail %s is not compatible with ActiveRecord %s. We allow PT
+      contributors to install incompatible versions of ActiveRecord, and this
+      warning can be silenced with an environment variable, but this is a bad
+      idea for normal use. Please install a compatible version of ActiveRecord
+      instead (%s). Please see the discussion in paper_trail/compatibility.rb
+      for details.
+    EOS
+
+    # Normal users need a warning if they accidentally install an incompatible
+    # version of ActiveRecord. Contributors can silence this warning with an
+    # environment variable.
+    def self.check_activerecord(ar_version)
+      raise ::TypeError unless ar_version.instance_of?(::Gem::Version)
+      return if ::ENV["PT_SILENCE_AR_COMPAT_WARNING"].present?
+      req = ::Gem::Requirement.new([ACTIVERECORD_GTE, ACTIVERECORD_LT])
+      unless req.satisfied_by?(ar_version)
+        ::Kernel.warn(
+          format(
+            E_INCOMPATIBLE_AR,
+            ::PaperTrail.gem_version,
+            ar_version,
+            req
+          )
+        )
+      end
+    end
+  end
+end

data/lib/paper_trail/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "singleton"
 require "paper_trail/serializers/yaml"
 
@@ -6,9 +8,14 @@ module PaperTrail
   # configuration can be found in `paper_trail.rb`, others in `controller.rb`.
   class Config
     include Singleton
-    attr_accessor :serializer, :version_limit
-    attr_reader :timestamp_field # deprecated
-    attr_writer :track_associations
+
+    attr_accessor(
+      :association_reify_error_behaviour,
+      :object_changes_adapter,
+      :serializer,
+      :version_limit,
+      :has_paper_trail_defaults
+    )
 
     def initialize
       # Variables which affect all threads, whose access is synchronized.
@@ -16,53 +23,8 @@ module PaperTrail
       @enabled = true
 
       # Variables which affect all threads, whose access is *not* synchronized.
-      @timestamp_field = :created_at
       @serializer = PaperTrail::Serializers::YAML
-    end
-
-    def serialized_attributes
-      ActiveSupport::Deprecation.warn(
-        "PaperTrail.config.serialized_attributes is deprecated without " +
-          "replacement and always returns false."
-      )
-      false
-    end
-
-    def serialized_attributes=(_)
-      ActiveSupport::Deprecation.warn(
-        "PaperTrail.config.serialized_attributes= is deprecated without " +
-          "replacement and no longer has any effect."
-      )
-    end
-
-    # Set the field which records when a version was created.
-    # @api public
-    # @deprecated
-    def timestamp_field=(field_name)
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.config.timestamp_field= is deprecated without replacement." \
-          "See https://github.com/airblade/paper_trail/pull/861 for discussion",
-        caller(1)
-      )
-      @timestamp_field = field_name
-    end
-
-    # Previously, we checked `PaperTrail::VersionAssociation.table_exists?`
-    # here, but that proved to be problematic in situations when the database
-    # connection had not been established, or when the database does not exist
-    # yet (as with `rake db:create`).
-    def track_associations?
-      if @track_associations.nil?
-        ActiveSupport::Deprecation.warn <<-EOS.strip_heredoc.gsub(/\s+/, " ")
-          PaperTrail.track_associations has not been set. As of PaperTrail 5, it
-          defaults to false. Tracking associations is an experimental feature so
-          we recommend setting PaperTrail.config.track_associations = false in
-          your config/initializers/paper_trail.rb
-        EOS
-        false
-      else
-        @track_associations
-      end
+      @has_paper_trail_defaults = {}
     end
 
     # Indicates whether PaperTrail is on or off. Default: true.

data/lib/paper_trail/events/base.rb

@@ -0,0 +1,323 @@
+# 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
+      RAILS_GTE_5_1 = ::ActiveRecord.gem_version >= ::Gem::Version.new("5.1.0.beta1")
+
+      # @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
+
+      # 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 && RAILS_GTE_5_1
+          @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)
+        cache_changed_attributes do
+          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
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`.
+      # @api private
+      def cache_changed_attributes(&block)
+        if RAILS_GTE_5_1
+          # Everything works fine as it is
+          yield
+        else
+          # Any particular call to `changed_attributes` produces the huge memory allocation.
+          # Lets use the generic AR workaround for that.
+          @record.send(:cache_changed_attributes, &block)
+        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 RAILS_GTE_5_1
+          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
+        else
+          @record.attribute_was(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
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      #
+      # @api private
+      def changes_in_latest_version
+        # Memoized to reduce memory usage
+        @changes_in_latest_version ||= begin
+          if @in_after_callback && RAILS_GTE_5_1
+            @record.saved_changes
+          else
+            @record.changes
+          end
+        end
+      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
+
+      # 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)
+        data.merge(PaperTrail.request.controller_info || {})
+      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|
+          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)
+          # If it is an attribute that is changing in an existing object,
+          # be sure to grab the current version.
+          if event != "create" &&
+              @record.has_attribute?(value) &&
+              attribute_changed_in_latest_version?(value)
+            attribute_in_previous_version(value, false)
+          else
+            @record.send(value)
+          end
+        else
+          value
+        end
+      end
+
+      # @api private
+      def notable_changes
+        changes_in_latest_version.delete_if { |k, _v|
+          !notably_changed.include?(k)
+        }
+      end
+
+      # @api private
+      def notably_changed
+        # Memoized to reduce memory usage
+        @notably_changed ||= begin
+          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
+      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