rails_audit_log 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa624cc1cc0ba6984f41de2f19b22891f9a7c376aae0625f94ebe86f2c48ef78
-  data.tar.gz: 75bfb038bb1fe170bdf1a893ec87c40b3e7711602ad355a9c0788d20558ef337
+  metadata.gz: 26fdf8335990094a7278cbcf9921e123fbf44f6ec464b974b1c73e1f41047691
+  data.tar.gz: 9700fef384bb8f23eb929b0c62cb82880ba8217a44f64660f97823c4ffe6f1c0
 SHA512:
-  metadata.gz: fd59c42a1522f4301e8c46c5b25186784847f5e56529fb7baf4d7b3d87d0f5391fb0bbcb33b8abac53bbf47a85a7529eae02d878c0484148a496b28950573541
-  data.tar.gz: 7b2be961c2b1f6091c1426d7be966ceb99647a7415faa4a540f3876d63ea6ff2a10fab515b61074b9538a7f43b63d99481c1743e35aeb09e313d2e76c4c3107f
+  metadata.gz: 8c0450b8f9228ec6ea98e7e026e0554d73004accf1a284433fa6260b5acd941d8314fd33b9bf873156e214f65f8bcd1d687613077f60c310dacd2a2b4e1f98e8
+  data.tar.gz: 733c560b234f96900a760cc76b74a18bd39303179e36ae8272c0f150560139272eb3fb0de9ee435883fbd2c128bd408b373601f407818ff9e5c72cb9c465e503

data/README.md

