paper_trail 4.0.0 → 5.1.0

data/Rakefile

@@ -1,30 +1,30 @@
-require 'bundler'
+require "bundler"
 Bundler::GemHelper.install_tasks
 
-desc 'Set a relevant database.yml for testing'
+desc "Set a relevant database.yml for testing"
 task :prepare do
   ENV["DB"] ||= "sqlite"
-  if RUBY_VERSION >= '1.9'
-    FileUtils.cp "test/dummy/config/database.#{ENV["DB"]}.yml", "test/dummy/config/database.yml"
-  else
-    require 'ftools'
-    File.cp "test/dummy/config/database.#{ENV["DB"]}.yml", "test/dummy/config/database.yml"
-  end
+  FileUtils.cp "test/dummy/config/database.#{ENV['DB']}.yml", "test/dummy/config/database.yml"
 end
 
-
-require 'rake/testtask'
-desc 'Run tests on PaperTrail with Test::Unit.'
+require "rake/testtask"
+desc "Run tests on PaperTrail with Test::Unit."
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
   t.verbose = false
 end
 
-require 'rspec/core/rake_task'
-desc 'Run tests on PaperTrail with RSpec'
-RSpec::Core::RakeTask.new(:spec)
+require "rspec/core/rake_task"
+desc "Run tests on PaperTrail with RSpec"
+task(:spec).clear
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = false # hide list of specs bit.ly/1nVq3Jn
+end
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
 
-desc 'Default: run all available test suites'
-task :default => [:prepare, :test, :spec]
+desc "Default: run all available test suites"
+task default: [:rubocop, :prepare, :test, :spec]

data/doc/bug_report_template.rb

@@ -0,0 +1,71 @@
+# Use this template to report PaperTrail bugs.
+# It is based on the ActiveRecord template.
+# https://github.com/rails/rails/blob/master/guides/bug_report_templates/active_record_gem.rb
+begin
+  require "bundler/inline"
+rescue LoadError => e
+  $stderr.puts "Bundler version 1.10 or later is required. Please update your Bundler"
+  raise e
+end
+
+gemfile(true) do
+  ruby "2.2.3"
+  source "https://rubygems.org"
+  gem "activerecord", "4.2.0"
+  gem "minitest", "5.8.3"
+  gem "paper_trail", "4.0.0", require: false
+  gem "sqlite3"
+end
+
+require "active_record"
+require "minitest/autorun"
+require "logger"
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+ActiveRecord::Schema.define do
+  create_table :users, force: true do |t|
+    t.text :first_name, null: false
+    t.timestamps null: false
+  end
+  create_table :versions do |t|
+    t.string :item_type, null: false
+    t.integer :item_id, null: false
+    t.string :event, null: false
+    t.string :whodunnit
+    t.text :object, limit: 1_073_741_823
+    t.text :object_changes, limit: 1_073_741_823
+    t.integer :transaction_id
+    t.datetime :created_at
+  end
+  add_index :versions, [:item_type, :item_id]
+  add_index :versions, [:transaction_id]
+
+  create_table :version_associations do |t|
+    t.integer  :version_id
+    t.string   :foreign_key_name, null: false
+    t.integer  :foreign_key_id
+  end
+  add_index :version_associations, [:version_id]
+  add_index :version_associations, [:foreign_key_name, :foreign_key_id],
+    name: "index_version_associations_on_foreign_key"
+end
+
+# Require `paper_trail.rb` after the `version_associations` table
+# exists so that PT will track associations.
+require "paper_trail"
+
+# Include your models here. Please only include the minimum code necessary to
+# reproduce your issue.
+class User < ActiveRecord::Base
+  has_paper_trail
+end
+
+# Please write a test that demonstrates your issue by failing.
+class BugTest < ActiveSupport::TestCase
+  def test_1
+    assert_difference(-> { PaperTrail::Version.count }, +1) {
+      User.create(first_name: "Jane")
+    }
+  end
+end

data/doc/warning_about_not_setting_whodunnit.md

