paper_trail 5.2.3 → 11.0.0

data/lib/paper_trail/request.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "request_store"
+
+module PaperTrail
+  # Manages variables that affect the current HTTP request, such as `whodunnit`.
+  #
+  # Please do not use `PaperTrail::Request` directly, use `PaperTrail.request`.
+  # Currently, `Request` is a `Module`, but in the future it is quite possible
+  # we may make it a `Class`. If we make such a choice, we will not provide any
+  # warning and will not treat it as a breaking change. You've been warned :)
+  #
+  # @api private
+  module Request
+    class InvalidOption < RuntimeError
+    end
+
+    class << self
+      # Sets any data from the controller that you want PaperTrail to store.
+      # See also `PaperTrail::Rails::Controller#info_for_paper_trail`.
+      #
+      #   PaperTrail.request.controller_info = { ip: request_user_ip }
+      #   PaperTrail.request.controller_info # => { ip: '127.0.0.1' }
+      #
+      # @api public
+      def controller_info=(value)
+        store[:controller_info] = value
+      end
+
+      # Returns the data from the controller that you want PaperTrail to store.
+      # See also `PaperTrail::Rails::Controller#info_for_paper_trail`.
+      #
+      #   PaperTrail.request.controller_info = { ip: request_user_ip }
+      #   PaperTrail.request.controller_info # => { ip: '127.0.0.1' }
+      #
+      # @api public
+      def controller_info
+        store[:controller_info]
+      end
+
+      # Switches PaperTrail off for the given model.
+      # @api public
+      def disable_model(model_class)
+        enabled_for_model(model_class, false)
+      end
+
+      # Switches PaperTrail on for the given model.
+      # @api public
+      def enable_model(model_class)
+        enabled_for_model(model_class, true)
+      end
+
+      # Sets whether PaperTrail is enabled or disabled for the current request.
+      # @api public
+      def enabled=(value)
+        store[:enabled] = value
+      end
+
+      # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
+      # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
+      # @api public
+      def enabled?
+        !!store[:enabled]
+      end
+
+      # Sets whether PaperTrail is enabled or disabled for this model in the
+      # current request.
+      # @api public
+      def enabled_for_model(model, value)
+        store[:"enabled_for_#{model}"] = value
+      end
+
+      # Returns `true` if PaperTrail is enabled for this model in the current
+      # request, `false` otherwise.
+      # @api public
+      def enabled_for_model?(model)
+        model.include?(::PaperTrail::Model::InstanceMethods) &&
+          !!store.fetch(:"enabled_for_#{model}", true)
+      end
+
+      # @api private
+      def merge(options)
+        options.to_h.each do |k, v|
+          store[k] = v
+        end
+      end
+
+      # @api private
+      def set(options)
+        store.clear
+        merge(options)
+      end
+
+      # Returns a deep copy of the internal hash from our RequestStore. Keys are
+      # all symbols. Values are mostly primitives, but whodunnit can be a Proc.
+      # We cannot use Marshal.dump here because it doesn't support Proc. It is
+      # unclear exactly how `deep_dup` handles a Proc, but it doesn't complain.
+      # @api private
+      def to_h
+        store.deep_dup
+      end
+
+      # Temporarily set `options` and execute a block.
+      # @api private
+      def with(options)
+        return unless block_given?
+        validate_public_options(options)
+        before = to_h
+        merge(options)
+        yield
+      ensure
+        set(before)
+      end
+
+      # Sets who is responsible for any changes that occur during request. You
+      # would normally use this in a migration or on the console, when working
+      # with models directly.
+      #
+      # `value` is usually a string, the name of a person, but you can set
+      # anything that responds to `to_s`. You can also set a Proc, which will
+      # not be evaluated until `whodunnit` is called later, usually right before
+      # inserting a `Version` record.
+      #
+      # @api public
+      def whodunnit=(value)
+        store[:whodunnit] = value
+      end
+
+      # Returns who is reponsible for any changes that occur during request.
+      #
+      # @api public
+      def whodunnit
+        who = store[:whodunnit]
+        who.respond_to?(:call) ? who.call : who
+      end
+
+      private
+
+      # Returns a Hash, initializing with default values if necessary.
+      # @api private
+      def store
+        RequestStore.store[:paper_trail] ||= {
+          enabled: true
+        }
+      end
+
+      # Provide a helpful error message if someone has a typo in one of their
+      # option keys. We don't validate option values here. That's traditionally
+      # been handled with casting (`to_s`, `!!`) in the accessor method.
+      # @api private
+      def validate_public_options(options)
+        options.each do |k, _v|
+          case k
+          when :controller_info,
+              /enabled_for_/,
+              :enabled,
+              :whodunnit
+            next
+          else
+            raise InvalidOption, "Invalid option: #{k}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/serializers/json.rb

