mongo_trails 10.3.1

data/lib/mongo_trails/request.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "request_store"
+
+module PaperTrail
+  # Manages variables that affect the current HTTP request, such as `whodunnit`.
+  #
+  # Please do not use `PaperTrail::Request` directly, use `PaperTrail.request`.
+  # 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 private
+  module Request
+    class InvalidOption < RuntimeError
+    end
+
+    class << self
+      # Sets any data from the controller that you want PaperTrail to store.
+      # See also `PaperTrail::Rails::Controller#info_for_paper_trail`.
+      #
+      #   PaperTrail.request.controller_info = { ip: request_user_ip }
+      #   PaperTrail.request.controller_info # => { ip: '127.0.0.1' }
+      #
+      # @api public
+      def controller_info=(value)
+        store[:controller_info] = value
+      end
+
+      # Returns the data from the controller that you want PaperTrail to store.
+      # See also `PaperTrail::Rails::Controller#info_for_paper_trail`.
+      #
+      #   PaperTrail.request.controller_info = { ip: request_user_ip }
+      #   PaperTrail.request.controller_info # => { ip: '127.0.0.1' }
+      #
+      # @api public
+      def controller_info
+        store[:controller_info]
+      end
+
+      # Switches PaperTrail off for the given model.
+      # @api public
+      def disable_model(model_class)
+        enabled_for_model(model_class, false)
+      end
+
+      # Switches PaperTrail on for the given model.
+      # @api public
+      def enable_model(model_class)
+        enabled_for_model(model_class, true)
+      end
+
+      # Sets whether PaperTrail is enabled or disabled for the current request.
+      # @api public
+      def enabled=(value)
+        store[:enabled] = value
+      end
+
+      # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
+      # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
+      # @api public
+      def enabled?
+        !!store[:enabled]
+      end
+
+      # Sets whether PaperTrail is enabled or disabled for this model in the
+      # current request.
+      # @api public
+      def enabled_for_model(model, value)
+        store[:"enabled_for_#{model}"] = value
+      end
+
+      # Returns `true` if PaperTrail is enabled for this model in the current
+      # request, `false` otherwise.
+      # @api public
+      def enabled_for_model?(model)
+        model.include?(::PaperTrail::Model::InstanceMethods) &&
+          !!store.fetch(:"enabled_for_#{model}", true)
+      end
+
+      # @api private
+      def merge(options)
+        options.to_h.each do |k, v|
+          store[k] = v
+        end
+      end
+
+      # @api private
+      def set(options)
+        store.clear
+        merge(options)
+      end
+
+      # Returns a deep copy of the internal hash from our RequestStore. Keys are
+      # all symbols. Values are mostly primitives, but whodunnit can be a Proc.
+      # We cannot use Marshal.dump here because it doesn't support Proc. It is
+      # unclear exactly how `deep_dup` handles a Proc, but it doesn't complain.
+      # @api private
+      def to_h
+        store.deep_dup
+      end
+
+      # Temporarily set `options` and execute a block.
+      # @api private
+      def with(options)
+        return unless block_given?
+        validate_public_options(options)
+        before = to_h
+        merge(options)
+        yield
+      ensure
+        set(before)
+      end
+
+      # Sets who is responsible for any changes that occur during request. You
+      # would normally use this in a migration or on the console, when working
+      # with models directly.
+      #
+      # `value` is usually a string, the name of a person, but you can set
+      # anything that responds to `to_s`. You can also set a Proc, which will
+      # not be evaluated until `whodunnit` is called later, usually right before
+      # inserting a `Version` record.
+      #
+      # @api public
+      def whodunnit=(value)
+        store[:whodunnit] = value
+      end
+
+      # Returns who is reponsible for any changes that occur during request.
+      #
+      # @api public
+      def whodunnit
+        who = store[:whodunnit]
+        who.respond_to?(:call) ? who.call : who
+      end
+
+      private
+
+      # Returns a Hash, initializing with default values if necessary.
+      # @api private
+      def store
+        RequestStore.store[:paper_trail] ||= {
+          enabled: true
+        }
+      end
+
+      # Provide a helpful error message if someone has a typo in one of their
+      # option keys. We don't validate option values here. That's traditionally
+      # been handled with casting (`to_s`, `!!`) in the accessor method.
+      # @api private
+      def validate_public_options(options)
+        options.each do |k, _v|
+          case k
+          when :controller_info,
+              /enabled_for_/,
+              :enabled,
+              :whodunnit
+            next
+          else
+            raise InvalidOption, "Invalid option: #{k}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo_trails/serializers/json.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Serializers
+    # An alternate serializer for, e.g. `versions.object`.
+    module JSON
+      extend self # makes all instance methods become module methods as well
+
+      def load(string)
+        ActiveSupport::JSON.decode string
+      end
+
+      def dump(object)
+        ActiveSupport::JSON.encode object
+      end
+
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized object.
+      def where_object_condition(arel_field, field, value)
+        # Convert to JSON to handle strings and nulls correctly.
+        json_value = value.to_json
+
+        # If the value is a number, we need to ensure that we find the next
+        # character too, which is either `,` or `}`, to ensure that searching
+        # for the value 12 doesn't yield false positives when the value is
+        # 123.
+        if value.is_a? Numeric
+          arel_field.matches("%\"#{field}\":#{json_value},%").
+            or(arel_field.matches("%\"#{field}\":#{json_value}}%"))
+        else
+          arel_field.matches("%\"#{field}\":#{json_value}%")
+        end
+      end
+
+      def where_object_changes_condition(*)
+        raise <<-STR.squish.freeze
+          where_object_changes no longer supports reading JSON from a text
+          column. The old implementation was inaccurate, returning more records
+          than you wanted. This feature was deprecated in 7.1.0 and removed in
+          8.0.0. The json and jsonb datatypes are still supported. See the
+          discussion at https://github.com/paper-trail-gem/paper_trail/issues/803
+        STR
+      end
+    end
+  end
+end

