mongo_trails 10.3.1

data/lib/mongo_trails/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/mongo_trails/attribute_serializers/attribute_serializer_factory.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "mongo_trails/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.
+    module AttributeSerializerFactory
+      AR_PG_ARRAY_CLASS = "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array"
+
+      def self.for(klass, attr)
+        active_record_serializer = klass.type_for_attribute(attr)
+        if active_record_serializer.class.name == AR_PG_ARRAY_CLASS
+          TypeSerializers::PostgresArraySerializer.new(
+            active_record_serializer.subtype,
+            active_record_serializer.delimiter
+          )
+        else
+          active_record_serializer
+        end
+      end
+    end
+  end
+end

data/lib/mongo_trails/attribute_serializers/cast_attribute_serializer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "mongo_trails/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`.
+    #
+    # This implementation depends on the `type_for_attribute` method, which was
+    # introduced in rails 4.2. As of PT 8, we no longer support rails < 4.2.
+    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
+    end
+
+    # Uses AR 5's `serialize` and `deserialize`.
+    class CastAttributeSerializer
+      def serialize(attr, val)
+        AttributeSerializerFactory.for(@klass, attr).serialize(val)
+      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
+        else
+          AttributeSerializerFactory.for(@klass, attr).deserialize(val)
+        end
+      end
+    end
+  end
+end

data/lib/mongo_trails/attribute_serializers/object_attribute.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mongo_trails/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/mongo_trails/attribute_serializers/object_changes_attribute.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "mongo_trails/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/mongo_trails/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

data/lib/mongo_trails/compatibility.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Rails does not follow SemVer, makes breaking changes in minor versions.
+  # Breaking changes are expected, and are generally good for the rails
+  # ecosystem. However, they often require dozens of hours to fix, even with the
+  # [help of experts](https://github.com/paper-trail-gem/mongo_trails/pull/899).
+  #
+  # It is not safe to assume that a new version of rails will be compatible with
+  # PaperTrail. PT is only compatible with the versions of rails that it is
+  # tested against. See `.travis.yml`.
+  #
+  # However, as of
+  # [#1213](https://github.com/paper-trail-gem/mongo_trails/pull/1213) our
+  # gemspec allows installation with newer, incompatible rails versions. We hope
+  # this will make it easier for contributors to work on compatibility with
+  # newer rails versions. Most PT users should avoid incompatible rails
+  # versions.
+  module Compatibility
+    ACTIVERECORD_GTE = ">= 5.2" # enforced in gemspec
+    ACTIVERECORD_LT = "< 6.1" # not enforced in gemspec
+
+    E_INCOMPATIBLE_AR = <<-EOS
+      PaperTrail %s is not compatible with ActiveRecord %s. We allow PT
+      contributors to install incompatible versions of ActiveRecord, and this
+      warning can be silenced with an environment variable, but this is a bad
+      idea for normal use. Please install a compatible version of ActiveRecord
+      instead (%s). Please see the discussion in mongo_trails/compatibility.rb
+      for details.
+    EOS
+
+    # Normal users need a warning if they accidentally install an incompatible
+    # version of ActiveRecord. Contributors can silence this warning with an
+    # environment variable.
+    def self.check_activerecord(ar_version)
+      raise ::TypeError unless ar_version.instance_of?(::Gem::Version)
+      return if ::ENV["PT_SILENCE_AR_COMPAT_WARNING"].present?
+      req = ::Gem::Requirement.new([ACTIVERECORD_GTE, ACTIVERECORD_LT])
+      unless req.satisfied_by?(ar_version)
+        ::Kernel.warn(
+          format(
+            E_INCOMPATIBLE_AR,
+            ::PaperTrail.gem_version,
+            ar_version,
+            req
+          )
+        )
+      end
+    end
+  end
+end

data/lib/mongo_trails/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "mongo_trails/serializers/yaml"
+
+module PaperTrail
+  # Global configuration affecting all threads. Some thread-specific
+  # configuration can be found in `paper_trail.rb`, others in `controller.rb`.
+  class Config
+    include Singleton
+
+    attr_accessor(
+      :association_reify_error_behaviour,
+      :object_changes_adapter,
+      :serializer,
+      :version_limit,
+      :has_paper_trail_defaults,
+      :mongo_config,
+      :mongo_prefix
+    )
+
+    def initialize
+      # Variables which affect all threads, whose access is synchronized.
+      @mutex = Mutex.new
+      @enabled = true
+
+      # Variables which affect all threads, whose access is *not* synchronized.
+      @serializer = PaperTrail::Serializers::YAML
+      @has_paper_trail_defaults = {}
+    end
+
+    # Indicates whether PaperTrail is on or off. Default: true.
+    def enabled
+      @mutex.synchronize { !!@enabled }
+    end
+
+    def enabled=(enable)
+      @mutex.synchronize { @enabled = enable }
+    end
+  end
+end

data/lib/mongo_trails/events/base.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Events
+    # We refer to times in the lifecycle of a record as "events". There are
+    # three events:
+    #
+    # - create
+    #   - `after_create` we call `RecordTrail#record_create`
+    # - update
+    #   - `after_update` we call `RecordTrail#record_update`
+    #   - `after_touch` we call `RecordTrail#record_update`
+    #   - `RecordTrail#save_with_version` calls `RecordTrail#record_update`
+    #   - `RecordTrail#update_columns` is also referred to as an update, though
+    #     it uses `RecordTrail#record_update_columns` rather than
+    #     `RecordTrail#record_update`
+    # - destroy
+    #   - `before_destroy` or `after_destroy` we call `RecordTrail#record_destroy`
+    #
+    # The value inserted into the `event` column of the versions table can also
+    # be overridden by the user, with `paper_trail_event`.
+    #
+    # @api private
+    class Base
+      RAILS_GTE_5_1 = ::ActiveRecord.gem_version >= ::Gem::Version.new("5.1.0.beta1")
+
+      # @api private
+      def initialize(record, in_after_callback)
+        @record = record
+        @in_after_callback = in_after_callback
+      end
+
+      # Determines whether it is appropriate to generate a new version
+      # instance. A timestamp-only update (e.g. only `updated_at` changed) is
+      # considered notable unless an ignored attribute was also changed.
+      #
+      # @api private
+      def changed_notably?
+        if ignored_attr_has_changed?
+          timestamps = @record.send(:timestamp_attributes_for_update_in_model).map(&:to_s)
+          (notably_changed - timestamps).any?
+        else
+          notably_changed.any?
+        end
+      end
+
+      private
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/mongo_trails/pull/899
+      #
+      # @api private
+      def attribute_changed_in_latest_version?(attr_name)
+        if @in_after_callback && RAILS_GTE_5_1
+          @record.saved_change_to_attribute?(attr_name.to_s)
+        else
+          @record.attribute_changed?(attr_name.to_s)
+        end
+      end
+
+      # @api private
+      def nonskipped_attributes_before_change(is_touch)
+        cache_changed_attributes do
+          record_attributes = @record.attributes.except(*@record.paper_trail_options[:skip])
+
+          record_attributes.each_key do |k|
+            if @record.class.column_names.include?(k)
+              record_attributes[k] = attribute_in_previous_version(k, is_touch)
+            end
+          end
+        end
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`.
+      # @api private
+      def cache_changed_attributes
+        if RAILS_GTE_5_1
+          # Everything works fine as it is
+          yield
+        else
+          # Any particular call to `changed_attributes` produces the huge memory allocation.
+          # Lets use the generic AR workaround for that.
+          @record.send(:cache_changed_attributes) { yield }
+        end
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/mongo_trails/pull/899
+      #
+      # Event can be any of the three (create, update, destroy).
+      #
+      # @api private
+      def attribute_in_previous_version(attr_name, is_touch)
+        if RAILS_GTE_5_1
+          if @in_after_callback && !is_touch
+            # For most events, we want the original value of the attribute, before
+            # the last save.
+            @record.attribute_before_last_save(attr_name.to_s)
+          else
+            # We are either performing a `record_destroy` or a
+            # `record_update(is_touch: true)`.
+            @record.attribute_in_database(attr_name.to_s)
+          end
+        else
+          @record.attribute_was(attr_name.to_s)
+        end
+      end
+
+      # @api private
+      def calculated_ignored_array
+        ignore = @record.paper_trail_options[:ignore].dup
+        # Remove Hash arguments and then evaluate whether the attributes (the
+        # keys of the hash) should also get pushed into the collection.
+        ignore.delete_if do |obj|
+          obj.is_a?(Hash) &&
+            obj.each { |attr, condition|
+              ignore << attr if condition.respond_to?(:call) && condition.call(@record)
+            }
+        end
+      end
+
+      # @api private
+      def changed_and_not_ignored
+        skip = @record.paper_trail_options[:skip]
+        (changed_in_latest_version - calculated_ignored_array) - skip
+      end
+
+      # @api private
+      def changed_in_latest_version
+        # Memoized to reduce memory usage
+        @changed_in_latest_version ||= changes_in_latest_version.keys
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/mongo_trails/pull/899
+      #
+      # @api private
+      def changes_in_latest_version
+        # Memoized to reduce memory usage
+        @changes_in_latest_version ||= begin
+          if @in_after_callback && RAILS_GTE_5_1
+            @record.saved_changes
+          else
+            @record.changes
+          end
+        end
+      end
+
+      # An attributed is "ignored" if it is listed in the `:ignore` option
+      # and/or the `:skip` option.  Returns true if an ignored attribute has
+      # changed.
+      #
+      # @api private
+      def ignored_attr_has_changed?
+        ignored = calculated_ignored_array + @record.paper_trail_options[:skip]
+        ignored.any? && (changed_in_latest_version & ignored).any?
+      end
+
+      # PT 10 has a new optional column, `item_subtype`
+      #
+      # @api private
+      def merge_item_subtype_into(data)
+        if @record.class.paper_trail.version_class.fields.key?("item_subtype")
+          data.merge!(item_subtype: @record.class.name)
+        end
+      end
+
+      # Updates `data` from the model's `meta` option and from `controller_info`.
+      # Metadata is always recorded; that means all three events (create, update,
+      # destroy) and `update_columns`.
+      #
+      # @api private
+      def merge_metadata_into(data)
+        merge_metadata_from_model_into(data)
+        merge_metadata_from_controller_into(data)
+      end
+
+      # Updates `data` from `controller_info`.
+      #
+      # @api private
+      def merge_metadata_from_controller_into(data)
+        data.merge(PaperTrail.request.controller_info || {})
+      end
+
+      # Updates `data` from the model's `meta` option.
+      #
+      # @api private
+      def merge_metadata_from_model_into(data)
+        @record.paper_trail_options[:meta].each do |k, v|
+          data[k] = model_metadatum(v, data[:event])
+        end
+      end
+
+      # Given a `value` from the model's `meta` option, returns an object to be
+      # persisted. The `value` can be a simple scalar value, but it can also
+      # be a symbol that names a model method, or even a Proc.
+      #
+      # @api private
+      def model_metadatum(value, event)
+        if value.respond_to?(:call)
+          value.call(@record)
+        elsif value.is_a?(Symbol) && @record.respond_to?(value, true)
+          # If it is an attribute that is changing in an existing object,
+          # be sure to grab the current version.
+          if event != "create" &&
+              @record.has_attribute?(value) &&
+              attribute_changed_in_latest_version?(value)
+            attribute_in_previous_version(value, false)
+          else
+            @record.send(value)
+          end
+        else
+          value
+        end
+      end
+
+      # @api private
+      def notable_changes
+        changes_in_latest_version.delete_if { |k, _v|
+          !notably_changed.include?(k)
+        }
+      end
+
+      # @api private
+      def notably_changed
+        # Memoized to reduce memory usage
+        @notably_changed ||= begin
+          only = @record.paper_trail_options[:only].dup
+          # Remove Hash arguments and then evaluate whether the attributes (the
+          # keys of the hash) should also get pushed into the collection.
+          only.delete_if do |obj|
+            obj.is_a?(Hash) &&
+              obj.each { |attr, condition|
+                only << attr if condition.respond_to?(:call) && condition.call(@record)
+              }
+          end
+          only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
+        end
+      end
+
+      # Returns hash of attributes (with appropriate attributes serialized),
+      # omitting attributes to be skipped.
+      #
+      # @api private
+      def object_attrs_for_paper_trail(is_touch)
+        attrs = nonskipped_attributes_before_change(is_touch)
+        AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs)
+        attrs
+      end
+
+      # @api private
+      def prepare_object_changes(changes)
+        changes = serialize_object_changes(changes)
+        recordable_object_changes(changes)
+      end
+
+      # Returns an object which can be assigned to the `object_changes`
+      # attribute of a nascent version record. If the `object_changes` column is
+      # a postgres `json` column, then a hash can be used in the assignment,
+      # otherwise the column is a `text` column, and we must perform the
+      # serialization here, using `PaperTrail.serializer`.
+      #
+      # @api private
+      # @param changes HashWithIndifferentAccess
+      def recordable_object_changes(changes)
+        if PaperTrail.config.object_changes_adapter&.respond_to?(:diff)
+          # We'd like to avoid the `to_hash` here, because it increases memory
+          # usage, but that would be a breaking change because
+          # `object_changes_adapter` expects a plain `Hash`, not a
+          # `HashWithIndifferentAccess`.
+          changes = PaperTrail.config.object_changes_adapter.diff(changes.to_hash)
+        end
+
+        if @record.class.paper_trail.version_class.object_changes_col_is_json?
+          changes
+        else
+          PaperTrail.serializer.dump(changes)
+        end
+      end
+
+      # Returns a boolean indicating whether to store serialized version diffs
+      # in the `object_changes` column of the version record.
+      #
+      # @api private
+      def record_object_changes?
+        @record.class.paper_trail.version_class.fields.keys.include?("object_changes")
+      end
+
+      # Returns a boolean indicating whether to store the original object during save.
+      #
+      # @api private
+      def record_object?
+        @record.class.paper_trail.version_class.fields.keys.include?("object")
+      end
+
+      # Returns an object which can be assigned to the `object` attribute of a
+      # nascent version record. If the `object` column is a postgres `json`
+      # column, then a hash can be used in the assignment, otherwise the column
+      # is a `text` column, and we must perform the serialization here, using
+      # `PaperTrail.serializer`.
+      #
+      # @api private
+      def recordable_object(is_touch)
+        if @record.class.paper_trail.version_class.object_col_is_json?
+          object_attrs_for_paper_trail(is_touch)
+        else
+          PaperTrail.serializer.dump(object_attrs_for_paper_trail(is_touch))
+        end
+      end
+
+      # @api private
+      def serialize_object_changes(changes)
+        AttributeSerializers::ObjectChangesAttribute.
+          new(@record.class).
+          serialize(changes)
+
+        # We'd like to convert this `HashWithIndifferentAccess` to a plain
+        # `Hash`, but we don't, to save memory.
+        changes
+      end
+    end
+  end
+end