paper_trail 8.0.0 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 91bf6fabed9a524ca3251a32df08bf75daaf8e59
-  data.tar.gz: 98c9208fcb6946ce58943ff3188ddee60f90a0de
+SHA256:
+  metadata.gz: 24616bf1e1df70302e7417a24d60141dc2a0d20f1c6e8ac3690dbd4abf890a82
+  data.tar.gz: 8f0ea37c0b65a0c15bfbf4096db430e81d848952f6d42ecbc09d5028fa042d3e
 SHA512:
-  metadata.gz: f75fd7f32568e15f48194cbd099152f75d0e38bd3e3e5f173c16f20919ad3766f9ccfebb69203558946abcd48d1da017a80749c1c957093af589478fa187b2cb
-  data.tar.gz: b4916a9fae7ce82d73d98baefb6d63d41482c0e7dc090751b2ddf7543876a070782c16a233f1b89617932ec1fb92d9810995b67ab4196d7bff94ecc471e2f912
+  metadata.gz: 109af4466c2f6a61b42633bb94e46909203252757d7864250dd8e62cddfe82ef317419fc5ad8f784eecb453af387a02242b643b58b8eadd5778ce1e64c4b56a3
+  data.tar.gz: b840ca06183ff5411b0dcc493c8bdbc8abaa94060d8dfccaf1b0cbd0bbf69cd4bda4c2a98e3bd406d4760317e9949c89e306bd7b54e676237b162f3721f30497

data/lib/generators/paper_trail/install_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators"
 require "rails/generators/active_record"
 
@@ -43,7 +45,7 @@ module PaperTrail
     def create_initializer
       create_file(
         "config/initializers/paper_trail.rb",
-        "PaperTrail.config.track_associations = #{!!options.with_associations?}"
+        "PaperTrail.config.track_associations = #{!!options.with_associations?}\n"
       )
     end
 

data/lib/paper_trail.rb

@@ -1,9 +1,26 @@
+# frozen_string_literal: true
+
+# AR does not require all of AS, but PT does. PT uses core_ext like
+# `String#squish`, so we require `active_support/all`. Instead of eagerly
+# loading all of AS here, we could put specific `require`s in only the various
+# PT files that need them, but this seems easier to troubleshoot, though it may
+# add a few milliseconds to rails boot time. If that becomes a pain point, we
+# can revisit this decision.
+require "active_support/all"
+
+# AR is required for, eg. has_paper_trail.rb, so we could put this `require` in
+# all of those files, but it seems easier to troubleshoot if we just make sure
+# AR is loaded here before loading *any* of PT. See discussion of
+# performance/simplicity tradeoff for activesupport above.
+require "active_record"
+
 require "request_store"
 require "paper_trail/cleaner"
 require "paper_trail/config"
 require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
 require "paper_trail/reifier"
+require "paper_trail/request"
 require "paper_trail/version_association_concern"
 require "paper_trail/version_concern"
 require "paper_trail/version_number"
@@ -13,133 +30,175 @@ require "paper_trail/serializers/yaml"
 # An ActiveRecord extension that tracks changes to your models, for auditing or
 # versioning.
 module PaperTrail
+  E_RAILS_NOT_LOADED = <<-EOS.squish.freeze
+    PaperTrail has been loaded too early, before rails is loaded. This can
+    happen when another gem defines the ::Rails namespace, then PT is loaded,
+    all before rails is loaded. You may want to reorder your Gemfile, or defer
+    the loading of PT by using `require: false` and a manual require elsewhere.
+  EOS
+  E_TIMESTAMP_FIELD_CONFIG = <<-EOS.squish.freeze
+    PaperTrail.timestamp_field= has been removed, without replacement. It is no
+    longer configurable. The timestamp column in the versions table must now be
+    named created_at.
+  EOS
+
   extend PaperTrail::Cleaner
 
   class << self
     # @api private
     def clear_transaction_id
-      self.transaction_id = nil
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.clear_transaction_id is deprecated, " \
+        "use PaperTrail.request.clear_transaction_id",
+        caller(1)
+      )
+      request.clear_transaction_id
     end
 
-    # Switches PaperTrail on or off.
+    # Switches PaperTrail on or off, for all threads.
     # @api public
     def enabled=(value)
       PaperTrail.config.enabled = value
     end
 
-    # Returns `true` if PaperTrail is on, `false` otherwise.
-    # PaperTrail is enabled by default.
+    # Returns `true` if PaperTrail is on, `false` otherwise. This is the
+    # on/off switch that affects all threads. Enabled by default.
     # @api public
     def enabled?
       !!PaperTrail.config.enabled
     end
 
-    # Sets whether PaperTrail is enabled or disabled for the current request.
-    # @api public
+    # @deprecated
     def enabled_for_controller=(value)
