snail_trail 0.0.1 → 1.0.0.rc.pre.1

data/lib/snail_trail/version_concern.rb

@@ -0,0 +1,407 @@
+# frozen_string_literal: true
+
+require "snail_trail/attribute_serializers/object_changes_attribute"
+require "snail_trail/queries/versions/where_attribute_changes"
+require "snail_trail/queries/versions/where_object"
+require "snail_trail/queries/versions/where_object_changes"
+require "snail_trail/queries/versions/where_object_changes_from"
+require "snail_trail/queries/versions/where_object_changes_to"
+
+module SnailTrail
+  # Originally, SnailTrail did not provide this module, and all of this
+  # functionality was in `SnailTrail::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
+
+    E_YAML_PERMITTED_CLASSES = <<-EOS.squish.freeze
+      SnailTrail encountered a Psych::DisallowedClass error during
+      deserialization of YAML column, indicating that
+      yaml_column_permitted_classes has not been configured correctly. %s
+    EOS
+
+    included do
+      belongs_to :item, polymorphic: true, optional: true, inverse_of: false
+      validates_presence_of :event
+      after_create :enforce_version_limit!
+      scope :within_transaction, ->(id) { where(transaction_id: id) }
+    end
+
+    # :nodoc:
+    module ClassMethods
+      def with_item_keys(item_type, item_id)
+        where item_type: item_type, 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.not(event: "create")
+      end
+
+      def between(start_time, end_time)
+        where(
+          arel_table[:created_at].gt(start_time).
+          and(arel_table[: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")
+        [arel_table[:created_at].send(direction.downcase)].tap do |array|
+          array << arel_table[primary_key].send(direction.downcase) if primary_key_is_int?
+        end
+      end
+
+      # Given an attribute like `"name"`, query the `versions.object_changes`
+      # column for any changes that modified the provided attribute.
+      #
+      # @api public
+      def where_attribute_changes(attribute)
+        unless attribute.is_a?(String) || attribute.is_a?(Symbol)
+          raise ArgumentError, "expected to receive a String or Symbol"
+        end
+
+        Queries::Versions::WhereAttributeChanges.new(self, attribute).execute
+      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
+
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # from the hash of attributes to other values.
+      #
+      # This is useful for finding versions where the attribute started with a
+      # known value and changed to something else. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_from(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesFrom.new(self, args).execute
+      end
+
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # to the hash of attributes from other values.
+      #
+      # This is useful for finding versions where the attribute started with an
+      # unknown value and changed to a known value. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_to(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesTo.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)
+      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))
+      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
+      # rubocop:disable Style/OptionalBooleanParameter
+      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
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      # 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
+      # rubocop:disable Style/OptionalBooleanParameter
+      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
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      private
+
+      # @api private
+      def preceding_by_id(obj)
+        where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
+      end
+
+      # @api private
+      def preceding_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(arel_table[:created_at].lt(obj)).
+          order(timestamp_sort_order("desc"))
+      end
+
+      # @api private
+      def subsequent_by_id(version)
+        where(arel_table[primary_key].gt(version.id)).order(arel_table[primary_key].asc)
+      end
+
+      # @api private
+      def subsequent_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(arel_table[:created_at].gt(obj)).order(timestamp_sort_order)
+      end
+    end
+
+    # @api private
+    def object_deserialized
+      if self.class.object_col_is_json?
+        object
+      else
+        SnailTrail.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.column_names.include? "object"
+        raise Error, "reify requires an object column"
+      end
+      return nil if object.nil?
+      ::SnailTrail::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.column_names.include? "object_changes"
+      @changeset ||= load_changeset
+    end
+
+    # Returns who put the item into the state stored in this version.
+    def snail_trail_originator
+      @snail_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 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. 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 SnailTrail.config.object_changes_adapter.respond_to?(:load_changeset)
+        return SnailTrail.config.object_changes_adapter.load_changeset(self)
+      end
+
+      # First, deserialize the `object_changes` column.
+      changes = ActiveSupport::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
+          SnailTrail.serializer.load(object_changes)
+        rescue StandardError => e
+          if defined?(::Psych::Exception) && e.instance_of?(::Psych::Exception)
+            ::Kernel.warn format(E_YAML_PERMITTED_CLASSES, e)
+          end
+          {}
+        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
+
+    # @api private
+    def sibling_versions
+      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
+    end
+
+    # See docs section 2.e. Limiting the Number of Versions Created.
+    # The version limit can be global or per-model.
+    #
+    # @api private
+    def version_limit
+      klass = item.class
+      if limit_option?(klass)
+        klass.snail_trail_options[:limit]
+      elsif base_class_limit_option?(klass)
+        klass.base_class.snail_trail_options[:limit]
+      else
+        SnailTrail.config.version_limit
+      end
+    end
+
+    def limit_option?(klass)
+      klass.respond_to?(:snail_trail_options) && klass.snail_trail_options.key?(:limit)
+    end
+
+    def base_class_limit_option?(klass)
+      klass.respond_to?(:base_class) && limit_option?(klass.base_class)
+    end
+  end
+end

data/lib/snail_trail/version_number.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SnailTrail
+  # The version number of the snail_trail gem. Not to be confused with
+  # `SnailTrail::Version`. Ruby constants are case-sensitive, apparently,
+  # and they are two different modules! It would be nice to remove `VERSION`,
+  # because of this confusion, but it's not worth the breaking change.
+  # People are encouraged to use `SnailTrail.gem_version` instead.
+  module VERSION
+    MAJOR = 1
+    MINOR = 0
+    TINY = 0
+
+    # Set PRE to nil unless it's a pre-release (beta, rc, etc.)
+    PRE = 'rc-1'
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".").freeze
+
+    def self.to_s
+      STRING
+    end
+  end
+end

