paper_trail 1.4.0 → 17.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ce4b87054886d17b9dea51dfcf6e9ddc948eaf331417b8dc5b992793e177a670
+  data.tar.gz: 32f2ff0f24978fe54e08a65dfe8c83ec023eaaf9ab676c0f791b398907a8fc80
+SHA512:
+  metadata.gz: 772518531867cafb80017ebbb42837412fc67b80ec9416cfc9269595084e266f312609115171868b4124747769f1aba03fd5ee1b932691b52128aaec6fa2c583
+  data.tar.gz: 3b28ed9bbbf1fef2eac6d106c5fedcb1566b88d7877782e115130f4f8386f5e6bf60f4123edc1518e41478b918fac9c371c98fea5e0b49745fcd384cffa85baa

data/lib/generators/paper_trail/install/USAGE

@@ -0,0 +1,31 @@
+Description:
+  Generates (but does not run) a migration to add a versions table. Also generates an initializer
+  file for configuring PaperTrail. Can be customized by providing a Version class name.
+  See section 5.c. Generators in README.md for more information.
+
+Examples:
+  rails generate paper_trail:install
+
+  This will create:
+    db/migrate/[TIMESTAMP]_create_versions.rb
+    config/initializers/paper_trail.rb
+
+  rails generate paper_trail:install --with-changes
+
+  This will create:
+    db/migrate/[TIMESTAMP]_create_versions.rb
+    db/migrate/[TIMESTAMP]_add_object_changes_to_versions.rb
+    config/initializers/paper_trail.rb
+
+  rails generate paper_trail:install CommentVersion
+
+  This will create:
+    db/migrate/[TIMESTAMP]_create_comment_versions.rb
+    config/initializers/paper_trail.rb
+
+  rails generate paper_trail:install ProductVersion --with-changes --uuid
+
+  This will create:
+    db/migrate/[TIMESTAMP]_create_product_versions.rb
+    db/migrate/[TIMESTAMP]_add_object_changes_to_product_versions.rb
+    config/initializers/paper_trail.rb

data/lib/generators/paper_trail/install/install_generator.rb

@@ -0,0 +1,101 @@
+# 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"
+    )
+    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. " \
+         "Can be customized by providing a Version class name. " \
+         "See section 5.c. Generators in README.md for more information."
+
+    def create_migration_file
+      # Use the table_name to create the proper migration filename
+      add_paper_trail_migration(
+        "create_#{table_name}",
+        item_type_options: item_type_options,
+        versions_table_options: versions_table_options,
+        item_id_type_options: item_id_type_options,
+        version_table_primary_key_type: version_table_primary_key_type
+      )
+      if options.with_changes?
+        add_paper_trail_migration("add_object_changes_to_#{table_name}")
+      end
+    end
+
+    private
+
+    # To use uuid instead of integer for primary key
+    def item_id_type_options
+      options.uuid? ? "string" : "bigint"
+    end
+
+    # To use uuid for version table primary key
+    def version_table_primary_key_type
+      if options.uuid?
+        ", id: :uuid"
+      else
+        ""
+      end
+    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
+      if mysql?
+        ", null: false, limit: 191"
+      else
+        ", null: false"
+      end
+    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 AddObjectChangesTo<%= version_class_name.pluralize %> < 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 :<%= table_name %>, :object_changes, :text, limit: TEXT_BYTES
+  end
+end

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

@@ -0,0 +1,41 @@
+# This migration creates the `<%= table_name %>` table for the <%= version_class_name %> class.
+# All other migrations PT provides are optional.
+class Create<%= version_class_name.pluralize %> < 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 :<%= table_name %><%= versions_table_options %><%= version_table_primary_key_type %> do |t|
+      # Consider using bigint type for performance if you are going to store only numeric ids.
+      # t.bigint   :whodunnit
+      t.string   :whodunnit
+
+      # 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)
+      #
+      # MySQL users should use the following line for `created_at`
+      # t.datetime :created_at, limit: 6
+      t.datetime :created_at
+
+      t.<%= item_id_type_options %>   :item_id,   null: false
+      t.string   :item_type<%= item_type_options %>
+      t.string   :event,     null: false
+      t.text     :object, limit: TEXT_BYTES
+    end
+    add_index :<%= table_name %>, %i[item_type item_id]
+  end
+end

data/lib/generators/paper_trail/migration_generator.rb

