paper_trail 9.2.0 → 14.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2e53b5f5457783341505d9c0341c5fdc93c52191644db689260311c6c63de72
-  data.tar.gz: bd94edaeb1bd3ca9d329b925241c1fe8774e7f058e64f82e06411e04397833ae
+  metadata.gz: 8442e35802b28551f1ab7275a3e6a14fed55edcba6c1aa9beeff5e65a2a92626
+  data.tar.gz: 3014b42bde912764165fc14a8974b14cc16cdf9643a1f8c9af23083a4479c50d
 SHA512:
-  metadata.gz: 63d9377e20237a70d024e857f64dcd089126efc5bbce13f4dffc65a1c9f4d8210426269bfb60af9bdcdaa7d23211c2359d3a8676ceaa3346b0d0e414cd813ffd
-  data.tar.gz: 952ea2469901473c0fe66b5b5e6aaaf65070957c0211147c60372c5a172029415aea87c93c6daac2c00243a087aa4135ca304b0ac69ad0f32a1a4fb940543e50
+  metadata.gz: 57f5248c0e5d448dd20e88530f06e74fddcf641c1f13f6b9d7e33ef54305168e5f0bb34322c4db7b0b9b5fe9c7c988116a72b17605500061c43ffc67f0519f9d
+  data.tar.gz: 6d84306539336b774e8b9cd5f1f2412fa59752c6ceb3033af6be9652045e19d5e11f95555f47cdde3742bf18e6165addcde3e3d5a5b2c7b8df7ecc908b16d6eb

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Andy Stewart, AirBlade Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/generators/paper_trail/install/USAGE

@@ -0,0 +1,3 @@
+Description:
+  Generates (but does not run) a migration to add a versions table. Also generates an initializer
+  file for configuring PaperTrail. See section 5.c. Generators in README.md for more information.

data/lib/generators/paper_trail/{install_generator.rb → install/install_generator.rb}

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
 
-require "rails/generators"
-require "rails/generators/active_record"
+require_relative "../migration_generator"
 
 module PaperTrail
   # Installs PaperTrail in a rails app.
-  class InstallGenerator < ::Rails::Generators::Base
-    include ::Rails::Generators::Migration
-
+  class InstallGenerator < MigrationGenerator
     # Class names of MySQL adapters.
     # - `MysqlAdapter` - Used by gems: `mysql`, `activerecord-jdbcmysql-adapter`.
     # - `Mysql2Adapter` - Used by `mysql2` gem.
@@ -23,50 +20,42 @@ module PaperTrail
       default: false,
       desc: "Store changeset (diff) with each version"
     )
+    class_option(
+      :uuid,
+      type: :boolean,
+      default: false,
+      desc: "Use uuid instead of bigint for item_id type (use only if tables use UUIDs)"
+    )
 
     desc "Generates (but does not run) a migration to add a versions table." \
-         "  Also generates an initializer file for configuring PaperTrail"
+         "  See section 5.c. Generators in README.md for more information."
 
     def create_migration_file
-      add_paper_trail_migration("create_versions")
-      add_paper_trail_migration("add_object_changes_to_versions") if options.with_changes?
-    end
-
-    def self.next_migration_number(dirname)
-      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
-    end
-
-    protected
-
-    def add_paper_trail_migration(template)
-      migration_dir = File.expand_path("db/migrate")
-      if self.class.migration_exists?(migration_dir, template)
-        ::Kernel.warn "Migration already exists: #{template}"
-      else
-        migration_template(
-          "#{template}.rb.erb",
-          "db/migrate/#{template}.rb",
-          item_type_options: item_type_options,
-          migration_version: migration_version,
-          versions_table_options: versions_table_options
-        )
+      add_paper_trail_migration(
+        "create_versions",
+        item_type_options: item_type_options,
+        versions_table_options: versions_table_options,
+        item_id_type_options: item_id_type_options
+      )
+      if options.with_changes?
+        add_paper_trail_migration("add_object_changes_to_versions")
       end
     end
 
     private
 
+    # To use uuid instead of integer for primary key
+    def item_id_type_options
+      options.uuid? ? "string" : "bigint"
+    end
+
     # MySQL 5.6 utf8mb4 limit is 191 chars for keys used in indexes.
     # See https://github.com/paper-trail-gem/paper_trail/issues/651
     def item_type_options
-      opt = { null: false }
-      opt[:limit] = 191 if mysql?
-      ", #{opt}"
-    end
-
-    def migration_version
-      major = ActiveRecord::VERSION::MAJOR
-      if major >= 5
-        "[#{major}.#{ActiveRecord::VERSION::MINOR}]"
+      if mysql?
+        ", null: false, limit: 191"
+      else
+        ", null: false"
       end
     end
 
@@ -91,7 +80,7 @@ module PaperTrail
     #
     def versions_table_options
       if mysql?
-        ', { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }'
+        ', options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci"'
       else
         ""
       end

data/lib/generators/paper_trail/{templates → install/templates}/create_versions.rb.erb

@@ -11,7 +11,7 @@ class CreateVersions < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :versions<%= versions_table_options %> do |t|
       t.string   :item_type<%= item_type_options %>
