active_record-undo 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3463f7d5263618417b5dc0bda22a13f8185b349c24d8b4e1610657afc5509564
-  data.tar.gz: d89197a34b065986d1f0060a83b6d5284af254ec4e9d2710de48549f60078e55
+  metadata.gz: aedb1b7356b0530c7316c1c94a4f2681cf4c103cb50986e24dfaa1f5d1eec553
+  data.tar.gz: 33f779d1c31b5c80126fa4838b8f080f512e25dca9dd372d88e3ff1d9a1b4eaa
 SHA512:
-  metadata.gz: 6daed055a8e31d9ce9386c92943b9e07133ca69aa0f782412d032e090491cfcc080054359fa7e9340b78563addf9dc17cf3cc6dabed4baffda12a611bf32e5ff
-  data.tar.gz: 3259b19bec3a4519ad5dda5b3d56dc94ff3ff6c4d4853fb81cdde33556cbbc530689875863a00893ac277bd042f9153261f4413ff0ad6a9dd87fcc26d09d6091
+  metadata.gz: 982b77e10592f7e0599d080b74d5c9daa4658c9df14e8a068b95dd00d51cacd33e813e5250e88b3fedc134fbfbe66fde57a6ad62c089b0dd2ce32a56c2597332
+  data.tar.gz: 177f71075ba0e65a2e372fbfc9afb4783248c29eb164955cf7449706257e82759d38e86b0eefad18b89a4b4a17ee335c8d589be65b6d288ff0126ccf9fafd7ab

data/DOCUMENTATION.md

@@ -49,6 +49,10 @@ graph TD
 | **Audit Log Parent** | `lib/active_record/undo/undo_log.rb` | `UndoLog` | Represents the top-level deletion event and manages atomic batch restoration |
 | **Audit Log Child** | `lib/active_record/undo/undo_log_item.rb` | `UndoLogItem` | Maps polymorphic targets (`item_type`, `item_id`) to original deleted entities |
 | **Engine Link** | `lib/active_record/undo/engine.rb` | `Engine` | Appends `db/migrate/` directly to host app migration paths |
+| **Configuration** | `lib/active_record/undo/configuration.rb` | `Configuration` | Houses retention_period settings |
+| **Purger Service** | `lib/active_record/undo/purger.rb` | `Purger` | Deletes expired UndoLog/Items and soft-deleted model records in batches |
+| **Purge Job** | `lib/active_record/undo/purge_job.rb` | `PurgeJob` | ActiveJob background runner invoking Purger |
+| **Rake Task** | `lib/active_record/undo/tasks/purge.rake` | Rake Task | Exposes `active_record_undo:purge_expired` command |
 
 ---
 
@@ -202,6 +206,7 @@ sequenceDiagram
     - `undoable_column`: Caches the name of the column (defaults to `:deleted_at`).
     - `kept` scope: Returns records that are not soft-deleted (`where(column => nil)`).
     - `soft_deleted` scope: Returns records that are soft-deleted (`where.not(column => nil)`).
+    - `expired` scope: Returns records soft-deleted before the global retention period threshold.
 * **`soft_deleted?`**
   - *Function*: Checks if the current record instance has been soft-deleted. Returns `true` if the configured deletion column is populated with a timestamp.
 * **`undoable?`**
@@ -227,6 +232,7 @@ sequenceDiagram
     3. Resolves the latest `UndoLogItem` that records the soft-deletion of this instance.
     4. If a log item is found, it calls `restore!` on the parent `UndoLog` (which restores the entire deleted tree).
     5. If no log item is found, it falls back to a simple, direct restore by setting the deletion column back to `nil`.
+    6. Automatically reloads the instance attributes in-memory (using `reload`) to refresh the model state before returning `true`.
 * **`ensure_undoable_column_exists!` (Private)**
   - *Function*: Asserts that the configured soft-delete column exists in the database schema table. Raises `ActiveRecord::Undo::Error` if missing.
 * **`find_latest_undo_log_item` (Private)**
@@ -289,4 +295,31 @@ sequenceDiagram
 * **`ensure_column_exists!(klass, column_name)` (Private)**
   - *Function*: Confirms that the target soft-delete column exists in the class's table schema. Throws `ActiveRecord::Undo::Error` if missing.
 * **`reset_soft_delete_column!(target, column_name)` (Private)**
