paper_trail 6.0.0 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 70bf4fda92d269f953d7e88fc0a78f72ff3e288e
-  data.tar.gz: 52bf0491880b3dba4905af331f84bc9de67d0bef
+SHA256:
+  metadata.gz: f8f7237a39b0645932b394ee0332846be680f6a725ed02c7a126aa892d840ccc
+  data.tar.gz: b0356d622a6e6f3ba0938c4d9fe0ff211b347a0c65e2d3a6574bc8bf5fb04df6
 SHA512:
-  metadata.gz: 7b139581b4bf0efa29562edc58d30e3854d746d6064c1e4d0a36204ffb1ed34c81d909eea0e6866fa42b35c34f8a3b0fef5e77858f00579bdeca50441d3c13d7
-  data.tar.gz: 1608f17448169a8f2084ce44782cfcac844bd6cf4faba4f283c81b5c338dbed9afc68f5b985279e35019cdb5f40f90a2835a2f9b4ed50ff1e998dc5d78471ea2
+  metadata.gz: 46ad3d73231d4ab6c3d978925e7b838af2697b2b998b9a7948d078266fbdbec33b6dbdcbfb93751f2aa961be6a3499f499a71d56e3fbc6138174cb752feae41a
+  data.tar.gz: 9ec2fc044229898aa2c5ab70dc41b549b6896c61af42633af0760e6b99aadd375f5f7e39160ad713131ecb439b0f5aff8cb6696f276f4c5225eb40e371f43035

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/install_generator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../migration_generator"
+
+module PaperTrail
+  # Installs PaperTrail in a rails app.
+  class InstallGenerator < MigrationGenerator
+    # Class names of MySQL adapters.
+    # - `MysqlAdapter` - Used by gems: `mysql`, `activerecord-jdbcmysql-adapter`.
+    # - `Mysql2Adapter` - Used by `mysql2` gem.
+    MYSQL_ADAPTERS = [
+      "ActiveRecord::ConnectionAdapters::MysqlAdapter",
+      "ActiveRecord::ConnectionAdapters::Mysql2Adapter"
+    ].freeze
+
+    source_root File.expand_path("templates", __dir__)
+    class_option(
+      :with_changes,
+      type: :boolean,
+      default: false,
+      desc: "Store changeset (diff) with each version"
+    )
+
+    desc "Generates (but does not run) a migration to add a versions table." \
+         "  See section 5.c. Generators in README.md for more information."
+
+    def create_migration_file
+      add_paper_trail_migration(
+        "create_versions",
+        item_type_options: item_type_options,
+        versions_table_options: versions_table_options
+      )
+      if options.with_changes?
+        add_paper_trail_migration("add_object_changes_to_versions")
+      end
+    end
+
+    private
+
+    # 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 mysql?
+      MYSQL_ADAPTERS.include?(ActiveRecord::Base.connection.class.name)
+    end
+
+    # Even modern versions of MySQL still use `latin1` as the default character
+    # encoding. Many users are not aware of this, and run into trouble when they
+    # try to use PaperTrail in apps that otherwise tend to use UTF-8. Postgres, by
+    # comparison, uses UTF-8 except in the unusual case where the OS is configured
+    # with a custom locale.
+    #
+    # - https://dev.mysql.com/doc/refman/5.7/en/charset-applications.html
+    # - http://www.postgresql.org/docs/9.4/static/multibyte.html
+    #
+    # Furthermore, MySQL's original implementation of UTF-8 was flawed, and had
+    # to be fixed later by introducing a new charset, `utf8mb4`.
+    #
+    # - https://mathiasbynens.be/notes/mysql-utf8mb4
+    # - https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html
+    #
+    def versions_table_options
+      if mysql?
+        ', { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }'
+      else
+        ""
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 # This migration adds the optional `object_changes` column, in which PaperTrail
 # will store the `changes` diff for each update event. See the readme for
 # details.
-class AddObjectChangesToVersions < ActiveRecord::Migration
+class AddObjectChangesToVersions < ActiveRecord::Migration<%= migration_version %>
   # The largest text column available in all supported RDBMS.
   # See `create_versions.rb` for details.
   TEXT_BYTES = 1_073_741_823

data/lib/generators/paper_trail/install/templates/create_versions.rb.erb

