snail_trail 0.0.1 → 0.0.2

data/lib/snail_trail/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "snail_trail/serializers/yaml"
+
+module SnailTrail
+  # Global configuration affecting all threads. Some thread-specific
+  # configuration can be found in `snail_trail.rb`, others in `controller.rb`.
+  class Config
+    include Singleton
+
+    attr_accessor(
+      :object_changes_adapter,
+      :serializer,
+      :version_limit,
+      :has_snail_trail_defaults,
+      :version_error_behavior
+    )
+
+    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 = SnailTrail::Serializers::YAML
+      @has_snail_trail_defaults = {}
+      @version_error_behavior = :legacy
+    end
+
+    # Indicates whether SnailTrail is on or off. Default: true.
+    def enabled
+      @mutex.synchronize { !!@enabled }
+    end
+
+    def enabled=(enable)
+      @mutex.synchronize { @enabled = enable }
+    end
+  end
+end

data/lib/snail_trail/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SnailTrail
+  # Generic SnailTrail exception.
+  # @api public
+  class Error < StandardError
+  end
+
+  # An unexpected option, perhaps a typo, was passed to a public API method.
+  # @api public
+  class InvalidOption < Error
+  end
+
+  # The application's database schema is not supported.
+  # @api public
+  class UnsupportedSchema < Error
+  end
+
+  # The application's database column type is not supported.
+  # @api public
+  class UnsupportedColumnType < UnsupportedSchema
+    def initialize(method:, expected:, actual:)
+      super(
+        format(
+          "%s expected %s column, got %s",
+          method,
+          expected,
+          actual
+        )
+      )
+    end
+  end
+end

data/lib/snail_trail/events/base.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+module SnailTrail
+  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 `snail_trail_event`.
+    #
+    # @api private
+    class Base
+      E_FORBIDDEN_METADATA_KEY = <<-EOS.squish
+        Forbidden metadata key: %s. As of ST 14, the following metadata keys are
+        forbidden: %s
+      EOS
+      FORBIDDEN_METADATA_KEYS = %i[
+        created_at
+        id
+        item_id
+        item_subtype
+        item_type
+        updated_at
+      ].freeze
+
+      # @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
+
+      # @api private
+      def assert_metadatum_key_is_permitted(key)
+        return unless FORBIDDEN_METADATA_KEYS.include?(key.to_sym)
+        raise SnailTrail::InvalidOption,
+          format(E_FORBIDDEN_METADATA_KEY, key, FORBIDDEN_METADATA_KEYS)
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/BrandsInsurance/snail_trail/pull/899
+      #
+      # @api private
+      def attribute_changed_in_latest_version?(attr_name)
+        if @in_after_callback
+          @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)
+        record_attributes = @record.attributes.except(*@record.snail_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
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/BrandsInsurance/snail_trail/pull/899
+      #
+      # Event can be any of the three (create, update, destroy).
+      #
+      # @api private
+      def attribute_in_previous_version(attr_name, is_touch)
+        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
+      end
+
+      # @api private
+      def calculated_ignored_array
+        ignore = @record.snail_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.snail_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
+
+      # Memoized to reduce memory usage
+      #
+      # @api private
+      def changes_in_latest_version
+        @changes_in_latest_version ||= load_changes_in_latest_version
+      end
+
+      # @api private
+      def evaluate_only
+        only = @record.snail_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
+      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.snail_trail_options[:skip]
+        ignored.any? && changed_in_latest_version.intersect?(ignored)
+      end
+
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/BrandsInsurance/snail_trail/pull/899
+      #
+      # @api private
+      def load_changes_in_latest_version
+        if @in_after_callback
+          @record.saved_changes
+        else
+          @record.changes
+        end
+      end
+
+      # ST 10 has a new optional column, `item_subtype`
+      #
+      # @api private
+      def merge_item_subtype_into(data)
+        if @record.class.snail_trail.version_class.columns_hash.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)
+        metadata = SnailTrail.request.controller_info || {}
+        metadata.keys.each { |k| assert_metadatum_key_is_permitted(k) }
+        data.merge(metadata)
+      end
+
+      # Updates `data` from the model's `meta` option.
+      #
+      # @api private
+      def merge_metadata_from_model_into(data)
+        @record.snail_trail_options[:meta].each do |k, v|
+          assert_metadatum_key_is_permitted(k)
+          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)
+          metadatum_from_model_method(event, value)
+        else
+          value
+        end
+      end
+
+      # The model method can either be an attribute or a non-attribute method.
+      #
+      # If it is an attribute that is changing in an existing object,
+      # be sure to grab the correct version.
+      #
+      # @api private
+      def metadatum_from_model_method(event, method)
+        if event != "create" &&
+            @record.has_attribute?(method) &&
+            attribute_changed_in_latest_version?(method)
+          attribute_in_previous_version(method, false)
+        else
+          @record.send(method)
+        end
+      end
+
+      # @api private
+      def notable_changes
+        changes_in_latest_version.delete_if { |k, _v|
+          notably_changed.exclude?(k)
+        }
+      end
+
+      # @api private
+      def notably_changed
+        # Memoized to reduce memory usage
+        @notably_changed ||= begin
+          only = evaluate_only
+          cani = changed_and_not_ignored
+          only.empty? ? cani : (cani & only)
+        end
+      end
+
+      # Returns hash of attributes (with appropriate attributes serialized),
+      # omitting attributes to be skipped.
+      #
+      # @api private
+      def object_attrs_for_snail_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 `SnailTrail.serializer`.
+      #
+      # @api private
+      # @param changes HashWithIndifferentAccess
+      def recordable_object_changes(changes)
+        if SnailTrail.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 = SnailTrail.config.object_changes_adapter.diff(changes.to_hash)
+        end
+
+        if @record.class.snail_trail.version_class.object_changes_col_is_json?
+          changes
+        else
+          SnailTrail.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.snail_trail.version_class.column_names.include?("object_changes")
+      end
+
+      # Returns a boolean indicating whether to store the original object during save.
+      #
+      # @api private
+      def record_object?
+        @record.class.snail_trail.version_class.column_names.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
+      # `SnailTrail.serializer`.
+      #
+      # @api private
+      def recordable_object(is_touch)
+        if @record.class.snail_trail.version_class.object_col_is_json?
+          object_attrs_for_snail_trail(is_touch)
+        else
+          SnailTrail.serializer.dump(object_attrs_for_snail_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

data/lib/snail_trail/events/create.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "snail_trail/events/base"
+
+module SnailTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Create < Base
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item: @record,
+          event: @record.snail_trail_event || "create",
+          whodunnit: SnailTrail.request.whodunnit
+        }
+        if @record.respond_to?(:updated_at)
+          data[:created_at] = @record.updated_at
+        end
+        if record_object_changes? && changed_notably?
+          changes = notable_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+    end
+  end
+end