-  - *Function*: Bypasses standard callbacks and validations to write a `nil` value to the soft-delete column directly in the database.
+  - *Function*: Bypasses standard callbacks and validations to write a `nil` value to the soft-delete column directly in the database.
+
+### 6.9 `lib/active_record/undo/configuration.rb` (Global Configuration)
+
+* **`Configuration#initialize`**
+  - *Function*: Instantiates default configurations for the gem.
+  - *Details*: Sets default `@retention_period` to `30.days`.
+
+### 6.10 `lib/active_record/undo/purger.rb` (Hard Purging Engine)
+
+* **`Purger.purge_expired!(batch_size: 1000)`**
+  - *Function*: Cleans up all database records and logs that are past their retention limits.
+  - *Steps*:
+    1. Delegates to `purge_expired_logs!(batch_size)` to find and clean up expired `UndoLog` and `UndoLogItem` entries in batches using direct SQL `delete_all` execution.
+    2. Delegates to `purge_expired_records!(batch_size)` to eager-load the host Rails application models (preventing Zeitwerk lazy-load gaps), identify expired records via the `.expired` scope, and hard-delete them and their cascading dependent associations in batches.
+  - *Relational Integrity & Constraint Protection*: Bottom-up recursive cascading deletes are performed first for associations marked as `:destroy`, `:delete_all`, or `:soft_delete`. For `:nullify` configurations, foreign key values are updated to `nil`, falling back to cascading deletion if the column contains a database-level `NOT NULL` constraint.
+
+### 6.11 `lib/active_record/undo/purge_job.rb` (Background Task Worker)
+
+* **`PurgeJob#perform(batch_size: 1000)`**
+  - *Function*: Runs inside ActiveJob (when available) to execute purging asynchronously.
+  - *Details*: Invokes `ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)`.
+
+### 6.12 `lib/active_record/undo/tasks/purge.rake` (Command Line Utility)
+
+* **`active_record_undo:purge_expired`**
+  - *Function*: Exposes CLI Rake task for the purger engine.
+  - *Details*: Checks `ENV['BATCH_SIZE']` for custom batch sizes, falling back to 1000, and triggers `ActiveRecord::Undo::Purger.purge_expired!`.

data/README.md

@@ -18,6 +18,7 @@ Unlike conventional soft-deletion gems, `active_record-undo` automatically captu
 - 📦 **Polymorphic Tracking:** Records deletion events via native `UndoLog` and `UndoLogItem` models—no messy JSON payload parsing required.
 - 🚂 **Zero Generator Setup:** Built on top of `Rails::Engine`. Migrations automatically hook into `rails db:migrate`.
 - 🔍 **Default Scopes & Helpers:** Provides `.kept`, `.soft_deleted`, `#soft_deleted?`, and `#undoable?` query methods out of the box.
+- 🧹 **Automatic Expiration & Purging:** Configurable global retention window with automated background purging (`PurgeJob` and Rake task) to clean up old soft-deleted records and logs.
 
 ---
 
@@ -158,11 +159,11 @@ To restore a deleted object tree, you can invoke `restore!` either on the corres
 Calling `restore!` directly on the soft-deleted model automatically resolves its latest deletion event log, performs the cascading restore, and cleans up the log database rows:
 
 ```ruby
-# Restores the post and all comments deleted in the same batch
+# Restores the post and all comments deleted in the same batch (automatically reloads in-memory)
 post.restore!
 
-post.reload.soft_deleted? # => false
-post.comments.count       # => 2
+post.soft_deleted?  # => false
+post.comments.count # => 2
 ```
 
 #### Option B: Restore from the `UndoLog`
@@ -199,6 +200,75 @@ Post.unscoped.where(id: 1)
 
 ---
 