-      t.integer  :item_id,   null: false
+      t.<%= item_id_type_options %>   :item_id,   null: false
       t.string   :event,     null: false
       t.string   :whodunnit
       t.text     :object, limit: TEXT_BYTES
@@ -25,12 +25,14 @@ class CreateVersions < ActiveRecord::Migration<%= migration_version %>
       # the `created_at` column.
       # (https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html)
       #
-      # MySQL users should also upgrade to rails 4.2, which is the first
+      # MySQL users should also upgrade to at least rails 4.2, which is the first
       # version of ActiveRecord with support for fractional seconds in MySQL.
       # (https://github.com/rails/rails/pull/14359)
       #
+      # MySQL users should use the following line for `created_at`
+      # t.datetime :created_at, limit: 6
       t.datetime :created_at
     end
-    add_index :versions, %i(item_type item_id)
+    add_index :versions, %i[item_type item_id]
   end
 end

data/lib/generators/paper_trail/migration_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module PaperTrail
+  # Basic structure to support a generator that builds a migration
+  class MigrationGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    def self.next_migration_number(dirname)
+      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    protected
+
+    def add_paper_trail_migration(template, extra_options = {})
+      migration_dir = File.expand_path("db/migrate")
+      if self.class.migration_exists?(migration_dir, template)
+        ::Kernel.warn "Migration already exists: #{template}"
+      else
+        migration_template(
+          "#{template}.rb.erb",
+          "db/migrate/#{template}.rb",
+          { migration_version: migration_version }.merge(extra_options)
+        )
+      end
+    end
+
+    def migration_version
+      format(
+        "[%d.%d]",
+        ActiveRecord::VERSION::MAJOR,
+        ActiveRecord::VERSION::MINOR
+      )
+    end
+  end
+end

data/lib/generators/paper_trail/update_item_subtype/USAGE

@@ -0,0 +1,4 @@
+Description:
+  Generates (but does not run) a migration to update item_type for STI entries
+  in an existing versions table. See section 5.c. Generators in README.md for
+  more information.

data/lib/generators/paper_trail/update_item_subtype/templates/update_versions_for_item_subtype.rb.erb

@@ -0,0 +1,85 @@
+# This migration updates existing `versions` that have `item_type` that refers to
+# the base_class, and changes them to refer to the subclass instead.
+class UpdateVersionsForItemSubtype < ActiveRecord::Migration<%= migration_version %>
+  include ActionView::Helpers::TextHelper
+  def up
+<%=
+  # Returns class, column, range
+  def self.parse_custom_entry(text)
+    parts = text.split("):")
+    range = parts.last.split("..").map(&:to_i)
+    range = Range.new(range.first, range.last)
+    parts.first.split("(") + [range]
+  end
+  # Running:
+  #   rails g paper_trail:update_item_subtype Animal(species):1..4 Plant(genus):42..1337
+  # results in:
+  #   # Versions of item_type "Animal" with IDs between 1 and 4 will be updated based on `species`
+  #   # Versions of item_type "Plant" with IDs between 42 and 1337 will be updated based on `genus`
+  #   hints = {"Animal"=>{1..4=>"species"}, "Plant"=>{42..1337=>"genus"}}
+  hint_descriptions = ""
+  hints = args.inject(Hash.new{|h, k| h[k] = {}}) do |s, v|
+    klass, column, range = parse_custom_entry(v)
+    hint_descriptions << "    # Versions of item_type \"#{klass}\" with IDs between #{
+      range.first} and #{range.last} will be updated based on \`#{column}\`\n"
+    s[klass][range] = column
+    s
+  end
+
+  unless hints.empty?
+    "#{hint_descriptions}    hints = #{hints.inspect}\n"
+  end
+%>
+    # Find all ActiveRecord models mentioned in existing versions
+    changes = Hash.new { |h, k| h[k] = [] }
+    model_names = PaperTrail::Version.select(:item_type).distinct
+    model_names.map(&:item_type).each do |model_name|
+      hint = hints[model_name] if defined?(hints)
+      begin
+        klass = model_name.constantize
+        # Actually implements an inheritance_column?  (Usually "type")
+        has_inheritance_column = klass.columns.map(&:name).include?(klass.inheritance_column)
+        # Find domain of types stored in PaperTrail versions
+        PaperTrail::Version.where(item_type: model_name, item_subtype: nil).select(:id, :object, :object_changes).each do |obj|
+          if (object_detail = PaperTrail.serializer.load(obj.object || obj.object_changes))
+            is_found = false
+            subtype_name = nil
+            hint&.each do |k, v|
+              if k === obj.id && (subtype_name = object_detail[v])
+                break
+              end
+            end
+            if subtype_name.nil? && has_inheritance_column
+              subtype_name = object_detail[klass.inheritance_column]
+            end
+            if subtype_name
+              subtype_name = subtype_name.last if subtype_name.is_a?(Array)
+              if subtype_name != model_name
+                changes[subtype_name] << obj.id
+              end
+            end
+          end
+        end
+      rescue NameError => ex
+        say "Skipping reference to #{model_name}", subitem: true
+      end
+    end
+    changes.each do |k, v|
+      # Update in blocks of up to 100 at a time
+      block_of_ids = []
+      id_count = 0
+      num_updated = 0
+      v.sort.each do |id|
+        block_of_ids << id
+        if (id_count += 1) % 100 == 0
+          num_updated += PaperTrail::Version.where(id: block_of_ids).update_all(item_subtype: k)
+          block_of_ids = []
+        end
+      end
+      num_updated += PaperTrail::Version.where(id: block_of_ids).update_all(item_subtype: k)
+      if num_updated > 0
+        say "Associated #{pluralize(num_updated, 'record')} to #{k}", subitem: true
+      end
+    end
+  end
+end