@@ -0,0 +1,32 @@
+# The warning about not setting whodunnit
+
+After upgrading to PaperTrail 5, you see this warning:
+
+> user_for_paper_trail is present, but whodunnit has not been set. PaperTrail no
+> longer adds the set_paper_trail_whodunnit before_filter for you. Please add this
+> before_filter to your ApplicationController to continue recording whodunnit.
+
+## You want to track whodunnit
+
+Add the set_paper_trail_whodunnit before_filter to your ApplicationController.
+See the PaperTrail readme for an example (https://git.io/vrsbt).
+
+## You don't want to track whodunnit
+
+If you no longer want to track whodunnit, you may disable this
+warning by overriding user_for_paper_trail to return nil.
+
+```
+# in application_controller.rb
+def user_for_paper_trail
+  nil # disable whodunnit tracking
+end
+```
+
+## You just want the warning to go away
+
+To disable this warning for any other reason, use `skip_after_action`.
+
+```
+skip_after_action :warn_about_not_setting_whodunnit
+```

data/gemfiles/ar3.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 3.2.22"
+gem "i18n", "~> 0.6.11"
+gem "request_store", "~> 1.1.0"
+
+group :development, :test do
+  gem "railties", "~> 3.2.22"
+  gem "test-unit", "~> 3.1.5"
+
+  platforms :ruby do
+    gem "mysql2", "~> 0.3.20"
+  end
+end
+
+gemspec :path => "../"

data/gemfiles/ar4.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 4.2"
+
+gemspec :path => "../"

data/gemfiles/ar5.gemfile

@@ -0,0 +1,13 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "5.0.0.beta3"
+gem "activemodel", "5.0.0.beta3"
+gem "actionpack", "5.0.0.beta3"
+gem "railties", "5.0.0.beta3"
+gem "rspec-rails", "3.5.0.beta3"
+gem "rails-controller-testing"
+gem "sinatra", :github => "sinatra/sinatra"
+
+gemspec :path => "../"

data/lib/generators/paper_trail/install_generator.rb

@@ -1,24 +1,33 @@
-require 'rails/generators'
-require 'rails/generators/active_record'
+require "rails/generators"
+require "rails/generators/active_record"
 
 module PaperTrail
+  # Installs PaperTrail in a rails app.
   class InstallGenerator < ::Rails::Generators::Base
     include ::Rails::Generators::Migration
 
-    source_root File.expand_path('../templates', __FILE__)
-    class_option :with_changes, :type => :boolean, :default => false,
-      :desc => "Store changeset (diff) with each version"
-    class_option :with_associations, :type => :boolean, :default => false,
-      :desc => "Store transactional IDs to support association restoration"
+    source_root File.expand_path("../templates", __FILE__)
+    class_option(
+      :with_changes,
+      type: :boolean,
+      default: false,
+      desc: "Store changeset (diff) with each version"
+    )
+    class_option(
+      :with_associations,
+      type: :boolean,
+      default: false,
+      desc: "Store transactional IDs to support association restoration"
+    )
 
-    desc 'Generates (but does not run) a migration to add a versions table.'
+    desc "Generates (but does not run) a migration to add a versions table."
 
     def create_migration_file
-      add_paper_trail_migration('create_versions')
-      add_paper_trail_migration('add_object_changes_to_versions') if options.with_changes?
+      add_paper_trail_migration("create_versions")
+      add_paper_trail_migration("add_object_changes_to_versions") if options.with_changes?
       if options.with_associations?
-        add_paper_trail_migration('create_version_associations')
-        add_paper_trail_migration('add_transaction_id_column_to_versions')
+        add_paper_trail_migration("create_version_associations")
+        add_paper_trail_migration("add_transaction_id_column_to_versions")
       end
     end
 
@@ -27,14 +36,13 @@ module PaperTrail
     end
 
     protected
-    def add_paper_trail_migration(template)
-      migration_dir = File.expand_path('db/migrate')
 
-      unless self.class.migration_exists?(migration_dir, template)
-        migration_template "#{template}.rb", "db/migrate/#{template}.rb"
+    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
-        warn("ALERT: Migration already exists named '#{template}'." +
-               " Please check your migrations directory before re-running")
+        migration_template "#{template}.rb", "db/migrate/#{template}.rb"
       end
     end
   end

data/lib/generators/paper_trail/templates/add_object_changes_to_versions.rb

@@ -1,5 +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
-
   # 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/templates/add_transaction_id_column_to_versions.rb

@@ -1,3 +1,5 @@
+# This migration and CreateVersionAssociations provide the necessary
+# schema for tracking associations.
 class AddTransactionIdColumnToVersions < ActiveRecord::Migration
   def self.up
     add_column :versions, :transaction_id, :integer

data/lib/generators/paper_trail/templates/create_version_associations.rb

@@ -1,17 +1,22 @@
+# This migration and AddTransactionIdColumnToVersions provide the necessary
+# schema for tracking associations.
 class CreateVersionAssociations < ActiveRecord::Migration
   def self.up
     create_table :version_associations do |t|
       t.integer  :version_id
-      t.string   :foreign_key_name, :null => false
+      t.string   :foreign_key_name, null: false
       t.integer  :foreign_key_id
     end
     add_index :version_associations, [:version_id]
-    add_index :version_associations, [:foreign_key_name, :foreign_key_id], :name => 'index_version_associations_on_foreign_key'
+    add_index :version_associations,
+      [:foreign_key_name, :foreign_key_id],
+      name: "index_version_associations_on_foreign_key"
   end
 
   def self.down
     remove_index :version_associations, [:version_id]
-    remove_index :version_associations, :name => 'index_version_associations_on_foreign_key'
+    remove_index :version_associations,
+      name: "index_version_associations_on_foreign_key"
     drop_table :version_associations
   end
-end
+end

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

@@ -1,4 +1,13 @@
+# This migration creates the `versions` table, the only schema PT requires.
+# All other migrations PT provides are optional.
 class CreateVersions < ActiveRecord::Migration
+  # 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
 
   # The largest text column available in all supported RDBMS is
   # 1024^3 - 1 bytes, roughly one gibibyte.  We specify a size
@@ -7,14 +16,53 @@ class CreateVersions < ActiveRecord::Migration
   TEXT_BYTES = 1_073_741_823
 
   def change
-    create_table :versions do |t|
-      t.string   :item_type, :null => false
-      t.integer  :item_id,   :null => false
-      t.string   :event,     :null => false
+    create_table :versions, versions_table_options do |t|
+      t.string   :item_type, null: false
+      t.integer  :item_id,   null: false
+      t.string   :event,     null: false
       t.string   :whodunnit
-      t.text     :object,    :limit => TEXT_BYTES
+      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 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, [:item_type, :item_id]
   end
+
+  private
+
+  # 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_ADAPTERS.include?(connection.class.name)
+      { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }
+    else
+      {}
+    end
+  end
 end

data/lib/paper_trail/attribute_serializers/README.md

@@ -0,0 +1,10 @@
+Attribute Serializers
+=====================
+
+"Serialization" here refers to the preparation of data for insertion into a
+database, particularly the `object` and `object_changes` columns in the
+`versions` table.
+
+Likewise, "deserialization" refers to any processing of data after they
+have been read from the database, for example preparing the result of
+`VersionConcern#changeset`.

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -0,0 +1,58 @@
+module PaperTrail
+  # :nodoc:
+  module AttributeSerializers
+    # 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. In older versions of rails, we shim this method
+    # with `LegacyActiveRecordShim`.
+    if ::ActiveRecord::VERSION::MAJOR >= 5
+      # This implementation uses AR 5's `serialize` and `deserialize`.
+      class CastAttributeSerializer
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def serialize(attr, val)
+          @klass.type_for_attribute(attr).serialize(val)
+        end
+
+        def deserialize(attr, val)
+          @klass.type_for_attribute(attr).deserialize(val)
+        end
+      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 initialize(klass)
+          @klass = klass
+        end
+
+        def serialize(attr, val)
+          val = defined_enums[attr][val] if defined_enums[attr]
+          @klass.type_for_attribute(attr).type_cast_for_database(val)
+        end
+
+        def deserialize(attr, val)
+          val = @klass.type_for_attribute(attr).type_cast_from_database(val)
+          if defined_enums[attr]
+            defined_enums[attr].key(val)
+          else
+            val
+          end
+        end
+
+        private
+
+        def defined_enums
+          @defined_enums ||= (@klass.respond_to?(:defined_enums) ? @klass.defined_enums : {})
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/legacy_active_record_shim.rb

@@ -0,0 +1,48 @@
+module PaperTrail
+  module AttributeSerializers
+    # Included into model if AR version is < 4.2. Backport Rails 4.2 and later's
+    # `type_for_attribute` so we can build on a common interface.
+    module LegacyActiveRecordShim
+      # An attribute which needs no processing. It is part of our backport (shim)
+      # of rails 4.2's attribute API. See `type_for_attribute` below.
+      class NoOpAttribute
+        def type_cast_for_database(value)
+          value
+        end
+
+        def type_cast_from_database(data)
+          data
+        end
+      end
+      NO_OP_ATTRIBUTE = NoOpAttribute.new
+
+      # An attribute which requires manual (de)serialization to/from what we get
+      # from the database. It is part of our backport (shim) of rails 4.2's
+      # attribute API. See `type_for_attribute` below.
+      class SerializedAttribute
+        def initialize(coder)
+          @coder = coder.respond_to?(:dump) ? coder : PaperTrail.serializer
+        end
+
+        def type_cast_for_database(value)
+          @coder.dump(value)
+        end
+
+        def type_cast_from_database(data)
+          @coder.load(data)
+        end
+      end
+
+      def type_for_attribute(attr_name)
+        serialized_attribute_types[attr_name.to_s] || NO_OP_ATTRIBUTE
+      end
+
+      def serialized_attribute_types
+        @attribute_types ||= Hash[serialized_attributes.map do |attr_name, coder|
+          [attr_name, SerializedAttribute.new(coder)]
+        end]
+      end
+      private :serialized_attribute_types
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/object_attribute.rb

@@ -0,0 +1,39 @@
+require "paper_trail/attribute_serializers/cast_attribute_serializer"
+
+module PaperTrail
+  module AttributeSerializers
+    # Serialize or deserialize the `version.object` column.
+    class ObjectAttribute
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      def serialize(attributes)
+        alter(attributes, :serialize)
+      end
+
+      def deserialize(attributes)
+        alter(attributes, :deserialize)
+      end
+
+      private
+
+      # Modifies `attributes` in place.
+      # TODO: Return a new hash instead.
+      def alter(attributes, serialization_method)
+        # Don't serialize before values before inserting into columns of type
+        # `JSON` on `PostgreSQL` databases.
+        return attributes if object_col_is_json?
+
+        serializer = CastAttributeSerializer.new(@model_class)
+        attributes.each do |key, value|
+          attributes[key] = serializer.send(serialization_method, key, value)
+        end
+      end
+
+      def object_col_is_json?
+        @model_class.paper_trail_version_class.object_col_is_json?
+      end
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/object_changes_attribute.rb

@@ -0,0 +1,42 @@
+require "paper_trail/attribute_serializers/cast_attribute_serializer"
+
+module PaperTrail
+  module AttributeSerializers
+    # Serialize or deserialize the `version.object_changes` column.
+    class ObjectChangesAttribute
+      def initialize(item_class)
+        @item_class = item_class
+      end
+
+      def serialize(changes)
+        alter(changes, :serialize)
+      end
+
+      def deserialize(changes)
+        alter(changes, :deserialize)
+      end
+
+      private
+
+      # Modifies `changes` in place.
+      # TODO: Return a new hash instead.
+      def alter(changes, serialization_method)
+        # Don't serialize before values before inserting into columns of type
+        # `JSON` on `PostgreSQL` databases.
+        return changes if object_changes_col_is_json?
+
+        serializer = CastAttributeSerializer.new(@item_class)
+        changes.clone.each do |key, change|
+          # `change` is an Array with two elements, representing before and after.
+          changes[key] = Array(change).map do |value|
+            serializer.send(serialization_method, key, value)
+          end
+        end
+      end
+
+      def object_changes_col_is_json?
+        @item_class.paper_trail_version_class.object_changes_col_is_json?
+      end
+    end
+  end
+end

data/lib/paper_trail/cleaner.rb

@@ -1,35 +1,58 @@
 module PaperTrail
+  # Utilities for deleting version records.
   module Cleaner
-    # Destroys all but the most recent version(s) for items on a given date (or on all dates). Useful for deleting drafts.
+    # Destroys all but the most recent version(s) for items on a given date
+    # (or on all dates). Useful for deleting drafts.
     #
     # Options:
-    # :keeping      An `integer` indicating the number of versions to be kept for each item per date.
-    #               Defaults to `1`.
-    # :date         Should either be a `Date` object specifying which date to destroy versions for or `:all`,
-    #               which will specify that all dates should be cleaned. Defaults to `:all`.
-    # :item_id      The `id` for the item to be cleaned on, or `nil`, which causes all items to be cleaned.
-    #               Defaults to `nil`.
+    #
+    # - :keeping - An `integer` indicating the number of versions to be kept for
+    #   each item per date. Defaults to `1`. The most recent matching versions
+    #   are kept.
+    # - :date - Should either be a `Date` object specifying which date to
+    #   destroy versions for or `:all`, which will specify that all dates
+    #   should be cleaned. Defaults to `:all`.
+    # - :item_id - The `id` for the item to be cleaned on, or `nil`, which
+    #   causes all items to be cleaned. Defaults to `nil`.
+    #
     def clean_versions!(options = {})
-      options = {:keeping => 1, :date => :all}.merge(options)
-      gather_versions(options[:item_id], options[:date]).each do |item_id, versions|
-        versions.group_by { |v| v.send(PaperTrail.timestamp_field).to_date }.each do |date, _versions|
-          # remove the number of versions we wish to keep from the collection of versions prior to destruction
-          _versions.pop(options[:keeping])
-          _versions.map(&:destroy)
+      options = { keeping: 1, date: :all }.merge(options)
+      gather_versions(options[:item_id], options[:date]).each do |_item_id, item_versions|
+        group_versions_by_date(item_versions).each do |_date, date_versions|
+          # Remove the number of versions we wish to keep from the collection
+          # of versions prior to destruction.
+          date_versions.pop(options[:keeping])
+          date_versions.map(&:destroy)
         end
       end
     end
 
     private
 
-    # Returns a hash of versions grouped by the `item_id` attribute formatted like this: {:item_id => PaperTrail::Version}.
-    # If `item_id` or `date` is set, versions will be narrowed to those pointing at items with those ids that were created on specified date.
+    # Returns a hash of versions grouped by the `item_id` attribute formatted
+    # like this: {:item_id => PaperTrail::Version}. If `item_id` or `date` is
+    # set, versions will be narrowed to those pointing at items with those ids
+    # that were created on specified date. Versions are returned in
+    # chronological order.
     def gather_versions(item_id = nil, date = :all)
-      raise ArgumentError.new("`date` argument must receive a Timestamp or `:all`") unless date == :all || date.respond_to?(:to_date)
-      versions = item_id ? PaperTrail::Version.where(:item_id => item_id) : PaperTrail::Version
+      unless date == :all || date.respond_to?(:to_date)
+        raise ArgumentError, "Expected date to be a Timestamp or :all"
+      end
+      versions = item_id ? PaperTrail::Version.where(item_id: item_id) : PaperTrail::Version
+      versions = versions.order(PaperTrail::Version.timestamp_sort_order)
       versions = versions.between(date.to_date, date.to_date + 1.day) unless date == :all
-      versions = PaperTrail::Version.all if versions == PaperTrail::Version # if versions has not been converted to an ActiveRecord::Relation yet, do so now
+
+      # If `versions` has not been converted to an ActiveRecord::Relation yet,
+      # do so now.
+      versions = PaperTrail::Version.all if versions == PaperTrail::Version
       versions.group_by(&:item_id)
     end
+
+    # Given an array of versions, returns a hash mapping dates to arrays of
+    # versions.
+    # @api private
+    def group_versions_by_date(versions)
+      versions.group_by { |v| v.send(PaperTrail.timestamp_field).to_date }
+    end
   end
 end