paper_trail 3.0.6 → 4.2.0

data/Rakefile

@@ -4,7 +4,7 @@ Bundler::GemHelper.install_tasks
 desc 'Set a relevant database.yml for testing'
 task :prepare do
   ENV["DB"] ||= "sqlite"
-  if RUBY_VERSION.to_f >= 1.9
+  if RUBY_VERSION >= '1.9'
     FileUtils.cp "test/dummy/config/database.#{ENV["DB"]}.yml", "test/dummy/config/database.yml"
   else
     require 'ftools'
@@ -23,7 +23,7 @@ Rake::TestTask.new(:test) do |t|
 end
 
 require 'rspec/core/rake_task'
-desc 'Run PaperTrail specs for the RSpec helper.'
+desc 'Run tests on PaperTrail with RSpec'
 RSpec::Core::RakeTask.new(:spec)
 
 desc 'Default: run all available test suites'

data/doc/bug_report_template.rb

@@ -0,0 +1,65 @@
+# 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)
+require 'paper_trail'
+
+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
+
+class User < ActiveRecord::Base
+  has_paper_trail
+end
+
+class BugTest < ActiveSupport::TestCase
+  def test_1
+    assert_difference(-> { PaperTrail::Version.count }, +1) {
+      User.create(first_name: "Jane")
+    }
+  end
+end

data/gemfiles/ar3.gemfile

@@ -0,0 +1,61 @@
+source 'https://rubygems.org'
+
+gem 'activerecord', '3.2.22.2'
+gem 'request_store', '~> 1.1.0'
+
+# i18n 0.7 requires ruby >= 1.9.3, but we still support 1.8.7
+gem 'i18n', '< 0.7'
+
+# actionpack 3 depends on rack-cache ~> 1.2, but bundler seems to ignore that.
+# Also rack-cache 1.3 dropped support for ruby 1.8.7. The simplest thing for now
+# was to specify rack-cache ~> 1.2 here, though it should be unnecessary given
+# the actionpack 3 dependency.
+gem 'rack-cache', '~> 1.2.0'
+
+group :development, :test do
+  gem 'rake', '~> 10.1.1'
+  gem 'shoulda', '~> 3.5'
+  gem 'ffaker',  '<= 1.31.0'
+
+  # Testing of Sinatra
+  gem 'sinatra', '~> 1.1.4'
+
+  # RSpec testing
+  gem 'rspec-rails', '~> 3.4.2'
+  gem 'generator_spec'
+
+  # To do proper transactional testing with ActiveSupport::TestCase on MySQL
+  gem 'database_cleaner', '~> 1.2.0'
+
+  # Allow time travel in testing. timecop is only supported after 1.9.2 but does a better cleanup at 'return'
+  if RUBY_VERSION < "1.9.2"
+    gem 'delorean'
+  else
+    gem 'timecop'
+  end
+
+  platforms :ruby do
+    gem 'sqlite3', '~> 1.2'
+
+    # We would prefer to only constrain mysql2 to '~> 0.3',
+    # but a rails bug (https://github.com/rails/rails/issues/21544)
+    # requires us to constrain to '~> 0.3.20' for now.
+    gem 'mysql2', '~> 0.3.20'
+
+    gem 'pg', '~> 0.17.1'
+  end
+
+  platforms :jruby, :ruby_18 do
+    # shoulda-matchers > 2.0 is not compatible with Ruby18.
+    # Since we can't specify difference between JRuby 18/19, we need to use shoulda-matchers 1.5 for all JRuby testing.
+    gem 'shoulda-matchers', '~> 1.5'
+  end
+
+  platforms :jruby do
+    # Use jRuby's sqlite3 adapter for jRuby
+    gem 'activerecord-jdbcsqlite3-adapter', '~> 1.3'
+    gem 'activerecord-jdbcpostgresql-adapter', '~> 1.3'
+    gem 'activerecord-jdbcmysql-adapter', '~> 1.3'
+    gem 'activerecord-jdbc-adapter', '1.3.15'
+  end
+end

data/lib/generators/paper_trail/install_generator.rb

@@ -6,17 +6,36 @@ module PaperTrail
     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_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.'
 
     def create_migration_file
-      migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
-      migration_template 'add_object_changes_to_versions.rb', 'db/migrate/add_object_changes_to_versions.rb' 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')
+      end
     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')
+
+      unless self.class.migration_exists?(migration_dir, template)
+        migration_template "#{template}.rb", "db/migrate/#{template}.rb"
+      else
+        warn("ALERT: Migration already exists named '#{template}'." +
+               " Please check your migrations directory before re-running")
+      end
+    end
   end
 end

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

@@ -1,5 +1,10 @@
 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
+
   def change
-    add_column :versions, :object_changes, :text
+    add_column :versions, :object_changes, :text, :limit => TEXT_BYTES
   end
 end

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

@@ -0,0 +1,11 @@
+class AddTransactionIdColumnToVersions < ActiveRecord::Migration
+  def self.up
+    add_column :versions, :transaction_id, :integer
+    add_index :versions, [:transaction_id]
+  end
+
+  def self.down
+    remove_index :versions, [:transaction_id]
+    remove_column :versions, :transaction_id
+  end
+end

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

@@ -0,0 +1,17 @@
+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.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
+
+  def self.down
+    remove_index :version_associations, [:version_id]
+    remove_index :version_associations, :name => 'index_version_associations_on_foreign_key'
+    drop_table :version_associations
+  end
+end

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

