rails_audit_log 0.9.0 → 1.1.0

data/app/concerns/rails_audit_log/controller.rb

@@ -1,4 +1,21 @@
 module RailsAuditLog
+  # Include in +ApplicationController+ (or any controller) to automatically
+  # set and clear the current actor for every request, so that audit entries
+  # written during the request are tagged with the signed-in user.
+  #
+  # == Usage
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include RailsAuditLog::Controller
+  #     audit_log_actor { current_user }
+  #   end
+  #
+  # The block passed to {audit_log_actor} is evaluated in controller instance
+  # context on every request via a +before_action+. The actor is cleared in an
+  # +after_action+ so it never leaks between requests.
+  #
+  # Request metadata (+remote_ip+, +user_agent+) is captured automatically when
+  # {RailsAuditLog.capture_request_metadata} is +true+.
   module Controller
     extend ActiveSupport::Concern
 
@@ -10,10 +27,22 @@ module RailsAuditLog
     end
 
     class_methods do
+      # Registers a block that resolves the current actor for each request.
+      # The block is evaluated in controller instance context, so any helper
+      # method available to the controller (e.g. +current_user+) can be used.
+      #
+      # @yield block evaluated in controller context; should return the actor
+      # @return [void]
+      # @example
+      #   audit_log_actor { current_user }
+      #
+      #   # With a one-argument lambda style (actor = the controller instance)
+      #   audit_log_actor { |c| c.current_user }
       def audit_log_actor(&block)
         @audit_log_actor_block = block
       end
 
+      # @api private
       def audit_log_actor_block
         @audit_log_actor_block
       end

data/app/controllers/rails_audit_log/application_controller.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class ApplicationController < ActionController::Base
     include Pagy::Method
 

data/app/controllers/rails_audit_log/audit_log_entries_controller.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class AuditLogEntriesController < ApplicationController
     def index
       set_filters

data/app/controllers/rails_audit_log/resources_controller.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class ResourcesController < ApplicationController
     def show
       @item_type = params[:item_type]

data/app/helpers/rails_audit_log/application_helper.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   module ApplicationHelper
     def format_diff_value(value)
       return "—" if value.nil?

data/app/jobs/rails_audit_log/application_job.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class ApplicationJob < ActiveJob::Base
   end
 end

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/app/models/rails_audit_log/application_record.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
   end

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -1,4 +1,23 @@
 module RailsAuditLog
+  # Represents a single audited event (+create+, +update+, or +destroy+) for
+  # one ActiveRecord record.
+  #
+  # == Columns
+  #
+  # [event]               One of <tt>"create"</tt>, <tt>"update"</tt>, <tt>"destroy"</tt>.
+  # [item_type]           Class name of the audited record (e.g. <tt>"Article"</tt>).
+  # [item_id]             Primary key of the audited record.
+  # [object_changes]      JSON hash of attribute changes in <tt>[from, to]</tt> form.
+  #                       All three event types use the same format:
+  #                       +create+ stores <tt>[nil, new]</tt> for every column,
+  #                       +update+ stores <tt>[old, new]</tt> for changed columns only,
+  #                       +destroy+ stores <tt>[final, nil]</tt> for every column.
+  # [object]              JSON snapshot of the record's full attributes before the
+  #                       change (stored when {RailsAuditLog.store_snapshot} is +true+).
+  # [whodunnit_snapshot]  Display name of the actor at the time of the change.
+  # [actor_type / actor_id] Polymorphic reference to the actor record.
+  # [reason]              Optional free-text reason string.
+  # [metadata]            Arbitrary JSON hash (request IP, custom lambdas, etc.).
   class AuditLogEntry < ApplicationRecord
     self.table_name = "audit_log_entries"
 
@@ -6,33 +25,63 @@ module RailsAuditLog
     BLOB_COLUMNS = %w[object_changes object metadata].freeze
     PERIODS      = { "1h" => 1.hour, "24h" => 24.hours, "7d" => 7.days }.freeze
 
+    # @api private
     def self.configure_connection!
       return unless (opts = RailsAuditLog.connects_to)
 
       connects_to(**opts)
     end
 
-    belongs_to :item, polymorphic: true, optional: true
+    belongs_to :item,  polymorphic: true, optional: true
     belongs_to :actor, polymorphic: true, optional: true
 
-    validates :event, presence: true, inclusion: { in: EVENTS }
+    validates :event,     presence: true, inclusion: { in: EVENTS }
     validates :item_type, presence: true
-    validates :item_id, presence: true
-    validate :metadata_must_be_a_hash
+    validates :item_id,   presence: true
+    validate  :metadata_must_be_a_hash
 