data/lib/snail_trail/events/destroy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "snail_trail/events/base"
+
+module SnailTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Destroy < Base
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item_id: @record.id,
+          item_type: @record.class.base_class.name,
+          event: @record.snail_trail_event || "destroy",
+          whodunnit: SnailTrail.request.whodunnit
+        }
+        if record_object?
+          data[:object] = recordable_object(false)
+        end
+        if record_object_changes?
+          data[:object_changes] = prepare_object_changes(notable_changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+
+      private
+
+      # Rails' implementation (eg. `@record.saved_changes`) returns nothing on
+      # destroy, so we have to build the hash we want.
+      #
+      # @override
+      def changes_in_latest_version
+        @record.attributes.transform_values { |value| [value, nil] }
+      end
+    end
+  end
+end

data/lib/snail_trail/events/update.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "snail_trail/events/base"
+
+module SnailTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Update < Base
+      # - is_touch - [boolean] - Used in the two situations that are touch-like:
+      #   - `after_touch` we call `RecordTrail#record_update`
+      # - force_changes - [Hash] - Only used by `RecordTrail#update_columns`,
+      #   because there dirty-tracking is off, so it has to track its own changes.
+      #
+      # @api private
+      def initialize(record, in_after_callback, is_touch, force_changes)
+        super(record, in_after_callback)
+        @is_touch = is_touch
+        @force_changes = force_changes
+      end
+
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item: @record,
+          event: @record.snail_trail_event || "update",
+          whodunnit: SnailTrail.request.whodunnit
+        }
+        if record_object?
+          data[:object] = recordable_object(@is_touch)
+        end
+        merge_object_changes_into(data)
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+
+      # If it is a touch event, and changed are empty, it is assumed to be
+      # implicit `touch` mutation, and will a version is created.
+      #
+      # See https://github.com/rails/rails/commit/dcb825902d79d0f6baba956f7c6ec5767611353e
+      #
+      # @api private
+      def changed_notably?
+        if @is_touch && changes_in_latest_version.empty?
+          true
+        else
+          super
+        end
+      end
+
+      private
+
+      # @api private
+      def merge_object_changes_into(data)
+        if record_object_changes?
+          changes = @force_changes.nil? ? notable_changes : @force_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+      end
+
+      # `touch` cannot record `object_changes` because rails' `touch` does not
+      # perform dirty-tracking. Specifically, methods from `Dirty`, like
+      # `saved_changes`, return the same values before and after `touch`.
+      #
+      # See https://github.com/rails/rails/issues/33429
+      #
+      # @api private
+      def record_object_changes?
+        !@is_touch && super
+      end
+    end
+  end
+end

data/lib/snail_trail/frameworks/active_record/models/snail_trail/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "snail_trail/version_concern"
+
+module SnailTrail
+  # This is the default ActiveRecord model provided by SnailTrail. Most simple
+  # applications will use this model as-is, but it is possible to sub-class,
+  # extend, or even do without this model entirely. See documentation section
+  # 6.a. Custom Version Classes.
+  #
+  # The snail_trail-association_tracking gem provides a related model,
+  # `VersionAssociation`.
+  class Version < ::ActiveRecord::Base
+    include SnailTrail::VersionConcern
+  end
+end

data/lib/snail_trail/frameworks/active_record.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Either ActiveRecord has already been loaded by the Lazy Load Hook in our
+# Railtie, or else we load it now.
+require "active_record"
+SnailTrail::Compatibility.check_activerecord(ActiveRecord.gem_version)
+
+# Now we can load the parts of ST that depend on AR.
+require "snail_trail/has_snail_trail"
+require "snail_trail/reifier"
+require "snail_trail/frameworks/active_record/models/snail_trail/version"
+ActiveRecord::Base.include SnailTrail::Model

data/lib/snail_trail/frameworks/cucumber.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# before hook for Cucumber
+Before do
+  SnailTrail.enabled = false
+  SnailTrail.request.enabled = true
+  SnailTrail.request.whodunnit = nil
+  SnailTrail.request.controller_info = {} if defined?(Rails)
+end
+
+module SnailTrail
+  module Cucumber
+    # Helper method for enabling ST in Cucumber features.
+    module Extensions
+      # :call-seq:
+      # with_versioning
+      #
+      # enable versioning for specific blocks
+
+      def with_versioning
+        was_enabled = ::SnailTrail.enabled?
+        ::SnailTrail.enabled = true
+        begin
+          yield
+        ensure
+          ::SnailTrail.enabled = was_enabled
+        end
+      end
+    end
+  end
+end
+
+World SnailTrail::Cucumber::Extensions