+## Expiration, Retention & Auto-Purging
+
+To prevent database bloat, `active_record-undo` supports automated retention periods, expiration checks, and background purging for both soft-deleted records and their associated `UndoLog` audit entries.
+
+### 1. Global Configuration
+
+You can configure a global retention period inside a Rails initializer:
+
+```ruby
+# config/initializers/active_record_undo.rb
+ActiveRecord::Undo.configure do |config|
+  # Default retention period for all soft-deleted records and undo logs (defaults to 30.days)
+  config.retention_period = 30.days
+end
+```
+
+If `retention_period` is set to `nil`, records and logs will never expire.
+
+### 2. Expiration Scopes & Helpers
+
+The gem provides query scopes and instance predicate helpers:
+
+- **Model `.expired` Scope**: Returns soft-deleted records older than the configured retention period.
+  ```ruby
+  Post.expired # => ActiveRecord::Relation of posts soft-deleted > 30 days ago
+  ```
+- **Model `#expired?` Predicate**: Checks if a record is soft-deleted and past the retention period.
+  ```ruby
+  post.expired? # => true/false
+  ```
+- **`UndoLog.expired` Scope**: Returns undo log entries older than the retention period.
+  ```ruby
+  ActiveRecord::Undo::UndoLog.expired # => logs created > 30 days ago
+  ```
+
+### 3. Background Purging
+
+#### Purger Service
+The `ActiveRecord::Undo::Purger` class performs hard SQL deletes on expired records and logs using `delete_all` (bypassing callbacks and validations for efficiency):
+
+```ruby
+# Purge all expired soft-deleted records and undo logs in batches
+ActiveRecord::Undo::Purger.purge_expired!(batch_size: 1000)
+```
+
+> [!NOTE]
+> **Relational Integrity & Constraint Protection**: To prevent database-level foreign key constraint failures (e.g. `FOREIGN KEY constraint failed`), `Purger` dynamically resolves dependent associations (such as `dependent: :destroy`, `dependent: :delete_all`, or `dependent: :soft_delete`) and recursively purges associated child records bottom-up before deleting the parent record. For associations configured with `dependent: :nullify`, it nullifies the foreign key (or cascades the deletion if the foreign key column is database-restricted to be `NOT NULL`).
+
+#### ActiveJob Background Job
+The gem provides an ActiveJob class that calls the Purger service:
+
+```ruby
+# Enqueue the purge job to run in the background
+ActiveRecord::Undo::PurgeJob.perform_later(batch_size: 1000)
+```
+
+#### Engine Rake Task
+You can run the purge task via Rake. This task is automatically loaded into host applications:
+
+```bash
+# Run with the default batch size of 1000
+$ rails active_record_undo:purge_expired
+
+# Run with a custom batch size
+$ BATCH_SIZE=500 rails active_record_undo:purge_expired
+```
+
+---
+
 ## How It Works
 
 1. **Cascade Inspection:** When `soft_delete!` is called, `ActiveRecord::Undo::CascadeHandler` reflects on `has_many`, `has_one`, and `belongs_to` associations configured with `dependent: :destroy` or `:delete_all`.

data/lib/active_record/undo/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class Configuration
+      attr_accessor :retention_period
+
+      def initialize
+        @retention_period = 30.days
+      end
+    end
+  end
+end

data/lib/active_record/undo/engine.rb

@@ -14,6 +14,11 @@ module ActiveRecord
           end
         end
       end
+
+      rake_tasks do
+        path = root.join('lib', 'tasks', 'active_record_undo_tasks.rake')
+        load path if File.exist?(path)
+      end
     end
   end
 end

data/lib/active_record/undo/model_extension.rb

@@ -8,18 +8,44 @@ module ActiveRecord
     module ModelExtension
       extend ActiveSupport::Concern
 
-      class_methods do
+      module ClassMethods
         # Accept a custom column parameter, defaulting to :deleted_at
         def acts_as_undoable(column: :deleted_at)
           include InstanceMethods
 
+          define_undo_attributes!(column)
+          define_undo_scopes!
+
+          ActiveRecord::Undo.registered_models << self
+        end
+
+        private
+
+        def define_undo_attributes!(column)
           class_attribute :undoable_column
           self.undoable_column = column.to_sym
+        end
+
+        def define_undo_scopes!
+          define_basic_scopes!
+          define_expired_scope!
+        end
 
-          # Dynamic scopes using the configured column
+        def define_basic_scopes!
           scope :kept, -> { where(undoable_column => nil) }
           scope :soft_deleted, -> { where.not(undoable_column => nil) }
         end
+
+        def define_expired_scope!
+          scope :expired, lambda {
+            period = ActiveRecord::Undo.config.retention_period
+            if period
+              where("#{table_name}.#{undoable_column} < ?", Time.current - period)
+            else
+              none
+            end
+          }
+        end
       end
 
       module InstanceMethods
@@ -27,6 +53,16 @@ module ActiveRecord
           public_send(self.class.undoable_column).present?
         end
 