@@ -0,0 +1,65 @@
+# 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
+
+    # Define arguments for the generator
+    argument :version_class_name, type: :string, default: "Version",
+      desc: "The name of the Version class (e.g., CommentVersion)"
+
+    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
+        # Map the dynamic template name to the actual template file
+        template_file = map_template_name(template)
+
+        migration_template(
+          "#{template_file}.rb.erb",
+          "db/migrate/#{template}.rb",
+          {
+            migration_version: migration_version,
+            table_name: table_name,
+            version_class_name: version_class_name
+          }.merge(extra_options)
+        )
+      end
+    end
+
+    def migration_version
+      format(
+        "[%d.%d]",
+        ActiveRecord::VERSION::MAJOR,
+        ActiveRecord::VERSION::MINOR
+      )
+    end
+
+    # Convert Version class name to table name using Rails conventions
+    def table_name
+      version_class_name.underscore.pluralize
+    end
+
+    # Map the dynamic template name to the actual template file
+    def map_template_name(template)
+      if template.start_with?("create_")
+        "create_versions"
+      elsif template.start_with?("add_object_changes_to_")
+        "add_object_changes_to_versions"
+      else
+        template
+      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,86 @@
+# 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 Update<%= version_class_name.pluralize %>ForItemSubtype < 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 = ""
+  # Use @hints over args to not break the test itself since args could now include --version_class_name=CommentVersion
+  hints = (@hints || []).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 = <%= fully_qualified_version_class_name %>.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
+        <%= fully_qualified_version_class_name %>.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 += <%= fully_qualified_version_class_name %>.where(id: block_of_ids).update_all(item_subtype: k)
+          block_of_ids = []
+        end
+      end
+      num_updated += <%= fully_qualified_version_class_name %>.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,40 @@
+# 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__)
+
+    # Remove the inherited version_class_name argument as we use an option instead
+    remove_argument :version_class_name
+
+    argument :hints, type: :array, default: [], banner: "hint1 hint2"
+
+    class_option :version_class_name,
+      type: :string,
+      default: "Version",
+      aliases: ["-v"],
+      desc: "The name of the Version class (e.g., CommentVersion)"
+
+    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_#{table_name}_for_item_subtype", sti_type_options: options)
+    end
+
+    # Return the version class name from options
+    def version_class_name
+      options[:version_class_name]
+    end
+
+    # Return the fully qualified class name for use in ERB templates
+    def fully_qualified_version_class_name
+      version_class_name == "Version" ? "PaperTrail::Version" : version_class_name
+    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/attribute_serializer_factory.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "paper_trail/type_serializers/postgres_array_serializer"
+
+module PaperTrail
+  module AttributeSerializers
+    # Values returned by some Active Record serializers are
+    # 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
+      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
+
+        # @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
+  end
+end

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "paper_trail/attribute_serializers/attribute_serializer_factory"
+
+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`.
+    class CastAttributeSerializer
+      def initialize(klass)
+        @klass = klass
+      end
+
+      private
+
+      # Returns a hash mapping attributes to hashes that map strings to
+      # integers. Example:
+      #
+      # ```
+      # { "status" => { "draft"=>0, "published"=>1, "archived"=>2 } }
+      # ```
+      #
+      # ActiveRecord::Enum was added in AR 4.1
+      # http://edgeguides.rubyonrails.org/4_1_release_notes.html#active-record-enums
+      def defined_enums
+        @defined_enums ||= (@klass.respond_to?(:defined_enums) ? @klass.defined_enums : {})
+      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
+        elsif 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 serialize(attr, val)
+        AttributeSerializerFactory.for(@klass, attr).serialize(val)
+      end
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/object_attribute.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+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
+
+        # ActiveRecord since 7.0 has a built-in encryption mechanism
+        @encrypted_attributes = @model_class.encrypted_attributes&.map(&:to_s)
+      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 non-encrypted before values before inserting into columns of type
+        # `JSON` on `PostgreSQL` databases.
+        attributes_to_serialize =
+          object_col_is_json? ? attributes.slice(*@encrypted_attributes) : attributes
+        return attributes if attributes_to_serialize.blank?
+
+        serializer = CastAttributeSerializer.new(@model_class)
+        attributes_to_serialize.each do |key, value|
+          attributes[key] = serializer.send(serialization_method, key, value)
+        end
+
+        attributes
+      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,51 @@
+# frozen_string_literal: true
+
+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
+
+        # ActiveRecord since 7.0 has a built-in encryption mechanism
+        @encrypted_attributes = @item_class.encrypted_attributes&.map(&:to_s)
+      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 non-encrypted before values before inserting into columns of type
+        # `JSON` on `PostgreSQL` databases.
+        changes_to_serialize =
+          object_changes_col_is_json? ? changes.slice(*@encrypted_attributes) : changes.clone
+        return changes if changes_to_serialize.blank?
+
+        serializer = CastAttributeSerializer.new(@item_class)
+        changes_to_serialize.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
+
+        changes
+      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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # Options:
+    #
+    # - :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, 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. Versions are returned in
+    # chronological order.
+    def gather_versions(item_id = nil, date = :all)
+      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
+
+      # 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.created_at.to_date }
+    end
+  end
+end