paper_trail-association_tracking 0.0.1

data/lib/paper_trail_association_tracking/reifier.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "paper_trail_association_tracking/reifiers/belongs_to"
+require "paper_trail_association_tracking/reifiers/has_and_belongs_to_many"
+require "paper_trail_association_tracking/reifiers/has_many"
+require "paper_trail_association_tracking/reifiers/has_many_through"
+require "paper_trail_association_tracking/reifiers/has_one"
+
+module PaperTrailAssociationTracking
+  # Given a version record and some options, builds a new model object.
+  # @api private
+  module Reifier
+    module ClassMethods
+      # See `VersionConcern#reify` for documentation.
+      # @api private
+      def reify(version, options)
+        options = apply_defaults_to(options, version)
+        model = super
+        reify_associations(model, options, version)
+        model
+      end
+
+      # Restore the `model`'s has_many associations as they were at version_at
+      # timestamp We lookup the first child versions after version_at timestamp or
+      # in same transaction.
+      # @api private
+      def reify_has_manys(transaction_id, model, options = {})
+        assoc_has_many_through, assoc_has_many_directly =
+          model.class.reflect_on_all_associations(:has_many).
+            partition { |assoc| assoc.options[:through] }
+        reify_has_many_associations(transaction_id, assoc_has_many_directly, model, options)
+        reify_has_many_through_associations(transaction_id, assoc_has_many_through, model, options)
+      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
+
+      # @api private
+      def each_enabled_association(associations)
+        associations.each do |assoc|
+          next unless ::PaperTrail.request.enabled_for_model?(assoc.klass)
+          yield assoc
+        end
+      end
+
+      # @api private
+      def reify_associations(model, options, version)
+        if options[:has_one]
+          reify_has_one_associations(version.transaction_id, model, options)
+        end
+        if options[:belongs_to]
+          reify_belongs_to_associations(version.transaction_id, model, options)
+        end
+        if options[:has_many]
+          reify_has_manys(version.transaction_id, model, options)
+        end
+        if options[:has_and_belongs_to_many]
+          reify_habtm_associations version.transaction_id, model, options
+        end
+      end
+
+      # Restore the `model`'s has_one associations as they were when this
+      # version was superseded by the next (because that's what the user was
+      # looking at when they made the change).
+      # @api private
+      def reify_has_one_associations(transaction_id, model, options = {})
+        associations = model.class.reflect_on_all_associations(:has_one)
+        each_enabled_association(associations) do |assoc|
+          ::PaperTrailAssociationTracking::Reifiers::HasOne.reify(assoc, model, options, transaction_id)
+        end
+      end
+
+      # Reify all `belongs_to` associations of `model`.
+      # @api private
+      def reify_belongs_to_associations(transaction_id, model, options = {})
+        associations = model.class.reflect_on_all_associations(:belongs_to)
+        each_enabled_association(associations) do |assoc|
+          ::PaperTrailAssociationTracking::Reifiers::BelongsTo.reify(assoc, model, options, transaction_id)
+        end
+      end
+
+      # Reify all direct (not `through`) `has_many` associations of `model`.
+      # @api private
+      def reify_has_many_associations(transaction_id, associations, model, options = {})
+        version_table_name = model.class.paper_trail.version_class.table_name
+        each_enabled_association(associations) do |assoc|
+          ::PaperTrailAssociationTracking::Reifiers::HasMany.reify(assoc, model, options, transaction_id, version_table_name)
+        end
+      end
+
+      # Reify all HMT associations of `model`. This must be called after the
+      # direct (non-`through`) has_manys have been reified.
+      # @api private
+      def reify_has_many_through_associations(transaction_id, associations, model, options = {})
+        each_enabled_association(associations) do |assoc|
+          ::PaperTrailAssociationTracking::Reifiers::HasManyThrough.reify(assoc, model, options, transaction_id)
+        end
+      end
+
+      # Reify all HABTM associations of `model`.
+      # @api private
+      def reify_habtm_associations(transaction_id, model, options = {})
+        model.class.reflect_on_all_associations(:has_and_belongs_to_many).each do |assoc|
+          pt_enabled = ::PaperTrail.request.enabled_for_model?(assoc.klass)
+          next unless model.class.paper_trail_save_join_tables.include?(assoc.name) || pt_enabled
+          ::PaperTrailAssociationTracking::Reifiers::HasAndBelongsToMany.reify(pt_enabled, assoc, model, options, transaction_id)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail_association_tracking/reifiers/belongs_to.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PaperTrailAssociationTracking
+  module Reifiers
+    # Reify a single `belongs_to` association of `model`.
+    # @api private
+    module BelongsTo
+      class << self
+        # @api private
+        def reify(assoc, model, options, transaction_id)
+          id = model.send(assoc.foreign_key)
+          version = load_version(assoc, id, transaction_id, options[:version_at])
+          record = load_record(assoc, id, options, version)
+          model.send("#{assoc.name}=".to_sym, record)
+        end
+
+        private
+
+        # Given a `belongs_to` association and a `version`, return a record that
+        # can be assigned in order to reify that association.
+        # @api private
+        def load_record(assoc, id, options, version)
+          if version.nil?
+            assoc.klass.where(assoc.klass.primary_key => id).first
+          else
+            version.reify(
+              options.merge(
+                has_many: false,
+                has_one: false,
+                belongs_to: false,
+                has_and_belongs_to_many: false
+              )
+            )
+          end
+        end
+
+        # Given a `belongs_to` association and an `id`, return a version record
+        # from the point in time identified by `transaction_id` or `version_at`.
+        # @api private
+        def load_version(assoc, id, transaction_id, version_at)
+          assoc.klass.paper_trail.version_class.
+            where("item_type = ?", assoc.klass.base_class.name).
+            where("item_id = ?", id).
+            where("created_at >= ? OR transaction_id = ?", version_at, transaction_id).
+            order("id").limit(1).first
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail_association_tracking/reifiers/has_and_belongs_to_many.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PaperTrailAssociationTracking
+  module Reifiers
+    # Reify a single HABTM association of `model`.
+    # @api private
+    module HasAndBelongsToMany
+      class << self
+        # @api private
+        def reify(pt_enabled, assoc, model, options, transaction_id)
+          version_ids = ::PaperTrail::VersionAssociation.
+            where("foreign_key_name = ?", assoc.name).
+            where("version_id = ?", transaction_id).
+            pluck(:foreign_key_id)
+
+          model.send(assoc.name).proxy_association.target =
+            version_ids.map do |id|
+              if pt_enabled
+                version = load_version(assoc, id, transaction_id, options[:version_at])
+                if version
+                  next version.reify(
+                    options.merge(
+                      has_many: false,
+                      has_one: false,
+                      belongs_to: false,
+                      has_and_belongs_to_many: false
+                    )
+                  )
+                end
+              end
+              assoc.klass.where(assoc.klass.primary_key => id).first
+            end
+        end
+
+        private
+
+        # Given a HABTM association `assoc` and an `id`, return a version record
+        # from the point in time identified by `transaction_id` or `version_at`.
+        # @api private
+        def load_version(assoc, id, transaction_id, version_at)
+          assoc.klass.paper_trail.version_class.
+            where("item_type = ?", assoc.klass.base_class.name).
+            where("item_id = ?", id).
+            where("created_at >= ? OR transaction_id = ?", version_at, transaction_id).
+            order("id").
+            limit(1).
+            first
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail_association_tracking/reifiers/has_many.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module PaperTrailAssociationTracking
+  module Reifiers
+    # Reify a single, direct (not `through`) `has_many` association of `model`.
+    # @api private
+    module HasMany
+      class << self
+        # @api private
+        def reify(assoc, model, options, transaction_id, version_table_name)
+          versions = load_versions_for_hm_association(
+            assoc,
+            model,
+            version_table_name,
+            transaction_id,
+            options[:version_at]
+          )
+          collection = Array.new model.send(assoc.name).reload # to avoid cache
+          prepare_array(collection, options, versions)
+          model.send(assoc.name).proxy_association.target = collection
+        end
+
+        # Replaces each record in `array` with its reified version, if present
+        # in `versions`.
+        #
+        # @api private
+        # @param array - The collection to be modified.
+        # @param options
+        # @param versions - A `Hash` mapping IDs to `Version`s
+        # @return nil - Always returns `nil`
+        #
+        # Once modified by this method, `array` will be assigned to the
+        # AR association currently being reified.
+        #
+        def prepare_array(array, options, versions)
+          # Iterate each child to replace it with the previous value if there is
+          # a version after the timestamp.
+          array.map! do |record|
+            if (version = versions.delete(record.id)).nil?
+              record
+            elsif version.event == "create"
+              options[:mark_for_destruction] ? record.tap(&:mark_for_destruction) : nil
+            else
+              version.reify(
+                options.merge(
+                  has_many: false,
+                  has_one: false,
+                  belongs_to: false,
+                  has_and_belongs_to_many: false
+                )
+              )
+            end
+          end
+
+          # Reify the rest of the versions and add them to the collection, these
+          # versions are for those that have been removed from the live
+          # associations.
+          array.concat(
+            versions.values.map { |v|
+              v.reify(
+                options.merge(
+                  has_many: false,
+                  has_one: false,
+                  belongs_to: false,
+                  has_and_belongs_to_many: false
+                )
+              )
+            }
+          )
+
+          array.compact!
+
+          nil
+        end
+
+        # Given a SQL fragment that identifies the IDs of version records,
+        # returns a `Hash` mapping those IDs to `Version`s.
+        #
+        # @api private
+        # @param klass - An ActiveRecord class.
+        # @param version_id_subquery - String. A SQL subquery that selects
+        #   the IDs of version records.
+        # @return A `Hash` mapping IDs to `Version`s
+        #
+        def versions_by_id(klass, version_id_subquery)
+          klass.
+            paper_trail.version_class.
+            where("id IN (#{version_id_subquery})").
+            inject({}) { |a, e| a.merge!(e.item_id => e) }
+        end
+
+        private
+
+        # Given a `has_many` association on `model`, return the version records
+        # from the point in time identified by `tx_id` or `version_at`.
+        # @api private
+        def load_versions_for_hm_association(assoc, model, version_table, tx_id, version_at)
+          version_id_subquery = ::PaperTrail::VersionAssociation.
+            joins(model.class.version_association_name).
+            select("MIN(version_id)").
+            where("foreign_key_name = ?", assoc.foreign_key).
+            where("foreign_key_id = ?", model.id).
+            where("#{version_table}.item_type = ?", assoc.klass.base_class.name).
+            where("created_at >= ? OR transaction_id = ?", version_at, tx_id).
+            group("item_id").
+            to_sql
+          versions_by_id(model.class, version_id_subquery)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail_association_tracking/reifiers/has_many_through.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PaperTrailAssociationTracking
+  module Reifiers
+    # Reify a single HMT association of `model`.
+    # @api private
+    module HasManyThrough
+      class << self
+        # @api private
+        def reify(assoc, model, options, transaction_id)
+          # Load the collection of through-models. For example, if `model` is a
+          # Chapter, having many Paragraphs through Sections, then
+          # `through_collection` will contain Sections.
+          through_collection = model.send(assoc.options[:through])
+
+          # Now, given the collection of "through" models (e.g. sections), load
+          # the collection of "target" models (e.g. paragraphs)
+          collection = collection(through_collection, assoc, options, transaction_id)
+
+          # Finally, assign the `collection` of "target" models, e.g. to
+          # `model.paragraphs`.
+          model.send(assoc.name).proxy_association.target = collection
+        end
+
+        private
+
+        # Examine the `source_reflection`, i.e. the "source" of `assoc` the
+        # `ThroughReflection`. The source can be a `BelongsToReflection`
+        # or a `HasManyReflection`.
+        #
+        # If the association is a has_many association again, then call
+        # reify_has_manys for each record in `through_collection`.
+        #
+        # @api private
+        def collection(through_collection, assoc, options, transaction_id)
+          if !assoc.source_reflection.belongs_to? && through_collection.present?
+            collection_through_has_many(through_collection, assoc, options, transaction_id)
+          else
+            collection_through_belongs_to(through_collection, assoc, options, transaction_id)
+          end
+        end
+
+        # @api private
+        def collection_through_has_many(through_collection, assoc, options, transaction_id)
+          through_collection.each do |through_model|
+            ::PaperTrail::Reifier.reify_has_manys(transaction_id, through_model, options)
+          end
+
+          # At this point, the "through" part of the association chain has
+          # been reified, but not the final, "target" part. To continue our
+          # example, `model.sections` (including `model.sections.paragraphs`)
+          # has been loaded. However, the final "target" part of the
+          # association, that is, `model.paragraphs`, has not been loaded. So,
+          # we do that now.
+          through_collection.flat_map { |through_model|
+            through_model.public_send(assoc.name.to_sym).to_a
+          }
+        end
+
+        # @api private
+        def collection_through_belongs_to(through_collection, assoc, options, tx_id)
+          ids = through_collection.map { |through_model|
+            through_model.send(assoc.source_reflection.foreign_key)
+          }
+          versions = load_versions_for_hmt_association(assoc, ids, tx_id, options[:version_at])
+          collection = Array.new assoc.klass.where(assoc.klass.primary_key => ids)
+          ::PaperTrailAssociationTracking::Reifiers::HasMany.prepare_array(collection, options, versions)
+          collection
+        end
+
+        # Given a `has_many(through:)` association and an array of `ids`, return
+        # the version records from the point in time identified by `tx_id` or
+        # `version_at`.
+        # @api private
+        def load_versions_for_hmt_association(assoc, ids, tx_id, version_at)
+          version_id_subquery = assoc.klass.paper_trail.version_class.
+            select("MIN(id)").
+            where("item_type = ?", assoc.klass.base_class.name).
+            where("item_id IN (?)", ids).
+            where(
+              "created_at >= ? OR transaction_id = ?",
+              version_at,
+              tx_id
+            ).
+            group("item_id").
+            to_sql
+          ::PaperTrailAssociationTracking::Reifiers::HasMany.versions_by_id(assoc.klass, version_id_subquery)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail_association_tracking/reifiers/has_one.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module PaperTrailAssociationTracking
+  module Reifiers
+    # Reify a single `has_one` association of `model`.
+    # @api private
+    module HasOne
+      # A more helpful error message, instead of the AssociationTypeMismatch
+      # you would get if, eg. we were to try to assign a Bicycle to the :car
+      # association (before, if there were multiple records we would just take
+      # the first and hope for the best).
+      # @api private
+      class FoundMoreThanOne < RuntimeError
+        MESSAGE_FMT = <<~STR
+          Unable to reify has_one association. Expected to find one %s,
+          but found %d.
+
+          This is a known issue, and a good example of why association tracking
+          is an experimental feature that should not be used in production.
+
+          That said, this is a rare error. In spec/models/person_spec.rb we
+          reproduce it by having two STI models with the same foreign_key (Car
+          and Bicycle are both Vehicles and the FK for both is owner_id)
+
+          If you'd like to help fix this error, please read
+          https://github.com/airblade/paper_trail/issues/594
+          and see spec/models/person_spec.rb
+        STR
+
+        def initialize(base_class_name, num_records_found)
+          @base_class_name = base_class_name.to_s
+          @num_records_found = num_records_found.to_i
+        end
+
+        def message
+          format(MESSAGE_FMT, @base_class_name, @num_records_found)
+        end
+      end
+
+      class << self
+        # @api private
+        def reify(assoc, model, options, transaction_id)
+          version = load_version(assoc, model, transaction_id, options[:version_at])
+          return unless version
+          if version.event == "create"
+            create_event(assoc, model, options)
+          else
+            noncreate_event(assoc, model, options, version)
+          end
+        end
+
+        private
+
+        # @api private
+        def create_event(assoc, model, options)
+          if options[:mark_for_destruction]
+            model.send(assoc.name).mark_for_destruction if model.send(assoc.name, true)
+          else
+            model.paper_trail.appear_as_new_record do
+              model.send "#{assoc.name}=", nil
+            end
+          end
+        end
+
+        # Given a has-one association `assoc` on `model`, return the version
+        # record from the point in time identified by `transaction_id` or `version_at`.
+        # @api private
+        def load_version(assoc, model, transaction_id, version_at)
+          base_class_name = assoc.klass.base_class.name
+          versions = load_versions(assoc, model, transaction_id, version_at, base_class_name)
+          case versions.length
+          when 0
+            nil
+          when 1
+            versions.first
+          else
+            case ::PaperTrail.config.association_reify_error_behaviour
+            when "warn"
+              version = versions.first
+              version.logger&.warn(
+                FoundMoreThanOne.new(base_class_name, versions.length).message
+              )
+              version
+            when "ignore"
+              versions.first
+            else # "error"
+              raise FoundMoreThanOne.new(base_class_name, versions.length)
+            end
+          end
+        end
+
+        # @api private
+        def load_versions(assoc, model, transaction_id, version_at, base_class_name)
+          version_table_name = model.class.paper_trail.version_class.table_name
+          model.class.paper_trail.version_class.joins(:version_associations).
+            where("version_associations.foreign_key_name = ?", assoc.foreign_key).
+            where("version_associations.foreign_key_id = ?", model.id).
+            where("#{version_table_name}.item_type = ?", base_class_name).
+            where("created_at >= ? OR transaction_id = ?", version_at, transaction_id).
+            order("#{version_table_name}.id ASC").
+            load
+        end
+
+        # @api private
+        def noncreate_event(assoc, model, options, version)
+          child = version.reify(
+            options.merge(
+              has_many: false,
+              has_one: false,
+              belongs_to: false,
+              has_and_belongs_to_many: false
+            )
+          )
+          model.paper_trail.appear_as_new_record do
+            without_persisting(child) do
+              model.send "#{assoc.name}=", child
+            end
+          end
+        end
+
+        # Temporarily suppress #save so we can reassociate with the reified
+        # master of a has_one relationship. Since ActiveRecord 5 the related
+        # object is saved when it is assigned to the association. ActiveRecord
+        # 5 also happens to be the first version that provides #suppress.
+        def without_persisting(record)
+          if record.class.respond_to? :suppress
+            record.class.suppress { yield }
+          else
+            yield
+          end
+        end
+      end
+    end
+  end
+end