+        def expired?
+          return false unless soft_deleted?
+
+          period = ActiveRecord::Undo.config.retention_period
+          return false unless period
+
+          timestamp = public_send(self.class.undoable_column)
+          timestamp && timestamp < Time.current - period
+        end
+
         def undoable?
           return false unless soft_deleted?
 
@@ -52,20 +88,16 @@ module ActiveRecord
           undo_log
         end
 
+        # rubocop:disable Naming/PredicateMethod
         def restore!
           ensure_undoable_column_exists!
           return false unless soft_deleted?
 
-          log_item = find_latest_undo_log_item
-
-          if log_item
-            log_item.undo_log.restore!
-          else
-            column_name = self.class.undoable_column
-            update_columns(column_name => nil, updated_at: Time.current)
-            true
-          end
+          restore_internally!(find_latest_undo_log_item)
+          reload
+          true
         end
+        # rubocop:enable Naming/PredicateMethod
 
         private
 
@@ -88,6 +120,15 @@ module ActiveRecord
         def soft_delete_cascade_internal!(timestamp, undo_log)
           CascadeHandler.new(self).soft_delete_with_cascade!(timestamp, undo_log)
         end
+
+        def restore_internally!(log_item)
+          if log_item
+            log_item.undo_log.restore!
+          else
+            column_name = self.class.undoable_column
+            update_columns(column_name => nil, updated_at: Time.current)
+          end
+        end
       end
     end
   end

data/lib/active_record/undo/purge_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+begin
+  require 'active_job'
+rescue LoadError
+  # ActiveJob is not available
+end
+
+if defined?(ActiveJob::Base)
+  module ActiveRecord
+    module Undo
+      class PurgeJob < ActiveJob::Base
+        queue_as :default
+
+        def perform(batch_size: 1000)
+          ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/purger.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Undo
+    class Purger
+      class << self
+        def purge_expired!(batch_size: 1000)
+          purge_expired_logs!(batch_size)
+          purge_expired_records!(batch_size)
+        end
+
+        private
+
+        def purge_expired_logs!(batch_size)
+          loop do
+            log_ids = UndoLog.expired.limit(batch_size).pluck(:id)
+            break if log_ids.empty?
+
+            UndoLogItem.where(undo_log_id: log_ids).delete_all
+            UndoLog.where(id: log_ids).delete_all
+          end
+        end
+
+        def purge_expired_records!(batch_size)
+          period = ActiveRecord::Undo.config.retention_period
+          return unless period
+
+          ActiveRecord::Undo.undoable_models.each do |model|
+            purge_model_expired_records!(model, batch_size)
+          end
+        end
+
+        def purge_model_expired_records!(model, batch_size)
+          primary_key = model.primary_key
+          loop do
+            expired_ids = model.expired.limit(batch_size).pluck(primary_key)
+            break if expired_ids.empty?
+
+            purge_records_with_cascade!(model, expired_ids, batch_size)
+          end
+        end
+
+        def purge_records_with_cascade!(model, record_ids, batch_size)
+          return if record_ids.empty?
+
+          nullify_dependent_associations!(model, record_ids)
+          purge_cascading_associations!(model, record_ids, batch_size)
+          delete_records!(model, record_ids)
+        end
+
+        def nullify_dependent_associations!(model, record_ids)
+          nullify_reflections(model).each do |reflection|
+            child_query_for(model, reflection, record_ids).update_all(reflection.foreign_key => nil)
+          end
+        end
+
+        def purge_cascading_associations!(model, record_ids, batch_size)
+          cascade_reflections(model).each do |reflection|
+            query = child_query_for(model, reflection, record_ids)
+            primary_key = reflection.klass.primary_key
+
+            query.pluck(primary_key).each_slice(batch_size) do |child_ids|
+              purge_records_with_cascade!(reflection.klass, child_ids, batch_size)
+            end
+          end
+        end
+
+        def child_query_for(model, reflection, record_ids)
+          query = reflection.klass.unscoped.where(reflection.foreign_key => record_ids)
+          query = query.where(reflection.type => model.name) if reflection.type
+          query
+        end
+
+        def delete_records!(model, record_ids)
+          model.unscoped.where(model.primary_key => record_ids).delete_all
+        end
+
+        def nullify_reflections(model)
+          model.reflections.values.select do |ref|
+            %i[has_many has_one].include?(ref.macro) &&
+              ref.options[:dependent] == :nullify &&
+              foreign_key_nullable?(ref)
+          end
+        end
+
+        def cascade_reflections(model)
+          model.reflections.values.select do |ref|
+            next false unless %i[has_many has_one].include?(ref.macro)
+
+            dependent = ref.options[:dependent]
+            %i[destroy soft_delete delete_all].include?(dependent) ||
+              non_nullable_nullify?(ref)
+          end
+        end
+
+        def non_nullable_nullify?(ref)
+          ref.options[:dependent] == :nullify && !foreign_key_nullable?(ref)
+        end
+
+        def foreign_key_nullable?(ref)
+          column = ref.klass.columns_hash[ref.foreign_key.to_s]
+          column.nil? || column.null
+        end
+      end
+    end
+  end
+end