data/lib/snail_trail.rb

@@ -1,6 +1,146 @@
 # frozen_string_literal: true
 
-require_relative 'snail_trail/version'
+# AR does not require all of AS, but ST does. ST uses core_ext like
+# `String#squish`, so we require `active_support/all`. Instead of eagerly
+# loading all of AS here, we could put specific `require`s in only the various
+# ST files that need them, but this seems easier to troubleshoot, though it may
+# add a few milliseconds to rails boot time. If that becomes a pain point, we
+# can revisit this decision.
+require "active_support/all"
 
+# We used to `require "active_record"` here, but that was [replaced with a
+# Railtie](https://github.com/BrandsInsurance/snail_trail/pull/1281) in ST 12.
+# As a result, we cannot reference `ActiveRecord` in this file (ie. until our
+# Railtie has loaded). If we did, it would cause [problems with non-Rails
+# projects](https://github.com/BrandsInsurance/snail_trail/pull/1401).
+
+require "snail_trail/errors"
+require "snail_trail/cleaner"
+require "snail_trail/compatibility"
+require "snail_trail/config"
+require "snail_trail/record_history"
+require "snail_trail/request"
+require "snail_trail/version_number"
+require "snail_trail/serializers/json"
+
+# An ActiveRecord extension that tracks changes to your models, for auditing or
+# versioning.
 module SnailTrail
+  E_TIMESTAMP_FIELD_CONFIG = <<-EOS.squish.freeze
+    SnailTrail.timestamp_field= has been removed, without replacement. It is no
+    longer configurable. The timestamp column in the versions table must now be
+    named created_at.
+  EOS
+
+  extend SnailTrail::Cleaner
+
+  class << self
+    def transaction?
+      ::ActiveRecord::Base.connection.open_transactions.positive?
+    end
+
+    # Switches SnailTrail on or off, for all threads.
+    # @api public
+    def enabled=(value)
+      SnailTrail.config.enabled = value
+    end
+
+    # Returns `true` if SnailTrail is on, `false` otherwise. This is the
+    # on/off switch that affects all threads. Enabled by default.
+    # @api public
+    def enabled?
+      !!SnailTrail.config.enabled
+    end
+
+    # Returns SnailTrail's `::Gem::Version`, convenient for comparisons. This is
+    # recommended over `::SnailTrail::VERSION::STRING`.
+    #
+    # Added in 7.0.0
+    #
+    # @api public
+    def gem_version
+      ::Gem::Version.new(VERSION::STRING)
+    end
+
+    # Set variables for the current request, eg. whodunnit.
+    #
+    # All request-level variables are now managed here, as of ST 9. Having the
+    # word "request" right there in your application code will remind you that
+    # these variables only affect the current request, not all threads.
+    #
+    # Given a block, temporarily sets the given `options`, executes the block,
+    # and returns the value of the block.
+    #
+    # Without a block, this currently just returns `SnailTrail::Request`.
+    # However, please do not use `SnailTrail::Request` directly. 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 public
+    def request(options = nil, &block)
+      if options.nil? && !block
+        Request
+      else
+        Request.with(options, &block)
+      end
+    end
+
+    # Set the field which records when a version was created.
+    # @api public
+    def timestamp_field=(_field_name)
+      raise Error, E_TIMESTAMP_FIELD_CONFIG
+    end
+
+    # Set the SnailTrail serializer. This setting affects all threads.
+    # @api public
+    def serializer=(value)
+      SnailTrail.config.serializer = value
+    end
+
+    # Get the SnailTrail serializer used by all threads.
+    # @api public
+    def serializer
+      SnailTrail.config.serializer
+    end
+
+    # Returns SnailTrail's global configuration object, a singleton. These
+    # settings affect all threads.
+    # @api public
+    def config
+      @config ||= SnailTrail::Config.instance
+      yield @config if block_given?
+      @config
+    end
+    alias configure config
+
+    # @api public
+    def version
+      VERSION::STRING
+    end
+
+    def active_record_gte_7_0?
+      @active_record_gte_7_0 ||= ::ActiveRecord.gem_version >= ::Gem::Version.new("7.0.0")
+    end
+
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("16.0", "SnailTrail")
+    end
+  end
+end
+
+# ST is built on ActiveRecord, but does not require Rails. If Rails is defined,
+# our Railtie makes sure not to load the AR-dependent parts of ST until AR is
+# ready. A typical Rails `application.rb` has:
+#
+# ```
+# require 'rails/all' # Defines `Rails`
+# Bundler.require(*Rails.groups) # require 'snail_trail' (this file)
+# ```
+#
+# Non-rails applications should take similar care to load AR before ST.
+if defined?(Rails)
+  require "snail_trail/frameworks/rails"
+else
+  require "snail_trail/frameworks/active_record"
 end