-    # Event scopes
+    # @!group Event scopes
+
+    # Entries for +create+ events.
+    # @return [ActiveRecord::Relation]
     scope :created_events,  -> { where(event: "create") }
+
+    # Entries for +update+ events.
+    # @return [ActiveRecord::Relation]
     scope :updated_events,  -> { where(event: "update") }
-    scope :destroyed_events, -> { where(event: "destroy") }
 
-    # Deprecated short aliases kept for backwards compatibility
+    # Entries for +destroy+ events.
+    # @return [ActiveRecord::Relation]
+    scope :destroyed_events, -> { where(event: "destroy") }
 
+    # @deprecated Use {.created_events} instead.
     scope :creates,  -> { created_events }
+    # @deprecated Use {.updated_events} instead.
     scope :updates,  -> { updated_events }
+    # @deprecated Use {.destroyed_events} instead.
     scope :destroys, -> { destroyed_events }
 
-    # Actor / resource scopes
+    # @!endgroup
+
+    # @!group Actor / resource scopes
+
+    # Entries written by a specific actor.
+    #
+    # @param actor [ActiveRecord::Base] the actor record to filter by
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.by_actor(current_user)
     scope :by_actor, ->(actor) { where(actor_type: actor.class.name, actor_id: actor.id) }
+
+    # Entries for a specific resource class or instance.
+    # Pass a class to get all entries for that type; pass an instance for one record.
+    #
+    # @param resource [Class, ActiveRecord::Base]
+    # @return [ActiveRecord::Relation]
+    # @example All entries for Article
+    #   AuditLogEntry.for_resource(Article)
+    # @example All entries for one article
+    #   AuditLogEntry.for_resource(article)
     scope :for_resource, lambda { |resource|
       if resource.is_a?(Class)
         where(item_type: resource.name)
@@ -41,16 +90,61 @@ module RailsAuditLog
       end
     }
 
-    # Time scopes
-    scope :since,      ->(time)   { where(created_at: time..) }
-    scope :until,      ->(time)   { where(created_at: ..time) }
+    # @!endgroup
+
+    # @!group Time scopes
+
+    # Entries created at or after +time+.
+    #
+    # @param time [Time]
+    # @return [ActiveRecord::Relation]
+    scope :since, ->(time) { where(created_at: time..) }
+
+    # Entries created at or before +time+.
+    #
+    # @param time [Time]
+    # @return [ActiveRecord::Relation]
+    scope :until, ->(time) { where(created_at: ..time) }
+
+    # Entries within a named period. Valid keys: <tt>"1h"</tt>, <tt>"24h"</tt>, <tt>"7d"</tt>.
+    #
+    # @param period [String] one of +PERIODS.keys+
+    # @return [ActiveRecord::Relation]
     scope :for_period, ->(period) { where(created_at: PERIODS[period].ago..) }
 
-    # Projection scope — omits JSON blob columns for index/listing queries
+    # @!endgroup
+
+    # Omits the three JSON blob columns (+object_changes+, +object+, +metadata+)
+    # from the +SELECT+. Use on index/listing queries where blobs are not
+    # displayed to reduce I/O and avoid deserializing large payloads.
+    #
+    # @return [ActiveRecord::Relation]
     scope :slim, -> { select(column_names - BLOB_COLUMNS) }
 
-    # Instance methods
+    # Entries where +object_changes+ contains a key matching +attribute+.
+    # Uses <tt>json_extract</tt> on SQLite/MySQL and <tt>->></tt> on PostgreSQL.
+    #
+    # @param attribute [Symbol, String] the attribute name to filter on
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.touching(:title)
+    #   post.audit_log_entries.updated_events.touching(:published_at)
+    scope :touching, ->(attribute) {
+      if connection.adapter_name =~ /PostgreSQL/i
+        # :nocov:
+        where("object_changes->>? IS NOT NULL", attribute.to_s)
+        # :nocov:
+      else
+        where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")
+      end
+    }
 
+    # Reconstructs and returns the record's state *before* this entry's change.
+    # Uses the +object+ snapshot when available; falls back to deriving prior
+    # state from +object_changes+ (or the live record for +update+ entries).
+    #
+    # @return [ActiveRecord::Base, nil] an unpersisted instance; +nil+ for
+    #   +create+ entries (there is no prior state)
     def reify
       return nil if event == "create"
 
@@ -82,18 +176,37 @@ module RailsAuditLog
       instance
     end
 
+    # Returns the entry immediately before this one in the version chain for
+    # the same record (lower +id+), or +nil+ if this is the first entry.
+    #
+    # @return [AuditLogEntry, nil]
     def previous
       self.class.where(item_type: item_type, item_id: item_id).where("id < ?", id).order(id: :desc).first
     end
 
