archival_record 2.0.0

data/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+desc "Default: run all available test suites."
+task default: %I[rubocop test]
+
+desc "Test the archival_record gem."
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end

data/archival_record.gemspec

@@ -0,0 +1,51 @@
+$LOAD_PATH.push File.expand_path("lib", __dir__)
+
+require "archival_record/version"
+
+Gem::Specification.new do |gem|
+  gem.name        = "archival_record"
+  gem.summary     = "Atomic archiving/unarchiving for ActiveRecord"
+  gem.version     = ArchivalRecord::VERSION
+  gem.authors     = ["Joel Meador",
+                     "Michael Kuehl",
+                     "Matthew Gordon",
+                     "Vojtech Salbaba",
+                     "David Jones",
+                     "Dave Woodward",
+                     "Miles Sterrett",
+                     "James Hill",
+                     "Maarten Claes",
+                     "Anthony Panozzo",
+                     "Aaron Milam",
+                     "Anton Rieder",
+                     "Josh Menden",
+                     "Sergey Gnuskov",
+                     "Elijah Miller"]
+  gem.email       = ["joel.meador+archival_record@gmail.com"]
+  gem.homepage    = "http://github.com/janxious/archival_record"
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ["lib"]
+  gem.required_ruby_version = ">= 2.4"
+
+  gem.add_dependency "activerecord", ">= 5.0"
+
+  gem.add_development_dependency "appraisal"
+  gem.add_development_dependency "database_cleaner"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rr"
+  gem.add_development_dependency "rubocop", "~> 0.82.0"
+  gem.add_development_dependency "sqlite3"
+
+  gem.description =
+    <<~DESCRIPTION
+      *Atomic archiving/unarchiving for ActiveRecord*
+
+      acts_as_paranoid and similar plugins/gems work on a record-by-record basis and make it difficult to restore records atomically (or archive them, for that matter).
+
+      Because ArchivalRecord's #archive! and #unarchive! methods are in transactions, and every archival record involved gets the same archive number upon archiving, you can easily restore or remove an entire set of records without having to worry about partial deletion or restoration.
+
+      Additionally, other plugins generally change how destroy/delete work. ArchivalRecord does not, and thus one can destroy records like normal.
+    DESCRIPTION
+end

data/gemfiles/rails_5.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 5.0.0"
+gem "sqlite3", "~> 1.3.13"
+
+gemspec path: "../"

data/gemfiles/rails_5.1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 5.1.0"
+gem "sqlite3", "~> 1.4.1"
+
+gemspec path: "../"

data/gemfiles/rails_5.2.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 5.2.0"
+gem "sqlite3", "~> 1.4.1"
+
+gemspec path: "../"

data/gemfiles/rails_6.0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 6.0.0"
+
+gemspec path: "../"

data/init.rb

@@ -0,0 +1,3 @@
+# Include hook code here
+ActiveRecord::Base.send :include, ArchivalRecordCore::ArchivalRecordActiveRecordMethods
+ActiveRecord::Base.send :include, ArchivalRecordCore::ArchivalRecord

data/lib/archival_record.rb

@@ -0,0 +1,19 @@
+require "archival_record/version"
+
+require "archival_record_core/association_operation/base"
+require "archival_record_core/association_operation/archive"
+require "archival_record_core/association_operation/unarchive"
+
+require "archival_record_core/archival_record"
+require "archival_record_core/archival_record_active_record_methods"
+
+# This assumes a fully Rails 5 compatible set of ActiveRecord models
+if defined?(ApplicationRecord)
+  ApplicationRecord.send :include, ArchivalRecordCore::ArchivalRecord
+  ApplicationRecord.send :include, ArchivalRecordCore::ArchivalRecordActiveRecordMethods
+else
+  ActiveRecord::Base.send :include, ArchivalRecordCore::ArchivalRecord
+  ActiveRecord::Base.send :include, ArchivalRecordCore::ArchivalRecordActiveRecordMethods
+end
+
+ActiveRecord::Relation.send :include, ArchivalRecordCore::ArchivalRecordActiveRecordMethods::ARRelationMethods

data/lib/archival_record/version.rb

@@ -0,0 +1,5 @@
+module ArchivalRecord
+
+  VERSION = "2.0.0".freeze
+
+end

data/lib/archival_record_core/archival_record.rb

@@ -0,0 +1,164 @@
+module ArchivalRecordCore
+  module ArchivalRecord
+
+    require "digest/md5"
+
+    unless defined?(MissingArchivalColumnError) == "constant" && MissingArchivalColumnError.class == Class
+      MissingArchivalColumnError = Class.new(ActiveRecord::ActiveRecordError)
+    end
+    unless defined?(CouldNotArchiveError) == "constant" && CouldNotArchiveError.class == Class
+      CouldNotArchiveError = Class.new(ActiveRecord::ActiveRecordError)
+    end
+    unless defined?(CouldNotUnarchiveError) == "constant" && CouldNotUnarchiveError.class == Class
+      CouldNotUnarchiveError = Class.new(ActiveRecord::ActiveRecordError)
+    end
+
+    def self.included(base)
+      base.extend ActMethods
+    end
+
+    module ActMethods
+
+      def archival_record(options = {})
+        return if included_modules.include?(InstanceMethods)
+
+        include InstanceMethods
+
+        setup_validations(options)
+
+        setup_scopes
+
+        setup_callbacks
+      end
+
+      # Deprecated: Please use `archival_record` instead
+      def acts_as_archival(options = {})
+        ActiveSupport::Deprecation.warn("`acts_as_archival` is deprecated.  Please use `archival_record` instead.")
+        archival_record(options)
+      end
+
+      private def setup_validations(options)
+        before_validation :raise_if_not_archival
+        validate :readonly_when_archived if options[:readonly_when_archived]
+      end
+
+      private def setup_scopes
+        scope :archived, -> { where.not(archived_at: nil).where.not(archive_number: nil) }
+        scope :unarchived, -> { where(archived_at: nil, archive_number: nil) }
+        scope :archived_from_archive_number, (lambda do |head_archive_number|
+          where(["archived_at IS NOT NULL AND archive_number = ?", head_archive_number])
+        end)
+      end
+
+      private def setup_callbacks
+        callbackable_actions = %w[archive unarchive]
+
+        setup_activerecord_callbacks(callbackable_actions)
+
+        define_callback_dsl_methods(callbackable_actions)
+      end
+
+      private def setup_activerecord_callbacks(callbackable_actions)
+        define_callbacks(*[callbackable_actions].flatten)
+      end
+
+      private def define_callback_dsl_methods(callbackable_actions)
+        callbackable_actions.each do |action|
+          %w[before after].each do |callbackable_type|
+            define_callback_dsl_method(callbackable_type, action)
+          end
+        end
+      end
+
+      private def define_callback_dsl_method(callbackable_type, action)
+        # rubocop:disable Security/Eval
+        eval <<-END_CALLBACKS, binding, __FILE__, __LINE__ + 1
+          unless defined?(#{callbackable_type}_#{action})
+            def #{callbackable_type}_#{action}(*args, &blk)
+              set_callback(:#{action}, :#{callbackable_type}, *args, &blk)
+            end
+          end
+        END_CALLBACKS
+        # rubocop:enable Security/Eval
+      end
+
+    end
+
+    module InstanceMethods
+
+      def readonly_when_archived
+        readonly_attributes_changed = archived? && changed? && !archived_at_changed? && !archive_number_changed?
+        return unless readonly_attributes_changed
+
+        errors.add(:base, "Cannot modify an archived record.")
+      end
+
+      def raise_if_not_archival
+        missing_columns = []
+        missing_columns << "archive_number" unless respond_to?(:archive_number)
+        missing_columns << "archived_at" unless respond_to?(:archived_at)
+        return if missing_columns.blank?
+
+        raise MissingArchivalColumnError.new("Add '#{missing_columns.join "', '"}' column(s) to '#{self.class.name}' to make it archival")
+      end
+
+      def archived?
+        !!(archived_at? && archive_number)
+      end
+
+      def archive!(head_archive_number = nil)
+        execute_archival_action(:archive) do
+          unless archived?
+            head_archive_number ||= Digest::MD5.hexdigest("#{self.class.name}#{id}")
+            archive_associations(head_archive_number)
+            self.archived_at = DateTime.now
+            self.archive_number = head_archive_number
+            save!
+          end
+        end
+      end
+
+      def unarchive!(head_archive_number = nil)
+        execute_archival_action(:unarchive) do
+          if archived?
+            head_archive_number ||= archive_number
+            self.archived_at = nil
+            self.archive_number = nil
+            save!
+            unarchive_associations(head_archive_number)
+          end
+        end
+      end
+
+      def archive_associations(head_archive_number)
+        AssociationOperation::Archive.new(self, head_archive_number).execute
+      end
+
+      def unarchive_associations(head_archive_number)
+        AssociationOperation::Unarchive.new(self, head_archive_number).execute
+      end
+
+      private def execute_archival_action(action)
+        self.class.transaction do
+          # rubocop: disable Style/RescueStandardError
+          begin
+            success = run_callbacks(action) { yield }
+            return !!success
+          rescue => e
+            handle_archival_action_exception(e)
+          end
+          # rubocop: enable Style/RescueStandardError
+        end
+        false
+      end
+
+      private def handle_archival_action_exception(exception)
+        ActiveRecord::Base.logger.try(:debug, exception.message)
+        ActiveRecord::Base.logger.try(:debug, exception.backtrace)
+        raise ActiveRecord::Rollback
+      end
+
+    end
+
+  end
+end

data/lib/archival_record_core/archival_record_active_record_methods.rb

@@ -0,0 +1,45 @@
+module ArchivalRecordCore
+  module ArchivalRecordActiveRecordMethods
+
+    def self.included(base)
+      base.extend ARClassMethods
+      base.send :include, ARInstanceMethods
+    end
+
+    module ARClassMethods
+
+      def archival?
+        included_modules.include?(ArchivalRecordCore::ArchivalRecord::InstanceMethods)
+      end
+
+    end
+
+    module ARInstanceMethods
+
+      def archival?
+        self.class.archival?
+      end
+
+    end
+
+    module ARRelationMethods
+
+      def archive_all!
+        error_message = "The #{klass} must implement 'act_on_archivals' in order to call `archive_all!`"
+        raise NotImplementedError.new(error_message) unless archival?
+
+        head_archive_number = Digest::MD5.hexdigest("#{klass}#{Time.now.utc.to_i}")
+        each { |record| record.archive!(head_archive_number) }.tap { reset }
+      end
+
+      def unarchive_all!
+        error_message = "The #{klass} must implement 'act_on_archivals' in order to call `unarchive_all!`"
+        raise NotImplementedError.new(error_message) unless archival?
+
+        each(&:unarchive!).tap { reset }
+      end
+
+    end
+
+  end
+end

data/lib/archival_record_core/association_operation/archive.rb

@@ -0,0 +1,21 @@
+module ArchivalRecordCore
+  module ArchivalRecord
+    module AssociationOperation
+      class Archive < Base
+
+        protected
+
+        def act_on_archivals(archivals)
+          archivals.unarchived.find_each do |related_record|
+            raise ActiveRecord::Rollback unless related_record.archive!(head_archive_number)
+          end
+        end
+
+        def association_conditions_met?(association)
+          association.options[:dependent] == :destroy
+        end
+
+      end
+    end
+  end
+end

data/lib/archival_record_core/association_operation/base.rb

@@ -0,0 +1,54 @@
+module ArchivalRecordCore
+  module ArchivalRecord
+    module AssociationOperation
+      class Base
+
+        attr_reader :model, :head_archive_number
+
+        def initialize(model, head_archive_number)
+          @model = model
+          @head_archive_number = head_archive_number
+        end
+
+        def execute
+          each_archivable_association do |association|
+            act_on_association(association) if association_conditions_met? association
+          end
+        end
+
+        protected
+
+        def each_archivable_association
+          model.class.reflect_on_all_associations.each do |association|
+            yield(association) if archivable_association?(association)
+          end
+        end
+
+        def archivable_association?(association)
+          association.macro.to_s =~ /^has/ &&
+            association.klass.archival? &&
+            association.options[:through].nil?
+        end
+
+        def association_conditions_met?(_association)
+          true
+        end
+
+        def act_on_association(association)
+          key = association.respond_to?(:foreign_key) ? association.foreign_key : association.primary_key_name
+          scope_conditions = { key => model.id }
+          # polymorphic associations need a type so we don't accidentally act on multiple associated objects
+          # that have the same ID
+          scope_conditions[association.type] = model.class.base_class.name if association.type
+          scope = association.klass.where(scope_conditions)
+          act_on_archivals(scope)
+        end
+
+        def act_on_archivals(_scope)
+          raise NotImplementedError.new("The #{self.class} hasn't implemented 'act_on_archivals(scope)'")
+        end
+
+      end
+    end
+  end
+end

data/lib/archival_record_core/association_operation/unarchive.rb

@@ -0,0 +1,17 @@
+module ArchivalRecordCore
+  module ArchivalRecord
+    module AssociationOperation
+      class Unarchive < Base
+
+        protected
+
+        def act_on_archivals(scope)
+          scope.archived.where(archive_number: head_archive_number).find_each do |related_record|
+            raise ActiveRecord::Rollback unless related_record.unarchive!(head_archive_number)
+          end
+        end
+
+      end
+    end
+  end
+end