@@ -1,11 +1,32 @@
 class CreateVersions < ActiveRecord::Migration
+
+  # 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 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
+      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]

data/lib/paper_trail.rb

@@ -1,4 +1,6 @@
-# Require core library
+require 'request_store'
+
+# Require files in lib/paper_trail, but not its subdirectories.
 Dir[File.join(File.dirname(__FILE__), 'paper_trail', '*.rb')].each do |file|
   require File.join('paper_trail', File.basename(file, '.rb'))
 end
@@ -22,6 +24,14 @@ module PaperTrail
     !!PaperTrail.config.enabled
   end
 
+  def self.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.
   def self.enabled_for_controller=(value)
     paper_trail_store[:request_enabled_for_controller] = value
@@ -34,12 +44,14 @@ module PaperTrail
     !!paper_trail_store[:request_enabled_for_controller]
   end
 
-  # Sets whether PaperTrail is enabled or disabled for this model in the current request.
+  # 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.
+  # 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
@@ -54,10 +66,9 @@ module PaperTrail
     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`.
+  # 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
@@ -67,8 +78,8 @@ module PaperTrail
     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.
+  # 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
@@ -91,33 +102,51 @@ module PaperTrail
   end
 
   def self.active_record_protected_attributes?
-    @active_record_protected_attributes ||= ::ActiveRecord::VERSION::MAJOR < 4 || !!defined?(ProtectedAttributes)
+    @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.
+  # Thread-safe hash to hold PaperTrail's data. Initializing with needed
+  # default values.
   def self.paper_trail_store
-    Thread.current[:paper_trail] ||= { :request_enabled_for_controller => true }
+    RequestStore.store[:paper_trail] ||= { :request_enabled_for_controller => true }
   end
 
   # Returns PaperTrail's configuration object.
   def self.config
-    @@config ||= PaperTrail::Config.instance
+    @config ||= PaperTrail::Config.instance
+    yield @config if block_given?
+    @config
   end
 
-  def self.configure
-    yield config
+  class << self
+    alias_method :configure, :config
   end
 end
 
-# Ensure `ProtectedAttributes` gem gets required if it is available before the `Version` class gets loaded in
+# 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; end # will rescue if `ProtectedAttributes` gem is not available
+  rescue LoadError
+    # In case `ProtectedAttributes` gem is not available.
+  end
 end
 
 ActiveSupport.on_load(:active_record) do
@@ -125,8 +154,9 @@ ActiveSupport.on_load(:active_record) do
 end
 
 # Require frameworks
-require 'paper_trail/frameworks/active_record'
 require 'paper_trail/frameworks/sinatra'
-require 'paper_trail/frameworks/rails' if defined? Rails
-require 'paper_trail/frameworks/rspec' if defined? RSpec::Core
-require 'paper_trail/frameworks/cucumber' if defined? World
+if defined?(::Rails) && ActiveRecord::VERSION::STRING >= '3.2'
+  require 'paper_trail/frameworks/rails'
+else
+  require 'paper_trail/frameworks/active_record'
+end

data/lib/paper_trail/attributes_serialization.rb

@@ -0,0 +1,89 @@
+module PaperTrail
+  module AttributesSerialization
+    class NoOpAttribute
+      def type_cast_for_database(value)
+        value
+      end
+
+      def type_cast_from_database(data)
+        data
+      end
+    end
+    NO_OP_ATTRIBUTE = NoOpAttribute.new
+
+    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
+
+    SERIALIZE, DESERIALIZE =
+      if ::ActiveRecord::VERSION::MAJOR >= 5
+        [:serialize, :deserialize]
+      else
+        [:type_cast_for_database, :type_cast_from_database]
+      end
+
+    if ::ActiveRecord::VERSION::STRING < '4.2'
+      # Backport Rails 4.2 and later's `type_for_attribute` to build
+      # on a common interface.
+      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
+
+    # Used for `Version#object` attribute.
+    def serialize_attributes_for_paper_trail!(attributes)
+      alter_attributes_for_paper_trail!(SERIALIZE, attributes)
+    end
+
+    def unserialize_attributes_for_paper_trail!(attributes)
+      alter_attributes_for_paper_trail!(DESERIALIZE, attributes)
+    end
+
+    def alter_attributes_for_paper_trail!(serializer, attributes)
+      # Don't serialize before values before inserting into columns of type
+      # `JSON` on `PostgreSQL` databases.
+      return attributes if paper_trail_version_class.object_col_is_json?
+
+      attributes.each do |key, value|
+        attributes[key] = type_for_attribute(key).send(serializer, value)
+      end
+    end
+
+    # Used for Version#object_changes attribute.
+    def serialize_attribute_changes_for_paper_trail!(changes)
+      alter_attribute_changes_for_paper_trail!(SERIALIZE, changes)
+    end
+
+    def unserialize_attribute_changes_for_paper_trail!(changes)
+      alter_attribute_changes_for_paper_trail!(DESERIALIZE, changes)
+    end
+
+    def alter_attribute_changes_for_paper_trail!(serializer, changes)
+      # Don't serialize before values before inserting into columns of type
+      # `JSON` on `PostgreSQL` databases.
+      return changes if paper_trail_version_class.object_changes_col_is_json?
+
+      changes.clone.each do |key, change|
+        type = type_for_attribute(key)
+        changes[key] = Array(change).map { |value| type.send(serializer, value) }
+      end
+    end
+  end
+end