@@ -0,0 +1,36 @@
+# This migration creates the `versions` table, the only schema PT requires.
+# All other migrations PT provides are optional.
+class CreateVersions < ActiveRecord::Migration<%= migration_version %>
+
+  # The largest text column available in all supported RDBMS is
+  # 1024^3 - 1 bytes, roughly one gibibyte.  We specify a size
+  # so that MySQL will use `longtext` instead of `text`.  Otherwise,
+  # when serializing very large objects, `text` might not be big enough.
+  TEXT_BYTES = 1_073_741_823
+
+  def change
+    create_table :versions<%= versions_table_options %> do |t|
+      t.string   :item_type<%= item_type_options %>
+      t.bigint   :item_id,   null: false
+      t.string   :event,     null: false
+      t.string   :whodunnit
+      t.text     :object, limit: TEXT_BYTES
+
+      # Known issue in MySQL: fractional second precision
+      # -------------------------------------------------
+      #
+      # MySQL timestamp columns do not support fractional seconds unless
+      # defined with "fractional seconds precision". MySQL users should manually
+      # add fractional seconds precision to this migration, specifically, to
+      # the `created_at` column.
+      # (https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html)
+      #
+      # 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)
+      #
+      t.datetime :created_at
+    end
+    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,17 @@
+# 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.rb

@@ -1,10 +1,27 @@
+# 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/compatibility"
 require "paper_trail/config"
 require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
 require "paper_trail/reifier"
-require "paper_trail/version_association_concern"
+require "paper_trail/request"
 require "paper_trail/version_concern"
 require "paper_trail/version_number"
 require "paper_trail/serializers/json"
@@ -13,146 +30,88 @@ 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
-    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
 
-    def serialized_attributes?
-      ActiveSupport::Deprecation.warn(
-        "PaperTrail.serialized_attributes? is deprecated without replacement " +
-          "and always returns false."
-      )
-      false
-    end
-
-    # Sets whether PaperTrail is enabled or disabled for the current request.
-    # @api public
-    def enabled_for_controller=(value)
-      paper_trail_store[:request_enabled_for_controller] = value
-    end
-
-    # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
+    # Returns PaperTrail's `::Gem::Version`, convenient for comparisons. This is
+    # recommended over `::PaperTrail::VERSION::STRING`.
+    #
+    # Added in 7.0.0
     #
-    # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
-    # @api public
-    def enabled_for_controller?
-      !!paper_trail_store[:request_enabled_for_controller]
-    end
-
-    # Sets whether PaperTrail is enabled or disabled for this model in the
-    # current request.
     # @api public
-    def enabled_for_model(model, value)
-      paper_trail_store[:"enabled_for_#{model}"] = value
+    def gem_version
+      ::Gem::Version.new(VERSION::STRING)
     end
 
-    # Returns `true` if PaperTrail is enabled for this model in the current
-    # request, `false` otherwise.
+    # 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`, executes the block,
+    # and returns the value of 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 enabled_for_model?(model)
-      !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
+    def request(options = nil, &block)
+      if options.nil? && !block_given?
+        Request
+      else
+        Request.with(options, &block)
+      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."
-      )
-    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
-    def whodunnit=(value)
-      paper_trail_store[:whodunnit] = value
-    end
-
-    # Returns who is reponsible for any changes that occur.
-    # @api public
-    def whodunnit
-      paper_trail_store[:whodunnit]
-    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
-    def controller_info=(value)
-      paper_trail_store[:controller_info] = value
+      raise(E_TIMESTAMP_FIELD_CONFIG)
     end
 
-    # Returns any information from the controller that you want
-    # PaperTrail to store.
-    #
-    # See `PaperTrail::Rails::Controller#info_for_paper_trail`.
-    # @api public
-    def controller_info
-      paper_trail_store[: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
     end
 
-    # Returns a boolean indicating whether "protected attibutes" should be
-    # configured, e.g. attr_accessible, mass_assignment_sanitizer,
-    # whitelist_attributes, etc.
-    # @api public
-    def active_record_protected_attributes?
-      @active_record_protected_attributes ||= ::ActiveRecord::VERSION::MAJOR < 4 ||
-        !!defined?(ProtectedAttributes)
-    end
-
-    # @api public
-    def transaction?
-      ::ActiveRecord::Base.connection.open_transactions > 0
-    end
-
-    # @api public
-    def transaction_id
-      paper_trail_store[:transaction_id]
-    end
-
-    # @api public
-    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 }
-    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
@@ -167,25 +126,27 @@ module PaperTrail
   end
 end
 
-# If available, ensure that the `protected_attributes` gem is loaded
-# before the `Version` class.
-unless PaperTrail.active_record_protected_attributes?
-  PaperTrail.send(:remove_instance_variable, :@active_record_protected_attributes)
-  begin
-    require "protected_attributes"
-  rescue LoadError # rubocop:disable Lint/HandleExceptions
-    # In case `protected_attributes` gem is not available.
-  end
-end
-
+# We use the `on_load` "hook" instead of `ActiveRecord::Base.include` because we
+# don't want to cause all of AR to be autloaded yet. See
+# https://guides.rubyonrails.org/engines.html#what-are-on-load-hooks-questionmark
+# to learn more about `on_load`.
 ActiveSupport.on_load(:active_record) do
   include PaperTrail::Model
 end
 
 # Require frameworks
-require "paper_trail/frameworks/sinatra"
-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
+
+if defined?(::ActiveRecord)
+  ::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
+end