data/lib/active_record/undo/tasks/purge.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :active_record_undo do
+  desc 'Purge expired soft-deleted records and undo logs'
+  task purge_expired: :environment do
+    batch_size = ENV['BATCH_SIZE'] ? ENV['BATCH_SIZE'].to_i : 1000
+    ActiveRecord::Undo::Purger.purge_expired!(batch_size: batch_size)
+  end
+end

data/lib/active_record/undo/undo_log.rb

@@ -8,6 +8,15 @@ module ActiveRecord
 
       has_many :undo_log_items, class_name: 'ActiveRecord::Undo::UndoLogItem', dependent: :destroy
 
+      scope :expired, lambda {
+        period = ActiveRecord::Undo.config.retention_period
+        if period
+          where('created_at < ?', Time.current - period)
+        else
+          none
+        end
+      }
+
       # Restores all records associated with this deletion batch
       def restore!
         transaction do

data/lib/active_record/undo/version.rb

@@ -3,6 +3,6 @@
 
 module ActiveRecord
   module Undo
-    VERSION = '0.1.3'
+    VERSION = '0.1.4'
   end
 end

data/lib/active_record/undo.rb

@@ -9,15 +9,52 @@ rescue LoadError => e
         "Please add 'activerecord' to your Gemfile. (Original error: #{e.message})"
 end
 
+require 'set'
 require_relative 'undo/version'
 require_relative 'undo/engine' if defined?(Rails::Engine)
+require_relative 'undo/configuration'
 require_relative 'undo/model_extension'
 require_relative 'undo/undo_log'
 require_relative 'undo/undo_log_item'
+require_relative 'undo/purger'
+require_relative 'undo/purge_job'
 
 module ActiveRecord
   module Undo
     class Error < StandardError; end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield(config)
+      end
+
+      def registered_models
+        @registered_models ||= Set.new
+      end
+
+      def undoable_models
+        eager_load_rails!
+        models = registered_models.to_a
+        if defined?(ActiveRecord::Base)
+          models += ActiveRecord::Base.descendants.select { |m| m.respond_to?(:undoable_column) }
+        end
+        models.uniq
+      end
+
+      private
+
+      def eager_load_rails!
+        return unless defined?(Rails) && Rails.application
+
+        Rails.application.eager_load!
+      rescue StandardError
+        # Safe fallback if Rails eager loading fails in test environments
+      end
+    end
   end
 end
 

data/lib/tasks/active_record_undo_tasks.rake

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+path = File.expand_path('../active_record/undo/tasks/purge.rake', __dir__)
+load path if File.exist?(path)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record-undo
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Saurabh Sharma
@@ -141,11 +141,16 @@ files:
 - lib/active_record/undo/cascade_handler.rb
 - lib/active_record/undo/cascade_handler/association_finder.rb
 - lib/active_record/undo/cascade_handler/record_updater.rb
+- lib/active_record/undo/configuration.rb
 - lib/active_record/undo/engine.rb
 - lib/active_record/undo/model_extension.rb
+- lib/active_record/undo/purge_job.rb
+- lib/active_record/undo/purger.rb
+- lib/active_record/undo/tasks/purge.rake
 - lib/active_record/undo/undo_log.rb
 - lib/active_record/undo/undo_log_item.rb
 - lib/active_record/undo/version.rb
+- lib/tasks/active_record_undo_tasks.rake
 - sig/active_record/undo.rbs
 homepage: https://github.com/saurabh-activecode/active_record-undo
 licenses: