snail_trail 0.0.1 → 1.0.0.rc.pre.1

data/lib/snail_trail/reifier.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "snail_trail/attribute_serializers/object_attribute"
+
+module SnailTrail
+  # Given a version record and some options, builds a new model object.
+  # @api private
+  module Reifier
+    class << self
+      # See `VersionConcern#reify` for documentation.
+      # @api private
+      def reify(version, options)
+        options = apply_defaults_to(options, version)
+        attrs = version.object_deserialized
+        model = init_model(attrs, options, version)
+        reify_attributes(model, version, attrs)
+        model.send :"#{model.class.version_association_name}=", version
+        model
+      end
+
+      private
+
+      # Given a hash of `options` for `.reify`, return a new hash with default
+      # values applied.
+      # @api private
+      def apply_defaults_to(options, version)
+        {
+          version_at: version.created_at,
+          mark_for_destruction: false,
+          has_one: false,
+          has_many: false,
+          belongs_to: false,
+          has_and_belongs_to_many: false,
+          unversioned_attributes: :nil
+        }.merge(options)
+      end
+
+      # Initialize a model object suitable for reifying `version` into. Does
+      # not perform reification, merely instantiates the appropriate model
+      # class and, if specified by `options[:unversioned_attributes]`, sets
+      # unversioned attributes to `nil`.
+      #
+      # Normally a polymorphic belongs_to relationship allows us to get the
+      # object we belong to by calling, in this case, `item`.  However this
+      # returns nil if `item` has been destroyed, and we need to be able to
+      # retrieve destroyed objects.
+      #
+      # In this situation we constantize the `item_type` to get hold of the
+      # class...except when the stored object's attributes include a `type`
+      # key.  If this is the case, the object we belong to is using single
+      # table inheritance (STI) and the `item_type` will be the base class,
+      # not the actual subclass. If `type` is present but empty, the class is
+      # the base class.
+      def init_model(attrs, options, version)
+        klass = version_reification_class(version, attrs)
+
+        # The `dup` option and destroyed version always returns a new object,
+        # otherwise we should attempt to load item or to look for the item
+        # outside of default scope(s).
+        model = if options[:dup] == true || version.event == "destroy"
+                  klass.new
+                else
+                  version.item || init_model_by_finding_item_id(klass, version) || klass.new
+                end
+
+        if options[:unversioned_attributes] == :nil && !model.new_record?
+          init_unversioned_attrs(attrs, model)
+        end
+
+        model
+      end
+
+      # @api private
+      def init_model_by_finding_item_id(klass, version)
+        klass.unscoped.where(klass.primary_key => version.item_id).first
+      end
+
+      # Look for attributes that exist in `model` and not in this version.
+      # These attributes should be set to nil. Modifies `attrs`.
+      # @api private
+      def init_unversioned_attrs(attrs, model)
+        (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
+      end
+
+      # Reify onto `model` an attribute named `k` with value `v` from `version`.
+      #
+      # `ObjectAttribute#deserialize` will return the mapped enum value and in
+      # Rails < 5, the []= uses the integer type caster from the column
+      # definition (in general) and thus will turn a (usually) string to 0
+      # instead of the correct value.
+      #
+      # @api private
+      def reify_attribute(k, v, model, version)
+        if model.has_attribute?(k)
+          model[k.to_sym] = v
+        elsif model.respond_to?(:"#{k}=")
+          model.send(:"#{k}=", v)
+        elsif version.logger
+          version.logger.warn(
+            "Attribute #{k} does not exist on #{version.item_type} (Version id: #{version.id})."
+          )
+        end
+      end
+
+      # Reify onto `model` all the attributes of `version`.
+      # @api private
+      def reify_attributes(model, version, attrs)
+        AttributeSerializers::ObjectAttribute.new(model.class).deserialize(attrs)
+        attrs.each do |k, v|
+          reify_attribute(k, v, model, version)
+        end
+      end
+
+      # Given a `version`, return the class to reify. This method supports
+      # Single Table Inheritance (STI) with custom inheritance columns and
+      # custom inheritance column values.
+      #
+      # For example, imagine a `version` whose `item_type` is "Animal". The
+      # `animals` table is an STI table (it has cats and dogs) and it has a
+      # custom inheritance column, `species`. If `attrs["species"]` is "Dog",
+      # this method returns the constant `Dog`. If `attrs["species"]` is blank,
+      # this method returns the constant `Animal`.
+      #
+      # The values contained in the inheritance columns may be non-camelized
+      # strings (e.g. 'dog' instead of 'Dog'). To reify classes in this case
+      # we need to call the parents class `sti_class_for` method to retrieve
+      # the correct record class.
+      #
+      # You can see these particular examples in action in
+      # `spec/models/animal_spec.rb` and `spec/models/plant_spec.rb`
+      def version_reification_class(version, attrs)
+        clazz = version.item_type.constantize
+        inheritance_column_name = clazz.inheritance_column
+        inher_col_value = attrs[inheritance_column_name]
+        return clazz if inher_col_value.blank?
+
+        # Rails 6.1 adds a public method for clients to use to customize STI classes. If that
+        # method is not available, fall back to using the private one
+        if clazz.public_methods.include?(:sti_class_for)
+          return clazz.sti_class_for(inher_col_value)
+        end
+
+        clazz.send(:find_sti_class, inher_col_value)
+      end
+    end
+  end
+end

data/lib/snail_trail/request.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "request_store"
+
+module SnailTrail
+  # Manages variables that affect the current HTTP request, such as `whodunnit`.
+  #
+  # Please do not use `SnailTrail::Request` directly, use `SnailTrail.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 << self
+      # @api private
+      def clear_transaction_id
+        self.transaction_id = nil
+      end
+
+      # @api private
+      def transaction_id
+        store[:transaction_id]
+      end
+
+      # @api private
+      def transaction_id=(id)
+        store[:transaction_id] = id
+      end
+
+      # Sets any data from the controller that you want SnailTrail to store.
+      # See also `SnailTrail::Rails::Controller#info_for_snail_trail`.
+      #
+      #   SnailTrail.request.controller_info = { ip: request_user_ip }
+      #   SnailTrail.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 SnailTrail to store.
+      # See also `SnailTrail::Rails::Controller#info_for_snail_trail`.
+      #
+      #   SnailTrail.request.controller_info = { ip: request_user_ip }
+      #   SnailTrail.request.controller_info # => { ip: '127.0.0.1' }
+      #
+      # @api public
+      def controller_info
+        store[:controller_info]
+      end
+
+      # Switches SnailTrail off for the given model.
+      # @api public
+      def disable_model(model_class)
+        enabled_for_model(model_class, false)
+      end
+
+      # Switches SnailTrail on for the given model.
+      # @api public
+      def enable_model(model_class)
+        enabled_for_model(model_class, true)
+      end
+
+      # Sets whether SnailTrail is enabled or disabled for the current request.
+      # @api public
+      def enabled=(value)
+        store[:enabled] = value
+      end
+
+      # Returns `true` if SnailTrail is enabled for the request, `false` otherwise.
+      # See `SnailTrail::Rails::Controller#snail_trail_enabled_for_controller`.
+      # @api public
+      def enabled?
+        !!store[:enabled]
+      end
+
+      # Sets whether SnailTrail 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 SnailTrail is enabled for this model in the current
+      # request, `false` otherwise.
+      # @api public
+      def enabled_for_model?(model)
+        model.include?(::SnailTrail::Model::InstanceMethods) &&
+          !!store.fetch(:"enabled_for_#{model}", true)
+      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
+
+      # @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 Hash, initializing with default values if necessary.
+      # @api private
+      def store
+        RequestStore.store[:snail_trail] ||= {
+          enabled: true
+        }
+      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
+
+      # 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
+          when :transaction_id
+            raise ::SnailTrail::Request::InvalidOption, "Cannot set private option: transaction_id"
+          else
+            raise InvalidOption, "Invalid option: #{k}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/snail_trail/serializers/json.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SnailTrail
+  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
+    end
+  end
+end

data/lib/snail_trail/serializers/yaml.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module SnailTrail
+  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)
+        if use_safe_load?
+          ::YAML.safe_load(
+            string,
+            permitted_classes: yaml_column_permitted_classes,
+            aliases: true
+          )
+        elsif ::YAML.respond_to?(:unsafe_load)
+          ::YAML.unsafe_load(string)
+        else
+          ::YAML.load(string)
+        end
+      end
+
+      # @param object (Hash | HashWithIndifferentAccess) - Coming from
+      # `recordable_object` `object` will be a plain `Hash`. However, due to
+      # recent [memory optimizations](https://github.com/BrandsInsurance/snail_trail/pull/1189),
+      # when coming from `recordable_object_changes`, it will be a `HashWithIndifferentAccess`.
+      def dump(object)
+        object = object.to_hash if object.is_a?(ActiveSupport::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
+
+      private
+
+      def use_safe_load?
+        if ::ActiveRecord.gem_version >= Gem::Version.new("7.0.3.1")
+          # `use_yaml_unsafe_load` may be removed in the future, at which point
+          # safe loading will be the default.
+          !defined?(ActiveRecord.use_yaml_unsafe_load) || !ActiveRecord.use_yaml_unsafe_load
+        elsif defined?(ActiveRecord::Base.use_yaml_unsafe_load)
+          # Rails 5.2.8.1, 6.0.5.1, 6.1.6.1
+          !ActiveRecord::Base.use_yaml_unsafe_load
+        else
+          false
+        end
+      end
+
+      def yaml_column_permitted_classes
+        if defined?(ActiveRecord.yaml_column_permitted_classes)
+          # Rails >= 7.0.3.1
+          ActiveRecord.yaml_column_permitted_classes
+        elsif defined?(ActiveRecord::Base.yaml_column_permitted_classes)
+          # Rails 5.2.8.1, 6.0.5.1, 6.1.6.1
+          ActiveRecord::Base.yaml_column_permitted_classes
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/snail_trail/type_serializers/postgres_array_serializer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SnailTrail
+  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)
+        array
+      end
+
+      def deserialize(array)
+        case array
+        # Needed for legacy data. 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 deserialize_with_ar(array)
+        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
+          new(@subtype, @delimiter).
+          deserialize(array)
+      end
+    end
+  end
+end