paper_trail 4.0.2 → 10.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8a92875e074ba53155be9597997716e75f2dfa33
-  data.tar.gz: b87bb9cad5f094f61957c287e4a27db3cff0d5d1
+SHA256:
+  metadata.gz: a08a7c456a492933cc36762913040e14bad8f468fc08889580faf9e86ade7fea
+  data.tar.gz: 19711dc6c6e4a438a0a97819c572df610d52db0f5c9aeba0a39eb1f44f3909c0
 SHA512:
-  metadata.gz: f5e16e1229742e460df8c0d1c6315a8207653f756b5df16d88b82e17ae07530260a0dab228afc894aeb3dcc765a7aa15f2b1b46f9366364abbba1bcb12ed61f5
-  data.tar.gz: e5a3ad55b824efa44f70924a47e840ccc16733308298d66eb1de4ba07010eff61ba1ad6a54c50288c18b60d92462d94d025bbd1d14bf4f496349c1a39e43ea89
+  metadata.gz: b39e89605a2b03889976070f0871f9dcd07544b97b6e0105b78035b5fb1ec030c7d5438dc0fe9fb16cccc8e3624cd920d37bd73066f8a4f3892bf356fa088e85
+  data.tar.gz: 56567a718ea4e605d32ffc2b71835b188f6cefab8dd7111b7abcdfc6d9e5b843e8468312ed4dfbc87f74607c1cd4a197ae2c11a9cb44ee2dd16a37a11303e6ad

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,71 @@
+# 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)
+      add_paper_trail_migration("add_object_changes_to_versions") if options.with_changes?
+    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/install/templates/add_object_changes_to_versions.rb.erb

@@ -0,0 +1,12 @@
+# 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<%= migration_version %>
+  # The largest text column available in all supported RDBMS.
+  # See `create_versions.rb` for details.
+  TEXT_BYTES = 1_073_741_823
+
+  def change
+    add_column :versions, :object_changes, :text, limit: TEXT_BYTES
+  end
+end

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.integer  :item_id,   null: false, limit: 8
+      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,37 @@
+# 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
+      major = ActiveRecord::VERSION::MAJOR
+      if major >= 5
+        "[#{major}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    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,160 +1,152 @@
-require 'request_store'
-
-# Require core library
-Dir[File.join(File.dirname(__FILE__), 'paper_trail', '*.rb')].each do |file|
-  require File.join('paper_trail', File.basename(file, '.rb'))
-end
-
-# Require serializers
-Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'serializers', '*.rb')].each do |file|
-  require File.join('paper_trail', 'serializers', File.basename(file, '.rb'))
-end
-
+# 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/request"
+require "paper_trail/version_concern"
+require "paper_trail/version_number"
+require "paper_trail/serializers/json"
+require "paper_trail/serializers/yaml"
+
+# An ActiveRecord extension that tracks changes to your models, for auditing or
+# versioning.
 module PaperTrail