data/lib/generators/paper_trail/update_item_subtype/update_item_subtype_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../migration_generator"
+
+module PaperTrail
+  # Updates STI entries for PaperTrail
+  class UpdateItemSubtypeGenerator < MigrationGenerator
+    source_root File.expand_path("templates", __dir__)
+
+    desc(
+      "Generates (but does not run) a migration to update item_subtype for "\
+      "STI entries in an existing versions table."
+    )
+
+    def create_migration_file
+      add_paper_trail_migration("update_versions_for_item_subtype", sti_type_options: options)
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/attribute_serializer_factory.rb

@@ -8,18 +8,32 @@ module PaperTrail
     # not suited for writing JSON to a text column. This factory
     # replaces certain default Active Record serializers
     # with custom PaperTrail ones.
+    #
+    # @api private
     module AttributeSerializerFactory
-      AR_PG_ARRAY_CLASS = "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array"
+      class << self
+        # @api private
+        def for(klass, attr)
+          active_record_serializer = klass.type_for_attribute(attr)
+          if ar_pg_array?(active_record_serializer)
+            TypeSerializers::PostgresArraySerializer.new(
+              active_record_serializer.subtype,
+              active_record_serializer.delimiter
+            )
+          else
+            active_record_serializer
+          end
+        end
+
+        private
 
-      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
+        # @api private
+        def ar_pg_array?(obj)
+          if defined?(::ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array)
+            obj.instance_of?(::ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array)
+          else
+            false
+          end
         end
       end
     end

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -8,9 +8,6 @@ module PaperTrail
     # The `CastAttributeSerializer` (de)serializes model attribute values. For
     # example, the string "1.99" serializes into the integer `1` when assigned
     # to an attribute of type `ActiveRecord::Type::Integer`.
-    #
-    # This implementation depends on the `type_for_attribute` method, which was
-    # introduced in rails 4.2. As of PT 8, we no longer support rails < 4.2.
     class CastAttributeSerializer
       def initialize(klass)
         @klass = klass
@@ -30,53 +27,28 @@ module PaperTrail
       def defined_enums
         @defined_enums ||= (@klass.respond_to?(:defined_enums) ? @klass.defined_enums : {})
       end
-    end
 
-    if ::ActiveRecord::VERSION::MAJOR >= 5
-      # This implementation uses AR 5's `serialize` and `deserialize`.
-      class CastAttributeSerializer
-        def serialize(attr, val)
-          AttributeSerializerFactory.for(@klass, attr).serialize(val)
+      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
+        elsif rails_gte_7_0? && val.is_a?(ActiveRecord::Type::Time::Value)
+          # Because Rails 7 time attribute throws a delegation error when you deserialize
+          # it with the factory.
+          # See ActiveRecord::Type::Time::Value crashes when loaded from YAML on rails 7.0
+          # https://github.com/rails/rails/issues/43966
+          val.instance_variable_get(:@time)
+        else
+          AttributeSerializerFactory.for(@klass, attr).deserialize(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
+      def rails_gte_7_0?
+        ::ActiveRecord.gem_version >= ::Gem::Version.new("7.0.0")
       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
-        end
+      def serialize(attr, val)
+        AttributeSerializerFactory.for(@klass, attr).serialize(val)
       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 `.github/workflows/test.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 = ">= 6.0" # enforced in gemspec
+    ACTIVERECORD_LT = "< 7.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

@@ -8,8 +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, :association_reify_error_behaviour,
-      :object_changes_adapter
+
+    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.
@@ -18,6 +24,7 @@ module PaperTrail
 
       # Variables which affect all threads, whose access is *not* synchronized.
       @serializer = PaperTrail::Serializers::YAML
+      @has_paper_trail_defaults = {}
     end
 
     # Indicates whether PaperTrail is on or off. Default: true.

data/lib/paper_trail/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Generic PaperTrail exception.
+  # @api public
+  class Error < StandardError
+  end
+
+  # An unexpected option, perhaps a typo, was passed to a public API method.
+  # @api public
+  class InvalidOption < Error
+  end
+
+  # The application's database schema is not supported.
+  # @api public
+  class UnsupportedSchema < Error
+  end
+
+  # The application's database column type is not supported.
+  # @api public
+  class UnsupportedColumnType < UnsupportedSchema
+    def initialize(method:, expected:, actual:)
+      super(
+        format(
+          "%s expected %s column, got %s",
+          method,
+          expected,
+          actual
+        )
+      )
+    end
+  end
+end