@@ -1,4 +1,4 @@
-require "active_support/json"
+# frozen_string_literal: true
 
 module PaperTrail
   module Serializers
@@ -32,15 +32,14 @@ module PaperTrail
         end
       end
 
-      # Returns a SQL LIKE condition to be used to match the given field and
-      # value in the serialized `object_changes`.
-      def where_object_changes_condition(arel_field, field, value)
-        # Convert to JSON to handle strings and nulls correctly.
-        json_value = value.to_json
-
-        # Need to check first (before) and secondary (after) fields
-        arel_field.matches("%\"#{field}\":[#{json_value},%").
-          or(arel_field.matches("%\"#{field}\":[%,#{json_value}]%"))
+      def where_object_changes_condition(*)
+        raise <<-STR.squish.freeze
+          where_object_changes no longer supports reading JSON from a text
+          column. The old implementation was inaccurate, returning more records
+          than you wanted. This feature was deprecated in 7.1.0 and removed in
+          8.0.0. The json and jsonb datatypes are still supported. See the
+          discussion at https://github.com/paper-trail-gem/paper_trail/issues/803
+        STR
       end
     end
   end

data/lib/paper_trail/serializers/yaml.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "yaml"
 
 module PaperTrail
@@ -10,7 +12,12 @@ module PaperTrail
         ::YAML.load string
       end
 
+      # @param object (Hash | HashWithIndifferentAccess) - Coming from
+      # `recordable_object` `object` will be a plain `Hash`. However, due to
+      # recent [memory optimizations](https://git.io/fjeYv), when coming from
+      # `recordable_object_changes`, it will be a `HashWithIndifferentAccess`.
       def dump(object)
+        object = object.to_hash if object.is_a?(HashWithIndifferentAccess)
         ::YAML.dump object
       end
 
@@ -22,34 +29,14 @@ module PaperTrail
 
       # Returns a SQL LIKE condition to be used to match the given field and
       # value in the serialized `object_changes`.
-      def where_object_changes_condition(arel_field, field, value)
-        # Need to check first (before) and secondary (after) fields
-        m1 = nil
-        m2 = nil
-        case yaml_engine_id
-        when :psych
-          m1 = "%\n#{field}:\n- #{value}\n%"
-          m2 = "%\n#{field}:\n-%\n- #{value}\n%"
-        when :syck
-          # Syck adds extra spaces into array dumps
-          m1 = "%\n#{field}: \n%- #{value}\n%"
-          m2 = "%\n#{field}: \n-%\n- #{value}\n%"
-        else
-          raise "Unknown yaml engine"
-        end
-        arel_field.matches(m1).or(arel_field.matches(m2))
-      end
-
-      # Returns a symbol identifying the YAML engine. Syck was removed from
-      # the ruby stdlib in ruby 2.0, but is still available as a gem.
-      # @api private
-      def yaml_engine_id
-        if (defined?(::YAML::ENGINE) && ::YAML::ENGINE.yamler == "psych") ||
-            (defined?(::Psych) && ::YAML == ::Psych)
-          :psych
-        else
-          :syck
-        end
+      def where_object_changes_condition(*)
+        raise <<-STR.squish.freeze
+          where_object_changes no longer supports reading YAML from a text
+          column. The old implementation was inaccurate, returning more records
+          than you wanted. This feature was deprecated in 8.1.0 and removed in
+          9.0.0. The json and jsonb datatypes are still supported. See
+          discussion at https://github.com/paper-trail-gem/paper_trail/pull/997
+        STR
       end
     end
   end

data/lib/paper_trail/type_serializers/postgres_array_serializer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module TypeSerializers
+    # Provides an alternative method of serialization
+    # and deserialization of PostgreSQL array columns.
+    class PostgresArraySerializer
+      def initialize(subtype, delimiter)
+        @subtype = subtype
+        @delimiter = delimiter
+      end
+
+      def serialize(array)
+        return serialize_with_ar(array) if active_record_pre_502?
+        array
+      end
+
+      def deserialize(array)
+        return deserialize_with_ar(array) if active_record_pre_502?
+
+        case array
+        # Needed for legacy reasons. If serialized array is a string
+        # then it was serialized with Rails < 5.0.2.
+        when ::String then deserialize_with_ar(array)
+        else array
+        end
+      end
+
+      private
+
+      def active_record_pre_502?
+        ::ActiveRecord.gem_version < Gem::Version.new("5.0.2")
+      end
+
+      def serialize_with_ar(array)
+        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
+          new(@subtype, @delimiter).
+          serialize(array)
+      end
+
+      def deserialize_with_ar(array)
+        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
+          new(@subtype, @delimiter).
+          deserialize(array)
+      end
+    end
+  end
+end

data/lib/paper_trail/version_concern.rb

@@ -1,5 +1,8 @@
-require "active_support/concern"
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/object_changes_attribute"
+require "paper_trail/queries/versions/where_object"
+require "paper_trail/queries/versions/where_object_changes"
 
 module PaperTrail
   # Originally, PaperTrail did not provide this module, and all of this
@@ -10,38 +13,22 @@ module PaperTrail
     extend ::ActiveSupport::Concern
 
     included do
-      belongs_to :item, polymorphic: true
-
-      # Since the test suite has test coverage for this, we want to declare
-      # the association when the test suite is running. This makes it pass when
-      # DB is not initialized prior to test runs such as when we run on Travis
-      # CI (there won't be a db in `test/dummy/db/`).
-      if PaperTrail.config.track_associations?
-        has_many :version_associations, dependent: :destroy
+      if ::ActiveRecord.gem_version >= Gem::Version.new("5.0")
+        belongs_to :item, polymorphic: true, optional: true
+      else
+        belongs_to :item, polymorphic: true
       end
 
       validates_presence_of :event
-
-      if PaperTrail.active_record_protected_attributes?
-        attr_accessible(
-          :item_type,
-          :item_id,
-          :event,
-          :whodunnit,
-          :object,
-          :object_changes,
-          :transaction_id,
-          :created_at
-        )
-      end
-
       after_create :enforce_version_limit!
-
-      scope :within_transaction, ->(id) { where transaction_id: id }
     end
 
     # :nodoc:
     module ClassMethods
+      def item_subtype_column_present?
+        column_names.include?("item_subtype")
+      end
+
       def with_item_keys(item_type, item_id)
         where item_type: item_type, item_id: item_id
       end
@@ -62,128 +49,152 @@ module PaperTrail
         where "event <> ?", "create"
       end
 
-      # Returns versions after `obj`.
-      #
-      # @param obj - a `Version` or a timestamp
-      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
-      #   Default: false.
-      # @return `ActiveRecord::Relation`
-      # @api public
-      def subsequent(obj, timestamp_arg = false)
-        if timestamp_arg != true && primary_key_is_int?
-          return where(arel_table[primary_key].gt(obj.id)).order(arel_table[primary_key].asc)
-        end
-
-        obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
-        where(arel_table[PaperTrail.timestamp_field].gt(obj)).order(timestamp_sort_order)
-      end
-
-      # Returns versions before `obj`.
-      #
-      # @param obj - a `Version` or a timestamp
-      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
-      #   Default: false.
-      # @return `ActiveRecord::Relation`
-      # @api public
-      def preceding(obj, timestamp_arg = false)
-        if timestamp_arg != true && primary_key_is_int?
-          return where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
-        end
-
-        obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
-        where(arel_table[PaperTrail.timestamp_field].lt(obj)).
-          order(timestamp_sort_order("desc"))
-      end
-
       def between(start_time, end_time)
         where(
-          arel_table[PaperTrail.timestamp_field].gt(start_time).
-          and(arel_table[PaperTrail.timestamp_field].lt(end_time))
+          arel_table[:created_at].gt(start_time).
+          and(arel_table[:created_at].lt(end_time))
         ).order(timestamp_sort_order)
       end
 
       # Defaults to using the primary key as the secondary sort order if
       # possible.
       def timestamp_sort_order(direction = "asc")
-        [arel_table[PaperTrail.timestamp_field].send(direction.downcase)].tap do |array|
+        [arel_table[:created_at].send(direction.downcase)].tap do |array|
           array << arel_table[primary_key].send(direction.downcase) if primary_key_is_int?
         end
       end
 
-      # Query the `versions.objects` column using the SQL LIKE operator.
-      # Performs an attribute search on the serialized object by invoking the
-      # identically-named method in the serializer being used.
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects` column.
+      #
+      # ```
+      # SELECT "versions".*
+      # FROM "versions"
+      # WHERE ("versions"."object" LIKE '%
+      # name: Joan
+      # %')
+      # ```
+      #
+      # This is useful for finding versions where a given attribute had a given
+      # value. Imagine, in the example above, that Joan had changed her name
+      # and we wanted to find the versions before that change.
+      #
+      # Based on the data type of the `object` column, the appropriate SQL
+      # operator is used. For example, a text column will use `like`, and a
+      # jsonb column will use `@>`.
+      #
       # @api public
       def where_object(args = {})
         raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
-
-        if columns_hash["object"].type == :jsonb
-          where("object @> ?", args.to_json)
-        elsif columns_hash["object"].type == :json
-          predicates = []
-          values = []
-          args.each do |field, value|
-            predicates.push "object->>? = ?"
-            values.concat([field, value.to_s])
-          end
-          sql = predicates.join(" and ")
-          where(sql, *values)
-        else
-          arel_field = arel_table[:object]
-          where_conditions = args.map { |field, value|
-            PaperTrail.serializer.where_object_condition(arel_field, field, value)
-          }
-          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
-          where(where_conditions)
-        end
+        Queries::Versions::WhereObject.new(self, args).execute
       end
 
-      # Query the `versions.object_changes` column by attributes, using the
-      # SQL LIKE operator.
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column.
+      #
+      # ```
+      # SELECT "versions".*
+      # FROM "versions"
+      # WHERE .. ("versions"."object_changes" LIKE '%
+      # name:
+      # - Joan
+      # %' OR "versions"."object_changes" LIKE '%
+      # name:
+      # -%
+      # - Joan
+      # %')
+      # ```
+      #
+      # This is useful for finding versions immediately before and after a given
+      # attribute had a given value. Imagine, in the example above, that someone
+      # changed their name to Joan and we wanted to find the versions
+      # immediately before and after that change.
+      #
+      # Based on the data type of the `object` column, the appropriate SQL
+      # operator is used. For example, a text column will use `like`, and a
+      # jsonb column will use `@>`.
+      #
       # @api public
       def where_object_changes(args = {})
         raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
-
-        if columns_hash["object_changes"].type == :jsonb
-          args.each { |field, value| args[field] = [value] }
-          where("object_changes @> ?", args.to_json)
-        elsif columns_hash["object"].type == :json
-          predicates = []
-          values = []
-          args.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 ")
-          where(sql, *values)
-        else
-          arel_field = arel_table[:object_changes]
-          where_conditions = args.map { |field, value|
-            PaperTrail.serializer.where_object_changes_condition(arel_field, field, value)
-          }
-          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
-          where(where_conditions)
-        end
+        Queries::Versions::WhereObjectChanges.new(self, args).execute
       end
 
       def primary_key_is_int?
         @primary_key_is_int ||= columns_hash[primary_key].type == :integer
-      rescue
+      rescue StandardError # TODO: Rescue something more specific
         true
       end
 
       # Returns whether the `object` column is using the `json` type supported
       # by PostgreSQL.
       def object_col_is_json?
-        [:json, :jsonb].include?(columns_hash["object"].type)
+        %i[json jsonb].include?(columns_hash["object"].type)
       end
 
       # Returns whether the `object_changes` column is using the `json` type
       # supported by PostgreSQL.
       def object_changes_col_is_json?
-        [:json, :jsonb].include?(columns_hash["object_changes"].try(:type))
+        %i[json jsonb].include?(columns_hash["object_changes"].try(:type))
+      end
+
+      # Returns versions before `obj`.
+      #
+      # @param obj - a `Version` or a timestamp
+      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
+      #   Default: false.
+      # @return `ActiveRecord::Relation`
+      # @api public
+      # rubocop:disable Style/OptionalBooleanParameter
+      def preceding(obj, timestamp_arg = false)
+        if timestamp_arg != true && primary_key_is_int?
+          preceding_by_id(obj)
+        else
+          preceding_by_timestamp(obj)
+        end
+      end
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      # Returns versions after `obj`.
+      #
+      # @param obj - a `Version` or a timestamp
+      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
+      #   Default: false.
+      # @return `ActiveRecord::Relation`
+      # @api public
+      # rubocop:disable Style/OptionalBooleanParameter
+      def subsequent(obj, timestamp_arg = false)
+        if timestamp_arg != true && primary_key_is_int?
+          subsequent_by_id(obj)
+        else
+          subsequent_by_timestamp(obj)
+        end
+      end
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      private
+
+      # @api private
+      def preceding_by_id(obj)
+        where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
+      end
+
+      # @api private
+      def preceding_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(arel_table[:created_at].lt(obj)).
+          order(timestamp_sort_order("desc"))
+      end
+
+      # @api private
+      def subsequent_by_id(version)
+        where(arel_table[primary_key].gt(version.id)).order(arel_table[primary_key].asc)
+      end
+
+      # @api private
+      def subsequent_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(arel_table[:created_at].gt(obj)).order(timestamp_sort_order)
       end
     end
 
@@ -198,18 +209,8 @@ module PaperTrail
 
     # Restore the item from this version.
     #
-    # Optionally this can also restore all :has_one and :has_many (including
-    # has_many :through) associations as they were "at the time", if they are
-    # also being versioned by PaperTrail.
-    #
     # Options:
     #
-    # - :has_one
-    #   - `true` - Also reify has_one associations.
-    #   - `false - Default.
-    # - :has_many
-    #   - `true` - Also reify has_many and has_many :through associations.
-    #   - `false` - Default.
     # - :mark_for_destruction
     #   - `true` - Mark the has_one/has_many associations that did not exist in
     #     the reified version for destruction, instead of removing them.
@@ -224,10 +225,11 @@ module PaperTrail
     #   - `:preserve` - Attributes undefined in version record are not modified.
     #
     def reify(options = {})
-      return nil if object.nil?
-      without_identity_map do
-        ::PaperTrail::Reifier.reify(self, options)
+      unless self.class.column_names.include? "object"
+        raise "reify can't be called without an object column"
       end
+      return nil if object.nil?
+      ::PaperTrail::Reifier.reify(self, options)
     end
 
     # Returns what changed in this version of the item.
@@ -243,11 +245,6 @@ module PaperTrail
       @paper_trail_originator ||= previous.try(:whodunnit)
     end
 
-    def originator
-      ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
-      paper_trail_originator
-    end
-
     # Returns who changed the item from the state it had in this version. This
     # is an alias for `whodunnit`.
     def terminator
@@ -255,13 +252,6 @@ module PaperTrail
     end
     alias version_author terminator
 
-    def sibling_versions(reload = false)
-      if reload || @sibling_versions.nil?
-        @sibling_versions = self.class.with_item_keys(item_type, item_id)
-      end
-      @sibling_versions
-    end
-
     def next
       @next ||= sibling_versions.subsequent(self).first
     end
@@ -271,8 +261,9 @@ module PaperTrail
     end
 
     # Returns an integer representing the chronological position of the
-    # version among its siblings (see `sibling_versions`). The "create" event,
-    # for example, has an index of 0.
+    # version among its siblings. The "create" event, for example, has an index
+    # of 0.
+    #
     # @api public
     def index
       @index ||= RecordHistory.new(sibling_versions, self.class).index(self)
@@ -282,6 +273,10 @@ module PaperTrail
 
     # @api private
     def load_changeset
+      if PaperTrail.config.object_changes_adapter&.respond_to?(:load_changeset)
+        return PaperTrail.config.object_changes_adapter.load_changeset(self)
+      end
+
       # First, deserialize the `object_changes` column.
       changes = HashWithIndifferentAccess.new(object_changes_deserialized)
 
@@ -317,33 +312,43 @@ module PaperTrail
       else
         begin
           PaperTrail.serializer.load(object_changes)
-        rescue # TODO: Rescue something specific
+        rescue StandardError # TODO: Rescue something more specific
           {}
         end
       end
     end
 
-    # In Rails 3.1+, calling reify on a previous version confuses the
-    # IdentityMap, if enabled. This prevents insertion into the map.
-    # @api private
-    def without_identity_map(&block)
-      if defined?(::ActiveRecord::IdentityMap) && ::ActiveRecord::IdentityMap.respond_to?(:without)
-        ::ActiveRecord::IdentityMap.without(&block)
-      else
-        yield
-      end
-    end
-
-    # Checks that a value has been set for the `version_limit` config
-    # option, and if so enforces it.
+    # Enforces the `version_limit`, if set. Default: no limit.
     # @api private
     def enforce_version_limit!
-      limit = PaperTrail.config.version_limit
+      limit = version_limit
       return unless limit.is_a? Numeric
-      previous_versions = sibling_versions.not_creates
+      previous_versions = sibling_versions.not_creates.
+        order(self.class.timestamp_sort_order("asc"))
       return unless previous_versions.size > limit
       excess_versions = previous_versions - previous_versions.last(limit)
       excess_versions.map(&:destroy)
     end
+
+    # @api private
+    def sibling_versions
+      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
+    end
+
+    # See docs section 2.e. Limiting the Number of Versions Created.
+    # The version limit can be global or per-model.
+    #
+    # @api private
+    #
+    # TODO: Duplication: similar `constantize` in Reifier#version_reification_class
+    def version_limit
+      if self.class.item_subtype_column_present?
+        klass = (item_subtype || item_type).constantize
+        if klass&.paper_trail_options&.key?(:limit)
+          return klass.paper_trail_options[:limit]
+        end
+      end
+      PaperTrail.config.version_limit
+    end
   end
 end