-  extend PaperTrail::Cleaner
-
-  # Switches PaperTrail on or off.
-  def self.enabled=(value)
-    PaperTrail.config.enabled = value
-  end
-
-  # Returns `true` if PaperTrail is on, `false` otherwise.
-  # PaperTrail is enabled by default.
-  def self.enabled?
-    !!PaperTrail.config.enabled
-  end
-
-  # ActiveRecord 5 drops support for serialized attributes; for previous
-  # versions of ActiveRecord it is supported, we have a config option
-  # to enable it within PaperTrail.
-  def self.serialized_attributes?
-    !!PaperTrail.config.serialized_attributes && ::ActiveRecord::VERSION::MAJOR < 5
-  end
-
-  # Sets whether PaperTrail is enabled or disabled for the current request.
-  def self.enabled_for_controller=(value)
-    paper_trail_store[:request_enabled_for_controller] = value
-  end
-
-  # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
-  #
-  # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
-  def self.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.
-  def self.enabled_for_model(model, value)
-    paper_trail_store[:"enabled_for_#{model}"] = value
-  end
-
-  # Returns `true` if PaperTrail is enabled for this model in the current
-  # request, `false` otherwise.
-  def self.enabled_for_model?(model)
-    !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
-  end
-
-  # Set the field which records when a version was created.
-  def self.timestamp_field=(field_name)
-    PaperTrail.config.timestamp_field = field_name
-  end
-
-  # Returns the field which records when a version was created.
-  def self.timestamp_field
-    PaperTrail.config.timestamp_field
-  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`.
-  def self.whodunnit=(value)
-    paper_trail_store[:whodunnit] = value
-  end
-
-  # Returns who is reponsible for any changes that occur.
-  def self.whodunnit
-    paper_trail_store[:whodunnit]
-  end
+  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
 
-  # Sets any information from the controller that you want PaperTrail to
-  # store.  By default this is set automatically by a before filter.
-  def self.controller_info=(value)
-    paper_trail_store[:controller_info] = value
-  end
-
-  # Returns any information from the controller that you want
-  # PaperTrail to store.
-  #
-  # See `PaperTrail::Rails::Controller#info_for_paper_trail`.
-  def self.controller_info
-    paper_trail_store[:controller_info]
-  end
-
-  # Getter and Setter for PaperTrail Serializer
-  def self.serializer=(value)
-    PaperTrail.config.serializer = value
-  end
-
-  def self.serializer
-    PaperTrail.config.serializer
-  end
-
-  def self.active_record_protected_attributes?
-    @active_record_protected_attributes ||= ::ActiveRecord::VERSION::MAJOR < 4 || !!defined?(ProtectedAttributes)
-  end
-
-  def self.transaction?
-    ::ActiveRecord::Base.connection.open_transactions > 0
-  end
-
-  def self.transaction_id
-    paper_trail_store[:transaction_id]
-  end
-
-  def self.transaction_id=(id)
-    paper_trail_store[:transaction_id] = id
-  end
-
-  private
-
-  # Thread-safe hash to hold PaperTrail's data. Initializing with needed
-  # default values.
-  def self.paper_trail_store
-    RequestStore.store[:paper_trail] ||= { :request_enabled_for_controller => true }
-  end
-
-  # Returns PaperTrail's configuration object.
-  def self.config
-    @@config ||= PaperTrail::Config.instance
-    yield @@config if block_given?
-    @@config
-  end
+  extend PaperTrail::Cleaner
 
   class << self
-    alias_method :configure, :config
-  end
-end
-
-# Ensure `ProtectedAttributes` gem gets required if it is available before the
-# `Version` class gets loaded in.
-unless PaperTrail.active_record_protected_attributes?
-  PaperTrail.send(:remove_instance_variable, :@active_record_protected_attributes)
-  begin
-    require 'protected_attributes'
-  rescue LoadError
-    # In case `ProtectedAttributes` gem is not available.
+    # 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. This is the
+    # on/off switch that affects all threads. Enabled by default.
+    # @api public
+    def enabled?
+      !!PaperTrail.config.enabled
+    end
+
+    # Returns PaperTrail's `::Gem::Version`, convenient for comparisons. This is
+    # recommended over `::PaperTrail::VERSION::STRING`.
+    #
+    # Added in 7.0.0
+    #
+    # @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`, 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 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(E_TIMESTAMP_FIELD_CONFIG)
+    end
+
+    # 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 PaperTrail's global configuration object, a singleton. These
+    # settings affect all threads.
+    # @api private
+    def config
+      @config ||= PaperTrail::Config.instance
+      yield @config if block_given?
+      @config
+    end
+    alias configure config
+
+    def version
+      VERSION::STRING
+    end
   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'
+  require "paper_trail/frameworks/active_record"
+end
+
+if defined?(::ActiveRecord)
+  ::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
 end