rails_audit_log 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc56d9335d26c5f43d52de380aa354a268cbb266696799cf1775f051162c2d8
-  data.tar.gz: '027792cdf8815ec2822177492b674d05534a3d96163d463dd603a415d471ace2'
+  metadata.gz: 5cd71899d109aa978910a72ef144aeafb601dc70790e044ef723b49d1d560f65
+  data.tar.gz: 8884deec2a0abf63f14639794d6ac614689c9799e09b375ffc0cc7d788943e7d
 SHA512:
-  metadata.gz: 107247da00cc1f7eec9750f9d59eb2b41fa47f4ec9c3a0b00f587882bf6080250fe5af5152a2d13491fdb6ebf6aa7d3f82a6418f89777b9dca3819c024692805
-  data.tar.gz: 3715691ec2538d7fca5538af23e9f087899469876dcb98b660d82f18230ee531f45660950c95e4230f15a6a430b4b85999691472b9c61cf1d4e88af6c90849c2
+  metadata.gz: c32ada5189eda30461ea1dbc10a67982fb0ff6c4244da4339aa3376082b38a5272bb3a1b91fe50110c08ae9ee0ae3ede52d2a43701c0f7260a4d5a6581c0f42d
+  data.tar.gz: 448becbb80428dd754bca4d1ab43625de5ec85a2c9d712e9e4a28f7c14b0c18ce6865b25dfd9ea6c46f7b1814988d0eea77ae8b6aee7a230927cc37a80f60cf3

data/README.md

@@ -23,6 +23,14 @@ bin/rails generate rails_audit_log:install
 bin/rails db:migrate
 ```
 
+Optionally scaffold a commented initializer with every configuration option:
+
+```bash
+bin/rails generate rails_audit_log:initializer
+```
+
+This creates `config/initializers/rails_audit_log.rb` with all settings documented as commented examples inside a `RailsAuditLog.configure` block.
+
 ## Usage
 
 ### Tracking a model
@@ -102,6 +110,32 @@ entry.diff
 # => { "title" => { from: "Hello", to: "World" } }
 ```
 
+### Separate audit database
+
+Route all audit writes to a dedicated database by setting `connects_to` in an initializer. The engine applies it to `AuditLogEntry` at boot:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.connects_to = {
+  database: { writing: :audit_log, reading: :audit_log }
+}
+```
+
+The key (e.g. `:audit_log`) must match a database key in `config/database.yml`. All reads and writes on `AuditLogEntry` — including `batch_audit` inserts and `WriteAuditLogJob` — use that connection automatically.
+
+### Lightweight queries
+
+Use `.slim` to exclude the three JSON blob columns (`object_changes`, `object`, `metadata`) from the SQL projection. This is useful for index or listing views where you only need the entry header (who, what event, when):
+
+```ruby
+entries = AuditLogEntry.slim.for_resource(article).since(1.week.ago)
+entries.first.event          # => "update"
+entries.first.actor_type     # => "User"
+entries.first.object_changes # => raises ActiveModel::MissingAttributeError
+```
+
+> **Note:** Use `.count(:id)` instead of `.count` when chaining `.slim` with other scopes — Rails' `COUNT` with a multi-column `SELECT` is not supported by all databases.
+
 ### Association tracking
 
 Track `has_many` add and remove events by passing `associations: true` to `audit_log`. Call `audit_log` **before** the `has_many` declarations so the callbacks are wired at class load time:
@@ -151,6 +185,59 @@ end
 
 `belongs_to` foreign-key changes are already tracked as regular column updates and require no extra configuration.
 
+### Bulk audit writes
+
+Wrap a block with `RailsAuditLog.batch_audit` to buffer all audit entries and flush them in a single `insert_all!` call at the end, eliminating N+1 inserts during imports:
+
+```ruby
+RailsAuditLog.batch_audit do
+  records.each { |attrs| Post.create!(attrs) }
+end
+# All audit entries written in one INSERT
+```
+
+Nested calls accumulate into the outermost batch — only one `insert_all!` fires. If the block raises, the buffer is discarded and no entries are written.
+
+> **Note:** Version pruning (`version_limit`) is deferred in batch mode — the next write outside the batch will trigger pruning as usual.
+
+### Async audit writes
+
+Offload audit writes to a background job by passing `async: true` to `audit_log`. The entry is enqueued via `RailsAuditLog::WriteAuditLogJob` (a subclass of `ActiveJob::Base`) so the request does not block on the database write:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log async: true
+end
+```
+
+Enable async globally in an initializer — per-model `async: true` takes precedence:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.async = true
+```
+
+Configure the queue adapter and queue name through standard ActiveJob settings. Version pruning also runs inside the job when `version_limit` is set.
+
+### Capping history per record
+
+Limit how many audit entries are kept per record with `version_limit:`. Oldest entries are pruned automatically after each write once the cap is reached:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log version_limit: 10  # keep only the 10 most recent entries
+end
+```
+
+Set a global default in an initializer — per-model values take precedence:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.version_limit = 50
+```
+
 ### Selective tracking
 
 Track only specific attributes, or exclude noisy ones:
@@ -305,6 +392,76 @@ To save storage at the cost of reduced reification accuracy, switch to diff-only
 RailsAuditLog.store_snapshot = false
 ```
 
+### Test helper
+
+`without_audit_log` silences audit tracking inside the block — useful in FactoryBot factories and seed data to avoid noise in the audit trail:
+
+```ruby
+# spec/rails_helper.rb (or spec/support/factory_helpers.rb)
+require "rails_audit_log/test_helpers"
+
+RSpec.configure do |config|
+  config.include RailsAuditLog::TestHelpers
+end
+
+# Or include directly in FactoryBot definitions:
+FactoryBot.define do
+  factory :post do
+    after(:create) { |p| without_audit_log { p.update!(cached_at: Time.current) } }
+  end
+end
+```
+
+`without_audit_log` is a prefix-free wrapper around `RailsAuditLog.disable` — thread-safe and restores tracking even if the block raises.
+
+### Minitest assertions
+
+Add to your `test/test_helper.rb`:
+
+```ruby
+require "rails_audit_log/minitest_assertions"
+
+class ActiveSupport::TestCase
+  include RailsAuditLog::MinitestAssertions
+end
+```
+
+Then use the assertions in any test:
+
+```ruby
+assert_audit_log_entry post                                      # any entry
+assert_audit_log_entry post, event: :update                      # update entry
+assert_audit_log_entry post, event: :update, touching: :title    # touching title
+refute_audit_log_entry post, event: :update                      # no update entry
+assert_audit_log_entry post, event: :update, message: "custom"  # custom failure message
+```
+
+### RSpec matchers
+
+Add to your `spec/rails_helper.rb` (or `spec_helper.rb`):
+
+```ruby
+require "rails_audit_log/matchers"
+
+RSpec.configure do |config|
+  config.include RailsAuditLog::Matchers
+end
+```
+
+Then use the matchers in any spec:
+
+```ruby
+# Assert a record has a matching audit entry
+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)
+
+# Assert a block creates a matching audit entry
+expect { post.update!(title: "New") }.to create_audit_log_entry
+expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update)
+expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update).touching(:title)
+```
+
 ## Requirements
 
 - Ruby >= 3.3

data/app/concerns/rails_audit_log/auditable.rb

@@ -3,10 +3,14 @@ module RailsAuditLog
     extend ActiveSupport::Concern
 
     included do
-      class_attribute :_audit_log_only,         default: nil
-      class_attribute :_audit_log_ignore,        default: nil
-      class_attribute :_audit_log_meta,          default: nil
-      class_attribute :_audit_log_associations,  default: nil
+      class_attribute :_audit_log_only,          default: nil
+      class_attribute :_audit_log_ignore,         default: nil
+      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_async,          default: false
+
+      _warn_if_audit_table_missing
 
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
@@ -50,11 +54,25 @@ module RailsAuditLog
     end
 
     class_methods do
-      def audit_log(only: nil, ignore: nil, meta: nil, associations: 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?
+      def _warn_if_audit_table_missing
+        return if connection.table_exists?("audit_log_entries")
+
+        warn "[RailsAuditLog] WARNING: #{name} includes RailsAuditLog::Auditable but the " \
+             "'audit_log_entries' table does not exist. " \
+             "Run `bin/rails generate rails_audit_log:install && bin/rails db:migrate` to create it."
+      rescue ActiveRecord::NoDatabaseError,
+             ActiveRecord::ConnectionNotEstablished,
+             ActiveRecord::StatementInvalid
+        # DB not reachable during this phase (e.g. before db:create) — skip the check
+      end
+
+      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: 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_async         = async               unless async.nil?
       end
     end
 
@@ -84,11 +102,12 @@ module RailsAuditLog
 
       actor = RailsAuditLog.actor
       meta  = build_audit_metadata
-      RailsAuditLog::AuditLogEntry.create!(
+      write_audit_entry(
         event:              "update",
         item_type:          self.class.name,
         item_id:            id,
         object_changes:     { assoc_name => [before, after] },
+        object:             nil,
         reason:             RailsAuditLog.reason,
         metadata:           meta.presence,
         whodunnit_snapshot: actor ? RailsAuditLog.whodunnit_display.call(actor) : nil,
@@ -104,8 +123,8 @@ module RailsAuditLog
       return if filtered.empty? && event == "update"
 
       actor = RailsAuditLog.actor
-      meta = build_audit_metadata
-      RailsAuditLog::AuditLogEntry.create!(
+      meta  = build_audit_metadata
+      write_audit_entry(
         event:               event,
         item_type:           self.class.name,
         item_id:             id,
@@ -119,6 +138,29 @@ module RailsAuditLog
       )
     end
 
+    def write_audit_entry(entry_attrs)
+      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)
+      else
+        RailsAuditLog::AuditLogEntry.create!(entry_attrs)
+        prune_audit_entries
+      end
+    end
+
+    def prune_audit_entries
+      limit = self.class._audit_log_version_limit || RailsAuditLog.version_limit
+      return unless limit
+
+      count = audit_log_entries.count
+      excess = count - limit
+      return unless excess > 0
+
+      audit_log_entries.order(id: :asc).limit(excess).delete_all
+    end
+
     def build_audit_metadata
       meta = {}
       if self.class._audit_log_meta

data/app/jobs/rails_audit_log/write_audit_log_job.rb

@@ -0,0 +1,20 @@
+module RailsAuditLog
+  class WriteAuditLogJob < ApplicationJob
+    def perform(entry_attrs, version_limit: 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
+
+      AuditLogEntry.where(item_type: item_type, item_id: item_id)
+                   .order(id: :asc)
+                   .limit(excess)
+                   .delete_all
+    end
+  end
+end

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -3,6 +3,13 @@ module RailsAuditLog
     self.table_name = "audit_log_entries"
 
     EVENTS = %w[create update destroy].freeze
+    BLOB_COLUMNS = %w[object_changes object metadata].freeze
+
+    def self.configure_connection!
+      return unless (opts = RailsAuditLog.connects_to)
+
+      connects_to(**opts)
+    end
 
     belongs_to :item, polymorphic: true, optional: true
     belongs_to :actor, polymorphic: true, optional: true
@@ -37,6 +44,9 @@ module RailsAuditLog
     scope :since, ->(time) { where(created_at: time..) }
     scope :until, ->(time) { where(created_at: ..time) }
 
+    # Projection scope — omits JSON blob columns for index/listing queries
+    scope :slim, -> { select(column_names - BLOB_COLUMNS) }
+
     # Instance methods
 
     def reify

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

@@ -0,0 +1,15 @@
+require "rails/generators"
+
+module RailsAuditLog
+  module Generators
+    class InitializerGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a commented RailsAuditLog initializer in config/initializers."
+
+      def create_initializer_file
+        template "rails_audit_log.rb", "config/initializers/rails_audit_log.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# config/initializers/rails_audit_log.rb
+# Generated by `bin/rails generate rails_audit_log:initializer`
+#
+# All settings are optional. Remove the comments around any line you want to activate.
+
+RailsAuditLog.configure do |config|
+  # Global columns excluded from all audited models. Default: ["updated_at"]
+  # config.ignored_attributes = %w[updated_at cached_at]
+
+  # Store a full attribute snapshot alongside object_changes. Default: true
+  # Disable to save storage; reify and version_at fall back to diff-only reconstruction.
+  # config.store_snapshot = false
+
+  # Capture remote_ip and user_agent into each entry's metadata column. Default: false
+  # Requires including RailsAuditLog::Controller in ApplicationController.
+  # config.capture_request_metadata = true
+
+  # Customise how the actor's display name is stored at write time. Default: actor.name
+  # config.whodunnit_display = ->(actor) { actor.email }
+
+  # Global cap on entries retained per tracked record. Default: nil (no limit)
+  # Per-model `audit_log version_limit: N` takes precedence.
+  # config.version_limit = 100
+
+  # Write all audit entries asynchronously via WriteAuditLogJob. Default: false
+  # Per-model `audit_log async: true` also works.
+  # config.async = true
+
+  # Route AuditLogEntry to a dedicated database (Rails multi-DB). Default: nil
+  # config.connects_to = { database: { writing: :audit_log, reading: :audit_log } }
+end

data/lib/rails_audit_log/engine.rb

@@ -1,5 +1,11 @@
 module RailsAuditLog
   class Engine < ::Rails::Engine
     isolate_namespace RailsAuditLog
+
+    initializer "rails_audit_log.connect_audit_db" do
+      ActiveSupport.on_load(:active_record) do
+        RailsAuditLog::AuditLogEntry.configure_connection!
+      end
+    end
   end
 end

data/lib/rails_audit_log/matchers.rb

@@ -0,0 +1,103 @@
+module RailsAuditLog
+  module Matchers
+    def have_audit_log_entry(event = nil)
+      HaveAuditLogEntry.new(event)
+    end
+
+    def create_audit_log_entry(event: nil, touching: nil)
+      CreateAuditLogEntry.new(event: event, touching: touching)
+    end
+
+    class HaveAuditLogEntry
+      def initialize(event)
+        @event    = event
+        @touching = nil
+      end
+
+      def touching(attribute)
+        @touching = attribute
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        scope = record.audit_log_entries
+        scope = scope.where(event: @event.to_s) if @event
+        scope = scope.touching(@touching)       if @touching
+        scope.exists?
+      end
+
+      def failure_message
+        "expected #{@record.class}##{@record.id} to have an audit log entry#{qualifier}"
+      end
+
+      def failure_message_when_negated
+        "expected #{@record.class}##{@record.id} not to have an audit log entry#{qualifier}"
+      end
+
+      def description
+        "have an audit log entry#{qualifier}"
+      end
+
+      private
+
+      def qualifier
+        parts = []
+        parts << " with event '#{@event}'" if @event
+        parts << " touching '#{@touching}'" if @touching
+        parts.join
+      end
+    end
+
+    class CreateAuditLogEntry
+      def initialize(event:, touching:)
+        @event    = event
+        @touching = touching
+      end
+
+      def touching(attribute)
+        @touching = attribute
+        self
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        @before = matching_scope.count
+        block.call
+        @after = matching_scope.count
+        @after > @before
+      end
+
+      def failure_message
+        "expected block to create an audit log entry#{qualifier}, but none was created"
+      end
+
+      def failure_message_when_negated
+        "expected block not to create an audit log entry#{qualifier}, but one was created"
+      end
+
+      def description
+        "create an audit log entry#{qualifier}"
+      end
+
+      private
+
+      def matching_scope
+        scope = RailsAuditLog::AuditLogEntry.all
+        scope = scope.where(event: @event.to_s) if @event
+        scope = scope.touching(@touching)       if @touching
+        scope
+      end
+
+      def qualifier
+        parts = []
+        parts << " with event '#{@event}'" if @event
+        parts << " touching '#{@touching}'" if @touching
+        parts.join
+      end
+    end
+  end
+end

data/lib/rails_audit_log/minitest_assertions.rb

@@ -0,0 +1,31 @@
+module RailsAuditLog
+  module MinitestAssertions
+    def assert_audit_log_entry(record, event: nil, touching: nil, message: nil)
+      scope = build_scope(record, event, touching)
+      msg   = message || default_message("to have", record, event, touching)
+      assert scope.exists?, msg
+    end
+
+    def refute_audit_log_entry(record, event: nil, touching: nil, message: nil)
+      scope = build_scope(record, event, touching)
+      msg   = message || default_message("not to have", record, event, touching)
+      refute scope.exists?, msg
+    end
+
+    private
+
+    def build_scope(record, event, touching)
+      scope = record.audit_log_entries
+      scope = scope.where(event: event.to_s) if event
+      scope = scope.touching(touching)       if touching
+      scope
+    end
+
+    def default_message(polarity, record, event, touching)
+      parts = []
+      parts << " with event '#{event}'" if event
+      parts << " touching '#{touching}'" if touching
+      "Expected #{record.class}##{record.id} #{polarity} an audit log entry#{parts.join}"
+    end
+  end
+end

data/lib/rails_audit_log/test_helpers.rb

@@ -0,0 +1,7 @@
+module RailsAuditLog
+  module TestHelpers
+    def without_audit_log(&block)
+      RailsAuditLog.disable(&block)
+    end
+  end
+end

data/lib/rails_audit_log/version.rb

@@ -1,3 +1,3 @@
 module RailsAuditLog
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/rails_audit_log.rb

@@ -5,8 +5,15 @@ module RailsAuditLog
   # Global default columns to ignore across all audited models.
   # Override in an initializer: RailsAuditLog.ignored_attributes = %w[updated_at cached_at]
   mattr_accessor :ignored_attributes, default: %w[updated_at]
+
+  def self.configure
+    yield self
+  end
   mattr_accessor :store_snapshot, default: true
   mattr_accessor :capture_request_metadata, default: false
+  mattr_accessor :version_limit, default: nil
+  mattr_accessor :async, default: false
+  mattr_accessor :connects_to, default: nil
   mattr_accessor :whodunnit_display, default: ->(actor) {
     actor.respond_to?(:name) ? actor.name.to_s : actor.to_s
   }
@@ -63,6 +70,24 @@ module RailsAuditLog
     self.reason = previous
   end
 
+  def self.batch_audit
+    return yield if Thread.current[:rails_audit_log_batch]
+
+    Thread.current[:rails_audit_log_batch] = []
+    begin
+      result = yield
+      batch = Thread.current[:rails_audit_log_batch]
+      AuditLogEntry.insert_all!(batch) if batch.any?
+      result
+    ensure
+      Thread.current[:rails_audit_log_batch] = nil
+    end
+  end
+
+  def self.batch_audit_buffer
+    Thread.current[:rails_audit_log_batch]
+  end
+
   def self.version_at(record, time)
     entry = AuditLogEntry
       .where(item_type: record.class.name, item_id: record.id)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -41,14 +41,20 @@ files:
 - app/controllers/rails_audit_log/application_controller.rb
 - app/helpers/rails_audit_log/application_helper.rb
 - app/jobs/rails_audit_log/application_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
 - app/views/layouts/rails_audit_log/application.html.erb
 - config/routes.rb
+- lib/generators/rails_audit_log/initializer/initializer_generator.rb
+- lib/generators/rails_audit_log/initializer/templates/rails_audit_log.rb
 - lib/generators/rails_audit_log/install/install_generator.rb
 - lib/generators/rails_audit_log/install/templates/create_audit_log_entries.rb
 - lib/rails_audit_log.rb
 - lib/rails_audit_log/engine.rb
+- lib/rails_audit_log/matchers.rb
+- lib/rails_audit_log/minitest_assertions.rb
+- lib/rails_audit_log/test_helpers.rb
 - lib/rails_audit_log/version.rb
 - lib/tasks/rails_audit_log_tasks.rake
 homepage: https://github.com/eclectic-coding/rails_audit_log