+    # Returns the entry immediately after this one in the version chain for
+    # the same record (higher +id+), or +nil+ if this is the last entry.
+    #
+    # @return [AuditLogEntry, nil]
     def next
       self.class.where(item_type: item_type, item_id: item_id).where("id > ?", id).order(id: :asc).first
     end
 
+    # Returns the list of attribute (and association) names that changed in
+    # this entry, derived from the keys of +object_changes+.
+    #
+    # @return [Array<String>]
     def changed_attributes
       object_changes&.keys || []
     end
 
+    # Returns +object_changes+ in a named-key format convenient for display.
+    #
+    # @return [Hash{String => Hash}] keys are attribute names; values are
+    #   hashes with +:from+ and +:to+ keys
+    # @example
+    #   entry.diff
+    #   # => { "title" => { from: "Old", to: "New" }, ... }
     def diff
       return {} unless object_changes
 
@@ -105,18 +218,5 @@ module RailsAuditLog
     def metadata_must_be_a_hash
       errors.add(:metadata, "must be a Hash") if metadata.present? && !metadata.is_a?(Hash)
     end
-
-    public
-
-    # Attribute scope — uses json_extract (SQLite/MySQL) or ->> (PostgreSQL)
-    scope :touching, ->(attribute) {
-      if connection.adapter_name =~ /PostgreSQL/i
-        # :nocov:
-        where("object_changes->>? IS NOT NULL", attribute.to_s)
-        # :nocov:
-      else
-        where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")
-      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/generators/rails_audit_log/migrate_from_paper_trail/migrate_from_paper_trail_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsAuditLog
+  module Generators
+    class MigrateFromPaperTrailGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a data migration that copies PaperTrail versions to audit_log_entries."
+
+      def create_migration_file
+        migration_template(
+          "migrate_from_paper_trail.rb",
+          "db/migrate/migrate_from_paper_trail.rb"
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+require "yaml"
+require "json"
+
+# Data migration: copies PaperTrail `versions` rows to `audit_log_entries`.
+#
+# Column mapping:
+#   versions.item_type        → audit_log_entries.item_type
+#   versions.item_id          → audit_log_entries.item_id
+#   versions.event            → audit_log_entries.event  (create/update/destroy only)
+#   versions.object_changes   → audit_log_entries.object_changes  (YAML or JSON → JSON)
+#   versions.object           → audit_log_entries.object           (YAML or JSON → JSON)
+#   versions.whodunnit        → audit_log_entries.whodunnit_snapshot
+#   versions.created_at       → audit_log_entries.created_at
+#
+# actor_type / actor_id are not populated — PaperTrail stores the actor
+# only as a string (whodunnit), so polymorphic references cannot be inferred.
+#
+# This migration is irreversible.
+class MigrateFromPaperTrail < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  BATCH_SIZE    = 1_000
+  VALID_EVENTS  = %w[create update destroy].freeze
+
+  # Isolated AR classes to avoid coupling to the host app's models.
+  class Version < ActiveRecord::Base   # @api private
+    self.table_name = "versions"
+  end
+
+  class AuditEntry < ActiveRecord::Base   # @api private
+    self.table_name = "audit_log_entries"
+  end
+
+  def up
+    unless table_exists?(:versions)
+      say "  versions table not found — nothing to migrate."
+      return
+    end
+
+    total     = Version.count
+    migrated  = 0
+    skipped   = 0
+
+    say_with_time "Migrating #{total} PaperTrail versions → audit_log_entries" do
+      Version.in_batches(of: BATCH_SIZE) do |batch|
+        rows = batch.filter_map do |v|
+          next unless VALID_EVENTS.include?(v.event)
+
+          {
+            event:              v.event,
+            item_type:          v.item_type,
+            item_id:            v.item_id,
+            object_changes:     parse_serialized(v.read_attribute_before_type_cast(:object_changes)),
+            object:             parse_serialized(v.read_attribute_before_type_cast(:object)),
+            whodunnit_snapshot: v.whodunnit,
+            created_at:         v.created_at,
+            updated_at:         v.created_at
+          }
+        end
+
+        skipped  += batch.size - rows.size
+        migrated += rows.size
+        AuditEntry.insert_all(rows) if rows.any?
+      end
+    end
+
+    say "  Migrated: #{migrated}  Skipped (unsupported event): #{skipped}"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          "Cannot reverse PaperTrail migration — rows already written to audit_log_entries " \
+          "cannot be reliably distinguished from native entries."
+  end
+
+  private
+
+  # Parses a PaperTrail serialized column (YAML or JSON) and returns a Hash,
+  # or nil if the value is blank or unparseable.
+  def parse_serialized(value)
+    return nil if value.nil? || value.to_s.strip.empty?
+
+    begin
+      parsed = JSON.parse(value)
+      return parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      # fall through to YAML
+    end
+
+    begin
+      parsed = YAML.safe_load(
+        value,
+        permitted_classes: [Symbol, Date, Time, DateTime, BigDecimal,
+                             ActiveSupport::TimeWithZone, ActiveSupport::Duration]
+      )
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/rails_audit_log/engine.rb

@@ -4,6 +4,7 @@ require "pagy"
 require "pagy/toolbox/paginators/method"
 
 module RailsAuditLog
+  # @api private
   class Engine < ::Rails::Engine
     isolate_namespace RailsAuditLog
 

data/lib/rails_audit_log/matchers.rb

@@ -1,24 +1,67 @@
 module RailsAuditLog
+  # RSpec matchers for asserting audit log behaviour.
+  #
+  # == Setup
+  #
+  #   # spec/rails_helper.rb
+  #   require "rails_audit_log/matchers"
+  #
+  #   RSpec.configure do |config|
+  #     config.include RailsAuditLog::Matchers
+  #   end
+  #
+  # == Usage
+  #
+  #   # Assert a record already has an entry
+  #   expect(post).to have_audit_log_entry(:update).touching(:title)
+  #
+  #   # Assert a block creates a new entry
+  #   expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update, touching: :title)
   module Matchers
+    # Returns a matcher that asserts the record has at least one matching
+    # {AuditLogEntry}.
+    #
+    # @param event [Symbol, String, nil] optional event filter
+    #   (<tt>:create</tt>, <tt>:update</tt>, or <tt>:destroy</tt>)
+    # @return [HaveAuditLogEntry]
+    # @example
+    #   expect(post).to have_audit_log_entry
+    #   expect(post).to have_audit_log_entry(:update)
+    #   expect(post).to have_audit_log_entry(:update).touching(:title)
     def have_audit_log_entry(event = nil)
       HaveAuditLogEntry.new(event)
     end
 
+    # Returns a matcher that asserts the block creates at least one new
+    # {AuditLogEntry} matching the given filters.
+    #
+    # @param event [Symbol, String, nil] optional event filter
+    # @param touching [Symbol, String, nil] optional attribute filter
+    # @return [CreateAuditLogEntry]
+    # @example
+    #   expect { post.update!(title: "x") }.to create_audit_log_entry(event: :update)
+    #   expect { post.update!(title: "x") }.to create_audit_log_entry(touching: :title)
     def create_audit_log_entry(event: nil, touching: nil)
       CreateAuditLogEntry.new(event: event, touching: touching)
     end
 
+    # RSpec matcher — asserts that a record already has a matching entry.
     class HaveAuditLogEntry
       def initialize(event)
         @event    = event
         @touching = nil
       end
 
+      # Chains an attribute filter onto the matcher.
+      #
+      # @param attribute [Symbol, String]
+      # @return [self]
       def touching(attribute)
         @touching = attribute
         self
       end
 
+      # @api private
       def matches?(record)
         @record = record
         scope = record.audit_log_entries
@@ -27,14 +70,17 @@ module RailsAuditLog
         scope.exists?
       end
 
+      # @api private
       def failure_message
         "expected #{@record.class}##{@record.id} to have an audit log entry#{qualifier}"
       end
 
+      # @api private
       def failure_message_when_negated
         "expected #{@record.class}##{@record.id} not to have an audit log entry#{qualifier}"
       end
 
+      # @api private
       def description
         "have an audit log entry#{qualifier}"
       end
@@ -49,21 +95,28 @@ module RailsAuditLog
       end
     end
 
+    # RSpec matcher — asserts that a block creates a new matching entry.
     class CreateAuditLogEntry
       def initialize(event:, touching:)
         @event    = event
         @touching = touching
       end
 
+      # Chains an attribute filter onto the matcher.
+      #
+      # @param attribute [Symbol, String]
+      # @return [self]
       def touching(attribute)
         @touching = attribute
         self
       end
 
+      # @api private
       def supports_block_expectations?
         true
       end
 
+      # @api private
       def matches?(block)
         @before = matching_scope.count
         block.call
@@ -71,14 +124,17 @@ module RailsAuditLog
         @after > @before
       end
 
+      # @api private
       def failure_message
         "expected block to create an audit log entry#{qualifier}, but none was created"
       end
 
+      # @api private
       def failure_message_when_negated
         "expected block not to create an audit log entry#{qualifier}, but one was created"
       end
 
+      # @api private
       def description
         "create an audit log entry#{qualifier}"
       end