@@ -23,6 +23,8 @@ Audit logging for Rails. Tracks `create`, `update`, and `destroy` events as stru
   - [Bulk audit writes](#bulk-audit-writes)
   - [Async audit writes](#async-audit-writes)
   - [Capping history per record](#capping-history-per-record)
+  - [Time-based retention](#time-based-retention)
+  - [Scheduled and manual pruning](#scheduled-and-manual-pruning)
   - [Selective tracking](#selective-tracking)
   - [Disabling auditing](#disabling-auditing)
   - [Object reconstruction](#object-reconstruction)
@@ -95,6 +97,11 @@ RailsAuditLog.configure do |config|
   # Per-model `audit_log version_limit: N` takes precedence.
   # config.version_limit = 100
 
+  # Global time-based TTL — entries older than this duration are pruned after
+  # each write. Composes with version_limit: an entry is removed when it
+  # exceeds either constraint. Default: nil (no TTL)
+  # config.retention_period = 90.days
+
   # Write all audit entries asynchronously via WriteAuditLogJob.
   # Default: false — per-model `audit_log async: true` also works.
   # config.async = true
@@ -323,6 +330,45 @@ Set a global default in an initializer — per-model values take precedence:
 RailsAuditLog.version_limit = 50
 ```
 
+### Time-based retention
+
+Automatically prune entries older than a configured duration by setting `retention_period` in an initializer:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.retention_period = 90.days
+```
+
+Entries whose `created_at` is older than the period are deleted after each write. `retention_period` and `version_limit` compose — an entry is pruned when it exceeds **either** constraint.
+
+Override the global default per model with `retain_for:`:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log retain_for: 30.days  # takes precedence over RailsAuditLog.retention_period
+end
+```
+
+### Scheduled and manual pruning
+
+`RailsAuditLog::PruneAuditLogJob` prunes all audited models in one pass. It iterates over every `item_type` present in `audit_log_entries`, resolves the effective `retain_for` / `retention_period` and `version_limit` per model, and deletes entries that exceed either constraint.
+
+Enqueue it on a recurring schedule via your job backend:
+
+```ruby
+# config/recurring.yml (Solid Queue)
+prune_audit_log:
+  class: RailsAuditLog::PruneAuditLogJob
+  schedule: every day at midnight
+```
+
+Or run it once manually via the rake task:
+
+```bash
+bin/rails rails_audit_log:prune
+```
+
 ### Selective tracking
 
 Track only specific attributes, or exclude noisy ones:
@@ -575,13 +621,13 @@ refute_audit_log_entry post, event: :destroy
 | `.connects_to=` | Route `AuditLogEntry` to a separate database |
 | `.page_size=` | Entries per page in the web dashboard |
 | `.whodunnit_display=` | Proc for actor display name snapshot |
-| `.retention_period=` | _(1.1.0)_ Global time-based TTL |
+| `.retention_period=` | Global time-based TTL for audit entries |
 
 **Concerns**
 
 | Class | Include in | Key methods |
 |---|---|---|
-| `RailsAuditLog::Auditable` | ActiveRecord models | `audit_log(only:, ignore:, meta:, associations:, version_limit:, async:)`, `skip_audit_log { }` |
+| `RailsAuditLog::Auditable` | ActiveRecord models | `audit_log(only:, ignore:, meta:, associations:, version_limit:, retain_for:, async:)`, `skip_audit_log { }` |
 | `RailsAuditLog::Controller` | ActionController | `audit_log_actor { }` |
 
 **Model — `RailsAuditLog::AuditLogEntry`**
@@ -600,10 +646,12 @@ Constants: `EVENTS`, `BLOB_COLUMNS`, `PERIODS`
 | `RailsAuditLog::MinitestAssertions` | `require "rails_audit_log/minitest_assertions"` | Minitest: `assert_audit_log_entry`, `refute_audit_log_entry` |
 | `RailsAuditLog::TestHelpers` | `require "rails_audit_log/test_helpers"` | `without_audit_log { }` |
 
-**Jobs** (enqueued internally; configure via ActiveJob)
+**Jobs** (configure via ActiveJob)
 
 `RailsAuditLog::WriteAuditLogJob` — do not instantiate directly; enqueued when `async: true` is set.
 
+`RailsAuditLog::PruneAuditLogJob` — enqueue on a schedule to prune all audited models; also invoked by `bin/rails rails_audit_log:prune`.
+
 **Generators**
 
 `rails generate rails_audit_log:install` · `rails generate rails_audit_log:initializer`

data/app/concerns/rails_audit_log/auditable.rb

@@ -28,6 +28,7 @@ module RailsAuditLog
       class_attribute :_audit_log_meta,           default: nil
       class_attribute :_audit_log_associations,   default: nil
       class_attribute :_audit_log_version_limit,  default: nil
+      class_attribute :_audit_log_retain_for,     default: nil
       class_attribute :_audit_log_async,          default: false
 
       _warn_if_audit_table_missing
@@ -105,6 +106,9 @@ module RailsAuditLog
       # @param version_limit [Integer, nil] maximum number of entries to retain
       #   per record; oldest entries are pruned after each write; overrides
       #   {RailsAuditLog.version_limit} for this model
+      # @param retain_for [ActiveSupport::Duration, nil] per-model time-based TTL;
+      #   entries older than this duration are pruned after each write; overrides
+      #   {RailsAuditLog.retention_period} for this model
       # @param async [Boolean, nil] when +true+, writes are dispatched via
       #   +WriteAuditLogJob+; overrides {RailsAuditLog.async} for this model
       # @return [void]
@@ -114,14 +118,16 @@ module RailsAuditLog
       #     audit_log only: %i[title body published_at],
       #               meta: { tenant_id: -> { Current.tenant_id } },
       #               associations: %i[tags],
-      #               version_limit: 100
+      #               version_limit: 100,
+      #               retain_for: 30.days
       #   end
-      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, async: nil)
+      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, retain_for: nil, async: nil)
         self._audit_log_only          = only.map(&:to_s)   if only
         self._audit_log_ignore        = ignore.map(&:to_s) if ignore
         self._audit_log_meta          = meta                if meta
         self._audit_log_associations  = associations        unless associations.nil?
         self._audit_log_version_limit = version_limit       unless version_limit.nil?
+        self._audit_log_retain_for    = retain_for          unless retain_for.nil?
         self._audit_log_async         = async               unless async.nil?
       end
     end
@@ -199,8 +205,9 @@ module RailsAuditLog
       if (buffer = RailsAuditLog.batch_audit_buffer)
         buffer << entry_attrs.stringify_keys.merge("created_at" => Time.current)
       elsif _audit_log_async || RailsAuditLog.async
-        limit = self.class._audit_log_version_limit || RailsAuditLog.version_limit
-        WriteAuditLogJob.perform_later(entry_attrs.stringify_keys, version_limit: limit)
+        limit  = self.class._audit_log_version_limit || RailsAuditLog.version_limit
+        period = self.class._audit_log_retain_for || RailsAuditLog.retention_period
+        WriteAuditLogJob.perform_later(entry_attrs.stringify_keys, version_limit: limit, retention_period: period)
       else
         RailsAuditLog::AuditLogEntry.create!(entry_attrs)
         prune_audit_entries
@@ -208,14 +215,19 @@ module RailsAuditLog
     end
 
     def prune_audit_entries
-      limit = self.class._audit_log_version_limit || RailsAuditLog.version_limit
-      return unless limit
+      limit  = self.class._audit_log_version_limit || RailsAuditLog.version_limit
+      period = self.class._audit_log_retain_for || RailsAuditLog.retention_period
+      return unless limit || period
 
-      count = audit_log_entries.count
-      excess = count - limit
-      return unless excess > 0
+      if period
+        audit_log_entries.where(created_at: ..period.ago).delete_all
+      end
 
-      audit_log_entries.order(id: :asc).limit(excess).delete_all
+      if limit
+        count  = audit_log_entries.count
+        excess = count - limit
+        audit_log_entries.order(id: :asc).limit(excess).delete_all if excess > 0
+      end
     end
 
     def build_audit_metadata

data/app/jobs/rails_audit_log/prune_audit_log_job.rb

@@ -0,0 +1,58 @@
+module RailsAuditLog
+  # Background job that prunes {AuditLogEntry} records for every audited model
+  # that has a configured retention policy.
+  #
+  # Enqueue on a recurring schedule via your job backend (Solid Queue,
+  # Sidekiq, GoodJob, etc.):
+  #
+  #   RailsAuditLog::PruneAuditLogJob.perform_later
+  #
+  # The job iterates over every +item_type+ present in +audit_log_entries+,
+  # resolves the effective +retention_period+ / +version_limit+ for that model,
+  # and deletes entries that exceed either constraint. Pruning is always scoped
+  # to one +item_type+ at a time so models do not interfere with each other.
+  class PruneAuditLogJob < ApplicationJob
+    def perform
+      AuditLogEntry.distinct.pluck(:item_type).each do |item_type|
+        prune_item_type(item_type)
+      end
+    end
+
+    private
+
+    def prune_item_type(item_type)
+      klass  = item_type.safe_constantize
+      period = resolve_period(klass)
+      limit  = resolve_limit(klass)
+      return unless period || limit
+
+      scope = AuditLogEntry.where(item_type: item_type)
+
+      scope.where(created_at: ..period.ago).delete_all if period
+
+      return unless limit
+
+      scope.select(:item_id).distinct.pluck(:item_id).each do |item_id|
+        record_scope = scope.where(item_id: item_id)
+        excess       = record_scope.count - limit
+        record_scope.order(id: :asc).limit(excess).delete_all if excess > 0
+      end
+    end
+
+    def resolve_period(klass)
+      if klass.respond_to?(:_audit_log_retain_for)
+        klass._audit_log_retain_for || RailsAuditLog.retention_period
+      else
+        RailsAuditLog.retention_period
+      end
+    end
+
+    def resolve_limit(klass)
+      if klass.respond_to?(:_audit_log_version_limit)
+        klass._audit_log_version_limit || RailsAuditLog.version_limit
+      else
+        RailsAuditLog.version_limit
+      end
+    end
+  end
+end

data/app/jobs/rails_audit_log/write_audit_log_job.rb

@@ -1,20 +1,21 @@
 module RailsAuditLog
   class WriteAuditLogJob < ApplicationJob
-    def perform(entry_attrs, version_limit: nil)
+    def perform(entry_attrs, version_limit: nil, retention_period: nil)
       AuditLogEntry.create!(entry_attrs)
 
-      return unless version_limit
-
       item_type = entry_attrs["item_type"]
       item_id   = entry_attrs["item_id"]
-      count     = AuditLogEntry.where(item_type: item_type, item_id: item_id).count
-      excess    = count - version_limit
-      return unless excess > 0
+      scope     = AuditLogEntry.where(item_type: item_type, item_id: item_id)
+
+      if retention_period
+        scope.where(created_at: ..retention_period.ago).delete_all
+      end
 
-      AuditLogEntry.where(item_type: item_type, item_id: item_id)
-                   .order(id: :asc)
-                   .limit(excess)
-                   .delete_all
+      if version_limit
+        count  = scope.count
+        excess = count - version_limit
+        scope.order(id: :asc).limit(excess).delete_all if excess > 0
+      end
     end
   end
 end

data/lib/generators/rails_audit_log/initializer/templates/rails_audit_log.rb

@@ -22,6 +22,11 @@ RailsAuditLog.configure do |config|
   # Per-model `audit_log version_limit: N` takes precedence.
   # config.version_limit = 100
 
+  # Global time-based TTL — entries older than this duration are pruned after
+  # each write. Composes with version_limit: an entry is removed when it
+  # exceeds either constraint. Default: nil (no TTL)
+  # config.retention_period = 90.days
+
   # Write all audit entries asynchronously via WriteAuditLogJob. Default: false
   # Per-model `audit_log async: true` also works.
   # config.async = true

data/lib/rails_audit_log/version.rb

@@ -1,3 +1,3 @@
 module RailsAuditLog
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/rails_audit_log.rb

@@ -53,6 +53,16 @@ module RailsAuditLog
   # @return [Integer, nil]
   mattr_accessor :version_limit, default: nil
 
+  # Global time-based TTL for audit entries. Entries whose +created_at+ is
+  # older than this duration are pruned automatically after each write.
+  # Composes with {.version_limit} — an entry is removed when it exceeds
+  # either constraint.
+  #
+  # @return [ActiveSupport::Duration, nil]
+  # @example
+  #   RailsAuditLog.retention_period = 90.days
+  mattr_accessor :retention_period, default: nil
+
   # When +true+, all audit writes are dispatched via +WriteAuditLogJob+ instead
   # of being written inline. Override per-model with <tt>audit_log async: true</tt>.
   #

data/lib/tasks/rails_audit_log_tasks.rake

@@ -1,4 +1,7 @@
-# desc "Explaining what the task does"
-# task :rails_audit_log do
-#   # Task goes here
-# end
+namespace :rails_audit_log do
+  desc "Prune audit log entries that exceed the configured retention_period or version_limit. " \
+       "Delegates to RailsAuditLog::PruneAuditLogJob."
+  task prune: :environment do
+    RailsAuditLog::PruneAuditLogJob.perform_now
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -98,6 +98,7 @@ files:
 - app/javascript/rails_audit_log/diff_controller.js
 - app/javascript/rails_audit_log/search_controller.js
 - app/jobs/rails_audit_log/application_job.rb
+- app/jobs/rails_audit_log/prune_audit_log_job.rb
 - app/jobs/rails_audit_log/write_audit_log_job.rb
 - app/models/rails_audit_log/application_record.rb
 - app/models/rails_audit_log/audit_log_entry.rb