data/lib/mongo_trails/serializers/yaml.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module PaperTrail
+  module Serializers
+    # The default serializer for, e.g. `versions.object`.
+    module YAML
+      extend self # makes all instance methods become module methods as well
+
+      def load(string)
+        ::YAML.load string
+      end
+
+      # @param object (Hash | HashWithIndifferentAccess) - Coming from
+      # `recordable_object` `object` will be a plain `Hash`. However, due to
+      # recent [memory optimizations](https://git.io/fjeYv), when coming from
+      # `recordable_object_changes`, it will be a `HashWithIndifferentAccess`.
+      def dump(object)
+        object = object.to_hash if object.is_a?(HashWithIndifferentAccess)
+        ::YAML.dump object
+      end
+
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized object.
+      def where_object_condition(arel_field, field, value)
+        arel_field.matches("%\n#{field}: #{value}\n%")
+      end
+
+      # Returns a SQL LIKE condition to be used to match the given field and
+      # value in the serialized `object_changes`.
+      def where_object_changes_condition(*)
+        raise <<-STR.squish.freeze
+          where_object_changes no longer supports reading YAML from a text
+          column. The old implementation was inaccurate, returning more records
+          than you wanted. This feature was deprecated in 8.1.0 and removed in
+          9.0.0. The json and jsonb datatypes are still supported. See
+          discussion at https://github.com/paper-trail-gem/paper_trail/pull/997
+        STR
+      end
+    end
+  end
+end

data/lib/mongo_trails/type_serializers/postgres_array_serializer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module TypeSerializers
+    # Provides an alternative method of serialization
+    # and deserialization of PostgreSQL array columns.
+    class PostgresArraySerializer
+      def initialize(subtype, delimiter)
+        @subtype = subtype
+        @delimiter = delimiter
+      end
+
+      def serialize(array)
+        return serialize_with_ar(array) if active_record_pre_502?
+        array
+      end
+
+      def deserialize(array)
+        return deserialize_with_ar(array) if active_record_pre_502?
+
+        case array
+        # Needed for legacy reasons. If serialized array is a string
+        # then it was serialized with Rails < 5.0.2.
+        when ::String then deserialize_with_ar(array)
+        else array
+        end
+      end
+
+      private
+
+      def active_record_pre_502?
+        ::ActiveRecord.gem_version < Gem::Version.new("5.0.2")
+      end
+
+      def serialize_with_ar(array)
+        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
+          new(@subtype, @delimiter).
+          serialize(array)
+      end
+
+      def deserialize_with_ar(array)
+        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
+          new(@subtype, @delimiter).
+          deserialize(array)
+      end
+    end
+  end
+end

data/lib/mongo_trails/version_concern.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require "mongo_trails/attribute_serializers/object_changes_attribute"
+require "mongo_trails/queries/versions/where_object"
+require "mongo_trails/queries/versions/where_object_changes"
+
+module PaperTrail
+  # Originally, PaperTrail did not provide this module, and all of this
+  # functionality was in `PaperTrail::Version`. That model still exists (and is
+  # used by most apps) but by moving the functionality to this module, people
+  # can include this concern instead of sub-classing the `Version` model.
+  module VersionConcern
+    extend ::ActiveSupport::Concern
+
+    # :nodoc:
+    module ClassMethods
+      def item_subtype_column_present?
+        column_names.include?("item_subtype")
+      end
+
+      def with_item_keys(item_type, item_id)
+        where(item_type: item_type).and(item_id: item_id)
+      end
+
+      def creates
+        where event: "create"
+      end
+
+      def updates
+        where event: "update"
+      end
+
+      def destroys
+        where event: "destroy"
+      end
+
+      def not_creates
+        where "event <> ?", "create"
+      end
+
+      def between(start_time, end_time)
+        where(:created_at.gt => start_time).and(:created_at.lt => end_time).order(timestamp_sort_order)
+      end
+
+      # Defaults to using the primary key as the secondary sort order if
+      # possible.
+      def timestamp_sort_order(direction = "asc")
+        { created_at: direction.downcase }
+      end
+
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects` column.
+      #
+      # ```
+      # SELECT "versions".*
+      # FROM "versions"
+      # WHERE ("versions"."object" LIKE '%
+      # name: Joan
+      # %')
+      # ```
+      #
+      # This is useful for finding versions where a given attribute had a given
+      # value. Imagine, in the example above, that Joan had changed her name
+      # and we wanted to find the versions before that change.
+      #
+      # Based on the data type of the `object` column, the appropriate SQL
+      # operator is used. For example, a text column will use `like`, and a
+      # jsonb column will use `@>`.
+      #
+      # @api public
+      def where_object(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObject.new(self, args).execute
+      end
+
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column.
+      #
+      # ```
+      # SELECT "versions".*
+      # FROM "versions"
+      # WHERE .. ("versions"."object_changes" LIKE '%
+      # name:
+      # - Joan
+      # %' OR "versions"."object_changes" LIKE '%
+      # name:
+      # -%
+      # - Joan
+      # %')
+      # ```
+      #
+      # This is useful for finding versions immediately before and after a given
+      # attribute had a given value. Imagine, in the example above, that someone
+      # changed their name to Joan and we wanted to find the versions
+      # immediately before and after that change.
+      #
+      # Based on the data type of the `object` column, the appropriate SQL
+      # operator is used. For example, a text column will use `like`, and a
+      # jsonb column will use `@>`.
+      #
+      # @api public
+      def where_object_changes(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChanges.new(self, args).execute
+      end
+
+      def primary_key_is_int?
+        @primary_key_is_int ||= columns_hash[primary_key].type == :integer
+      rescue StandardError # TODO: Rescue something more specific
+        true
+      end
+
+      # Returns whether the `object` column is using the `json` type supported
+      # by PostgreSQL.
+      def object_col_is_json?
+        # %i[json jsonb].include?(columns_hash["object"].type)
+        true
+      end
+
+      # Returns whether the `object_changes` column is using the `json` type
+      # supported by PostgreSQL.
+      def object_changes_col_is_json?
+        # %i[json jsonb].include?(columns_hash["object_changes"].try(:type))
+        true
+      end
+
+      # Returns versions before `obj`.
+      #
+      # @param obj - a `Version` or a timestamp
+      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
+      #   Default: false.
+      # @return `ActiveRecord::Relation`
+      # @api public
+      def preceding(obj, timestamp_arg = false)
+        if timestamp_arg != true && primary_key_is_int?
+          preceding_by_id(obj)
+        else
+          preceding_by_timestamp(obj)
+        end
+      end
+
+      # Returns versions after `obj`.
+      #
+      # @param obj - a `Version` or a timestamp
+      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
+      #   Default: false.
+      # @return `ActiveRecord::Relation`
+      # @api public
+      def subsequent(obj, timestamp_arg = false)
+        if timestamp_arg != true && primary_key_is_int?
+          subsequent_by_id(obj)
+        else
+          subsequent_by_timestamp(obj)
+        end
+      end
+
+      private
+
+      # @api private
+      def preceding_by_id(obj)
+        where(:integer_id.lt => obj.integer_id).order(integer_id: :desc)
+      end
+
+      # @api private
+      def preceding_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(:created_at.lt => obj).order(timestamp_sort_order("desc"))
+      end
+
+      # @api private
+      def subsequent_by_id(version)
+        where(:integer_id.gt => version.integer_id).order(integer_id: :asc)
+      end
+
+      # @api private
+      def subsequent_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(:created_at.gt => obj).order(timestamp_sort_order)
+      end
+    end
+
+    # @api private
+    def object_deserialized
+      if self.class.object_col_is_json?
+        object
+      else
+        PaperTrail.serializer.load(object)
+      end
+    end
+
+    # Restore the item from this version.
+    #
+    # Options:
+    #
+    # - :mark_for_destruction
+    #   - `true` - Mark the has_one/has_many associations that did not exist in
+    #     the reified version for destruction, instead of removing them.
+    #   - `false` - Default. Useful for persisting the reified version.
+    # - :dup
+    #   - `false` - Default.
+    #   - `true` - Always create a new object instance. Useful for
+    #     comparing two versions of the same object.
+    # - :unversioned_attributes
+    #   - `:nil` - Default. Attributes undefined in version record are set to
+    #     nil in reified record.
+    #   - `:preserve` - Attributes undefined in version record are not modified.
+    #
+    def reify(options = {})
+      unless self.class.fields.keys.include? "object"
+        raise "reify can't be called without an object column"
+      end
+      return nil if object.nil?
+      ::PaperTrail::Reifier.reify(self, options)
+    end
+
+    # Returns what changed in this version of the item.
+    # `ActiveModel::Dirty#changes`. returns `nil` if your `versions` table does
+    # not have an `object_changes` text column.
+    def changeset
+      return nil unless self.class.fields.keys.include? "object_changes"
+      @changeset ||= load_changeset
+    end
+
+    # Returns who put the item into the state stored in this version.
+    def paper_trail_originator
+      @paper_trail_originator ||= previous.try(:whodunnit)
+    end
+
+    # Returns who changed the item from the state it had in this version. This
+    # is an alias for `whodunnit`.
+    def terminator
+      @terminator ||= whodunnit
+    end
+    alias version_author terminator
+
+    def sibling_versions(reload = false)
+      if reload || !defined?(@sibling_versions) || @sibling_versions.nil?
+        @sibling_versions = self.class.with_item_keys(item_type, item_id)
+      end
+      @sibling_versions
+    end
+
+    def next
+      @next ||= sibling_versions.subsequent(self).first
+    end
+
+    def previous
+      @previous ||= sibling_versions.preceding(self).first
+    end
+
+    # Returns an integer representing the chronological position of the
+    # version among its siblings (see `sibling_versions`). The "create" event,
+    # for example, has an index of 0.
+    # @api public
+    def index
+      @index ||= RecordHistory.new(sibling_versions, self.class).index(self)
+    end
+
+    private
+
+    # @api private
+    def load_changeset
+      if PaperTrail.config.object_changes_adapter&.respond_to?(:load_changeset)
+        return PaperTrail.config.object_changes_adapter.load_changeset(self)
+      end
+
+      # First, deserialize the `object_changes` column.
+      changes = HashWithIndifferentAccess.new(object_changes_deserialized)
+
+      # The next step is, perhaps unfortunately, called "de-serialization",
+      # and appears to be responsible for custom attribute serializers. For an
+      # example of a custom attribute serializer, see
+      # `Person::TimeZoneSerializer` in the test suite.
+      #
+      # Is `item.class` good enough? Does it handle `inheritance_column`
+      # as well as `Reifier#version_reification_class`? We were using
+      # `item_type.constantize`, but that is problematic when the STI parent
+      # is not versioned. (See `Vehicle` and `Car` in the test suite).
+      #
+      # Note: `item` returns nil if `event` is "destroy".
+      unless item.nil?
+        AttributeSerializers::ObjectChangesAttribute.
+          new(item.class).
+          deserialize(changes)
+      end
+
+      # Finally, return a Hash mapping each attribute name to
+      # a two-element array representing before and after.
+      changes
+    end
+
+    # If the `object_changes` column is a Postgres JSON column, then
+    # ActiveRecord will deserialize it for us. Otherwise, it's a string column
+    # and we must deserialize it ourselves.
+    # @api private
+    def object_changes_deserialized
+      if self.class.object_changes_col_is_json?
+        object_changes
+      else
+        begin
+          PaperTrail.serializer.load(object_changes)
+        rescue StandardError # TODO: Rescue something more specific
+          {}
+        end
+      end
+    end
+
+    # Enforces the `version_limit`, if set. Default: no limit.
+    # @api private
+    def enforce_version_limit!
+      limit = version_limit
+      return unless limit.is_a? Numeric
+      previous_versions = sibling_versions.not_creates.
+        order(self.class.timestamp_sort_order("asc"))
+      return unless previous_versions.size > limit
+      excess_versions = previous_versions - previous_versions.last(limit)
+      excess_versions.map(&:destroy)
+    end
+
+    # See docs section 2.e. Limiting the Number of Versions Created.
+    # The version limit can be global or per-model.
+    #
+    # @api private
+    #
+    # TODO: Duplication: similar `constantize` in Reifier#version_reification_class
+    def version_limit
+      if self.class.item_subtype_column_present?
+        klass = (item_subtype || item_type).constantize
+        if klass&.paper_trail_options&.key?(:limit)
+          return klass.paper_trail_options[:limit]
+        end
+      end
+      PaperTrail.config.version_limit
+    end
+  end
+end