-      paper_trail_store[:request_enabled_for_controller] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_controller= is deprecated, " \
+        "use PaperTrail.request.enabled=",
+        caller(1)
+      )
+      request.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
+    # @deprecated
     def enabled_for_controller?
-      !!paper_trail_store[:request_enabled_for_controller]
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_controller? is deprecated, " \
+        "use PaperTrail.request.enabled?",
+        caller(1)
+      )
+      request.enabled?
     end
 
-    # Sets whether PaperTrail is enabled or disabled for this model in the
-    # current request.
-    # @api public
+    # @deprecated
     def enabled_for_model(model, value)
-      paper_trail_store[:"enabled_for_#{model}"] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_model is deprecated, " \
+        "use PaperTrail.request.enabled_for_model",
+        caller(1)
+      )
+      request.enabled_for_model(model, value)
     end
 
-    # Returns `true` if PaperTrail is enabled for this model in the current
-    # request, `false` otherwise.
-    # @api public
+    # @deprecated
     def enabled_for_model?(model)
-      !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_model? is deprecated, " \
+        "use PaperTrail.request.enabled_for_model?",
+        caller(1)
+      )
+      request.enabled_for_model?(model)
     end
 
-    # Returns a `::Gem::Version`, convenient for comparisons. This is
+    # Returns PaperTrail's `::Gem::Version`, convenient for comparisons. This is
     # recommended over `::PaperTrail::VERSION::STRING`.
     # @api public
     def gem_version
       ::Gem::Version.new(VERSION::STRING)
     end
 
+    # Set variables for the current request, eg. whodunnit.
+    #
+    # All request-level variables are now managed here, as of PT 9. Having the
+    # word "request" right there in your application code will remind you that
+    # these variables only affect the current request, not all threads.
+    #
+    # Given a block, temporarily sets the given `options` and execute the block.
+    #
+    # Without a block, this currently just returns `PaperTrail::Request`.
+    # However, please do not use `PaperTrail::Request` directly. 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 public
+    def request(options = nil, &block)
+      if options.nil? && !block_given?
+        Request
+      else
+        Request.with(options, &block)
+        nil
+      end
+    end
+
     # Set the field which records when a version was created.
     # @api public
     def timestamp_field=(_field_name)
-      raise(
-        "PaperTrail.timestamp_field= has been removed, without replacement. " \
-          "It is no longer configurable. The timestamp field in the versions table " \
-          "must now be named created_at."
-      )
+      raise(E_TIMESTAMP_FIELD_CONFIG)
     end
 
-    # Sets who is responsible for any changes that occur. You would normally use
-    # this in a migration or on the console, when working with models directly.
-    # In a controller it is set automatically to the `current_user`.
-    # @api public
+    # @deprecated
     def whodunnit=(value)
-      paper_trail_store[:whodunnit] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.whodunnit= is deprecated, use PaperTrail.request.whodunnit=",
+        caller(1)
+      )
+      request.whodunnit = value
     end
 
-    # If nothing passed, returns who is reponsible for any changes that occur.
-    #
-    #   PaperTrail.whodunnit = "someone"
-    #   PaperTrail.whodunnit # => "someone"
-    #
-    # If value and block passed, set this value as whodunnit for the duration of the block
-    #
-    #   PaperTrail.whodunnit("me") do
-    #     puts PaperTrail.whodunnit # => "me"
-    #   end
-    #
-    # @api public
-    def whodunnit(value = nil)
-      if value
-        raise ArgumentError, "no block given" unless block_given?
-
-        previous_whodunnit = paper_trail_store[:whodunnit]
-        paper_trail_store[:whodunnit] = value
-
-        begin
-          yield
-        ensure
-          paper_trail_store[:whodunnit] = previous_whodunnit
-        end
-      elsif paper_trail_store[:whodunnit].respond_to?(:call)
-        paper_trail_store[:whodunnit].call
+    # @deprecated
+    def whodunnit(value = nil, &block)
+      if value.nil?
+        ::ActiveSupport::Deprecation.warn(
+          "PaperTrail.whodunnit is deprecated, use PaperTrail.request.whodunnit",
+          caller(1)
+        )
+        request.whodunnit
+      elsif block_given?
+        ::ActiveSupport::Deprecation.warn(
+          "Passing a block to PaperTrail.whodunnit is deprecated, " \
+          'use PaperTrail.request(whodunnit: "John") do .. end',
+          caller(1)
+        )
+        request(whodunnit: value, &block)
       else
-        paper_trail_store[:whodunnit]
+        raise ArgumentError, "Invalid arguments"
       end
     end
 
-    # Sets any information from the controller that you want PaperTrail to
-    # store.  By default this is set automatically by a before filter.
-    # @api public
+    # @deprecated
     def controller_info=(value)
-      paper_trail_store[:controller_info] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.controller_info= is deprecated, use PaperTrail.request.controller_info=",
+        caller(1)
+      )
+      request.controller_info = value
     end
 
-    # Returns any information from the controller that you want
-    # PaperTrail to store.
-    #
-    # See `PaperTrail::Rails::Controller#info_for_paper_trail`.
-    # @api public
+    # @deprecated
     def controller_info
-      paper_trail_store[:controller_info]
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.controller_info is deprecated, use PaperTrail.request.controller_info",
+        caller(1)
+      )
+      request.controller_info
     end
 
-    # Getter and Setter for PaperTrail Serializer
+    # Set the PaperTrail serializer. This setting affects all threads.
     # @api public
     def serializer=(value)
       PaperTrail.config.serializer = value
     end
 
+    # Get the PaperTrail serializer used by all threads.
     # @api public
     def serializer
       PaperTrail.config.serializer
@@ -147,27 +206,29 @@ module PaperTrail
 
     # @api public
     def transaction?
-      ::ActiveRecord::Base.connection.open_transactions > 0
+      ::ActiveRecord::Base.connection.open_transactions.positive?
     end
 
-    # @api public
+    # @deprecated
     def transaction_id
-      paper_trail_store[:transaction_id]
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.transaction_id is deprecated without replacement.",
+        caller(1)
+      )
+      request.transaction_id
     end
 
-    # @api public
+    # @deprecated
     def transaction_id=(id)
-      paper_trail_store[:transaction_id] = id
-    end
-
-    # Thread-safe hash to hold PaperTrail's data. Initializing with needed
-    # default values.
-    # @api private
-    def paper_trail_store
-      RequestStore.store[:paper_trail] ||= { request_enabled_for_controller: true }
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.transaction_id= is deprecated without replacement.",
+        caller(1)
+      )
+      request.transaction_id = id
     end
 
-    # Returns PaperTrail's configuration object.
+    # Returns PaperTrail's global configuration object, a singleton. These
+    # settings affect all threads.
     # @api private
     def config
       @config ||= PaperTrail::Config.instance
@@ -187,8 +248,14 @@ ActiveSupport.on_load(:active_record) do
 end
 
 # Require frameworks
-if defined?(::Rails) && ActiveRecord::VERSION::STRING >= "3.2"
-  require "paper_trail/frameworks/rails"
+if defined?(::Rails)
+  # Rails module is sometimes defined by gems like rails-html-sanitizer
+  # so we check for presence of Rails.application.
+  if defined?(::Rails.application)
+    require "paper_trail/frameworks/rails"
+  else
+    ::Kernel.warn(::PaperTrail::E_RAILS_NOT_LOADED)
+  end
 else
   require "paper_trail/frameworks/active_record"
 end

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
@@ -33,7 +36,7 @@ module PaperTrail
       # This implementation uses AR 5's `serialize` and `deserialize`.
       class CastAttributeSerializer
         def serialize(attr, val)
-          @klass.type_for_attribute(attr).serialize(val)
+          AttributeSerializerFactory.for(@klass, attr).serialize(val)
         end
 
         def deserialize(attr, val)
@@ -41,7 +44,7 @@ module PaperTrail
             # Because PT 4 used to save the string version of enums to `object_changes`
             val
           else
-            @klass.type_for_attribute(attr).deserialize(val)
+            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

data/lib/paper_trail/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "singleton"
 require "paper_trail/serializers/yaml"
 
@@ -5,9 +7,26 @@ module PaperTrail
   # Global configuration affecting all threads. Some thread-specific
   # configuration can be found in `paper_trail.rb`, others in `controller.rb`.
   class Config
+    DPR_TRACK_ASSOC = <<~STR
+      Association tracking is an endangered feature. For the past three or four
+      years it has been an experimental feature, not recommended for production.
+      It has a long list of known issues
+      (https://github.com/airblade/paper_trail#4b1-known-issues) and has no
+      regular volunteers caring for it.
+
+      If you don't use this feature, I strongly recommend disabling it.
+
+      If you do use this feature, please head over to
+      https://github.com/airblade/paper_trail/issues/1070 and volunteer to work
+      on the known issues.
+
+      If we can't make a serious dent in the list of known issues over the next
+      few years, then I'm inclined to delete it, though that would make me sad
+      because I've put dozens of hours into it, and I know others have too.
+    STR
+
     include Singleton
     attr_accessor :serializer, :version_limit
-    attr_writer :track_associations
 
     def initialize
       # Variables which affect all threads, whose access is synchronized.
@@ -18,18 +37,24 @@ module PaperTrail
       @serializer = PaperTrail::Serializers::YAML
     end
 
-    # Previously, we checked `PaperTrail::VersionAssociation.table_exists?`
+    def track_associations=(value)
+      @track_associations = !!value
+      if @track_associations
+        ::ActiveSupport::Deprecation.warn(DPR_TRACK_ASSOC, caller(1))
+      end
+    end
+
+    # As of PaperTrail 5, `track_associations?` 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
+    #
+    # In PT 4, 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.config.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