rails_audit_log 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c9a9fcdb866f5300a3a2fd9bd6026ad93530d15b0b26d771ef1a28a47985280
-  data.tar.gz: 01ac4b3f95fd1c2067a8aa5936122ff86dc264fe771881515dd31d3401377b66
+  metadata.gz: aa624cc1cc0ba6984f41de2f19b22891f9a7c376aae0625f94ebe86f2c48ef78
+  data.tar.gz: 75bfb038bb1fe170bdf1a893ec87c40b3e7711602ad355a9c0788d20558ef337
 SHA512:
-  metadata.gz: 4c155747f1219996a6fde0fcc0d00c764df0f296c7b099418b7020ef90984690400300174b5c1cc1dc4842451a3f53d35e4b710542693683c78d4706c0eca1c1
-  data.tar.gz: 256ef73b739193443718481ef7fa1c0920ae4b4d424e3466b9ac3dbaf9a0bf8b7cf4823d0fd7d000652710985ac60fa6df6252e5997266bb40eda6bde9ba9941
+  metadata.gz: fd59c42a1522f4301e8c46c5b25186784847f5e56529fb7baf4d7b3d87d0f5391fb0bbcb33b8abac53bbf47a85a7529eae02d878c0484148a496b28950573541
+  data.tar.gz: 7b2be961c2b1f6091c1426d7be966ceb99647a7415faa4a540f3876d63ea6ff2a10fab515b61074b9538a7f43b63d99481c1743e35aeb09e313d2e76c4c3107f

data/README.md

@@ -6,10 +6,45 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby)](https://www.ruby-lang.org)
 [![codecov](https://codecov.io/gh/eclectic-coding/rails_audit_log/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/rails_audit_log)
 
-A modern, Zeitwerk-native Rails engine for auditing ActiveRecord changes. Tracks `create`, `update`, and `destroy` events with JSON-first storage, whodunnit actor context, and a clean query API.
+Audit logging for Rails. Tracks `create`, `update`, and `destroy` events as structured JSON records with a mountable web dashboard, whodunnit actor context, batch writes, time-travel reconstruction, and test helpers — a clean, well-documented replacement for PaperTrail with a built-in migration path.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Web dashboard](#web-dashboard)
+- [Usage](#usage)
+  - [Tracking a model](#tracking-a-model)
+  - [Recording who made the change](#recording-who-made-the-change)
+  - [Actor context outside of controllers](#actor-context-outside-of-controllers)
+  - [Querying the audit log](#querying-the-audit-log)
+  - [Lightweight queries](#lightweight-queries)
+  - [Association tracking](#association-tracking)
+  - [Bulk audit writes](#bulk-audit-writes)
+  - [Async audit writes](#async-audit-writes)
+  - [Capping history per record](#capping-history-per-record)
+  - [Selective tracking](#selective-tracking)
+  - [Disabling auditing](#disabling-auditing)
+  - [Object reconstruction](#object-reconstruction)
+  - [Attaching a reason](#attaching-a-reason)
+  - [Arbitrary metadata](#arbitrary-metadata)
+  - [Request metadata capture](#request-metadata-capture)
+  - [Actor display name snapshot](#actor-display-name-snapshot)
+  - [Object snapshot storage](#object-snapshot-storage)
+  - [Separate audit database](#separate-audit-database)
+  - [Test helpers](#test-helpers)
+- [Stability and versioning](#stability-and-versioning)
+- [Migrating from PaperTrail](#migrating-from-papertrail)
+- [Performance](#performance)
+- [Companion gems](#companion-gems)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
+[↑ Table of contents](#table-of-contents)
+
 Add to your `Gemfile`:
 
 ```ruby
@@ -23,16 +58,67 @@ bin/rails generate rails_audit_log:install
 bin/rails db:migrate
 ```
 
-Optionally scaffold a commented initializer with every configuration option:
+## Configuration
+
+[↑ Table of contents](#table-of-contents)
+
+Run the initializer generator to create `config/initializers/rails_audit_log.rb` with every option documented as a commented example:
 
 ```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.
+The generated file (shown below with all options) uses the block-style `configure` API. Every setting has a sensible default — uncomment only what you need:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+
+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 RailsAuditLog::Controller in ApplicationController.
+  # config.capture_request_metadata = true
+
+  # Customise how the actor's display name is stored at write time.
+  # Default: actor.name if available, otherwise actor.to_s
+  # config.whodunnit_display = ->(actor) { actor.email }
+
+  # Global cap on entries retained per tracked record. 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).
+  # config.connects_to = { database: { writing: :audit_log, reading: :audit_log } }
+
+  # Entries per page in the web dashboard. Default: 25
+  # config.page_size = 50
+
+  # Gate web dashboard access. Block runs in controller context so controller
+  # helpers like current_user are available directly. Falls back to HTTP Basic
+  # auth when the block returns falsy. Leave unset for unauthenticated access.
+  # config.authenticate { current_user&.admin? }
+  # config.authenticate { |c| c.current_user&.admin? }
+end
+```
+
+Each option is documented in detail in its own Usage section below.
 
 ## Web dashboard
 
+[↑ Table of contents](#table-of-contents)
+
 Mount the engine in `config/routes.rb` to enable the built-in audit trail browser:
 
 ```ruby
@@ -43,6 +129,8 @@ Then visit `/audit` to browse all audit entries. The dashboard is delivered via
 
 ## Usage
 
+[↑ Table of contents](#table-of-contents)
+
 ### Tracking a model
 
 Include `RailsAuditLog::Auditable` in any ActiveRecord model:
@@ -120,19 +208,6 @@ 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):
@@ -293,22 +368,20 @@ article.skip_audit_log { article.update!(cached_at: Time.current) }
 
 ### Object reconstruction
 
-#### Reify a single entry
-
-`AuditLogEntry#reify` returns an unsaved ActiveRecord instance reflecting the record's state **before** the entry was recorded:
+**Reify a single entry** — `AuditLogEntry#reify` returns an unsaved ActiveRecord instance reflecting the record's state **before** the entry was recorded:
 
 ```ruby
 article.update!(title: "v2")
 entry = article.audit_log_entries.updated_events.last
 
 previous = entry.reify
-previous.title   # => "v1"  (the pre-update state)
+previous.title      # => "v1"  (the pre-update state)
 previous.persisted? # => false
 ```
 
 Returns `nil` for `create` entries (nothing existed before).
 
-#### Reconstruct state at any point in time
+**Reconstruct state at any point in time:**
 
 ```ruby
 snapshot = RailsAuditLog.version_at(article, 1.week.ago)
@@ -317,7 +390,7 @@ snapshot.title  # => whatever the title was a week ago
 
 Returns `nil` if the record had no history at that time or was already destroyed.
 
-#### Navigate the version chain
+**Navigate the version chain:**
 
 ```ruby
 entry = article.audit_log_entries.updated_events.last
@@ -402,31 +475,58 @@ To save storage at the cost of reduced reification accuracy, switch to diff-only
 RailsAuditLog.store_snapshot = false
 ```
 
-### Test helper
+### 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.
+
+### Test helpers
 
-`without_audit_log` silences audit tracking inside the block — useful in FactoryBot factories and seed data to avoid noise in the audit trail:
+**`RailsAuditLog::TestHelpers`** — silences audit tracking inside a block; useful in FactoryBot factories and seed data:
 
 ```ruby
-# spec/rails_helper.rb (or spec/support/factory_helpers.rb)
+# spec/rails_helper.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
+```ruby
+# Or in a FactoryBot factory:
+after(:create) { |p| without_audit_log { p.update!(cached_at: Time.current) } }
 ```
 
 `without_audit_log` is a prefix-free wrapper around `RailsAuditLog.disable` — thread-safe and restores tracking even if the block raises.
 
-### Minitest assertions
+**`RailsAuditLog::Matchers`** (RSpec) — add to `spec/rails_helper.rb`:
+
+```ruby
+require "rails_audit_log/matchers"
 
-Add to your `test/test_helper.rb`:
+RSpec.configure do |config|
+  config.include RailsAuditLog::Matchers
+end
+```
+
+```ruby
+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)
+
+expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update).touching(:title)
+```
+
+**`RailsAuditLog::MinitestAssertions`** — add to `test/test_helper.rb`:
 
 ```ruby
 require "rails_audit_log/minitest_assertions"
@@ -436,51 +536,180 @@ class ActiveSupport::TestCase
 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
+assert_audit_log_entry post, event: :update, touching: :title
+refute_audit_log_entry post, event: :destroy
+```
+
+## Stability and versioning
+
+[↑ Table of contents](#table-of-contents)
+
+`rails_audit_log` follows [Semantic Versioning](https://semver.org/) from 1.0.0. The public API is everything documented in this README. Anything not listed here is internal and may change between minor versions.
+
+| Version bump | Meaning |
+|---|---|
+| **Patch** (1.0.x) | Bug fixes only — no API changes |
+| **Minor** (1.x.0) | New features, backward-compatible |
+| **Major** (x.0.0) | Breaking changes with a documented migration path |
+
+### Public API surface
+
+**Module-level** — `RailsAuditLog`
+
+| Method / accessor | Purpose |
+|---|---|
+| `.configure { \|config\| }` | Block-style configuration |
+| `.with_actor(actor) { }` | Set whodunnit context for a block |
+| `.disable { }` | Suppress all audit writes for a block |
+| `.enabled?` | Whether audit writes are active |
+| `.audit_log_reason(value) { }` | Attach a free-text reason for a block |
+| `.batch_audit { }` | Buffer writes and flush with a single `insert_all!` |
+| `.version_at(record, time)` | Reconstruct record state at a point in time |
+| `.authenticate { }` | Gate web dashboard access |
+| `.ignored_attributes=` | Global columns excluded from all models |
+| `.store_snapshot=` | Store full object snapshot alongside diffs |
+| `.capture_request_metadata=` | Capture `remote_ip` and `user_agent` |
+| `.version_limit=` | Global entry cap per record |
+| `.async=` | Write audit entries via `WriteAuditLogJob` |
+| `.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 |
+
+**Concerns**
+
+| Class | Include in | Key methods |
+|---|---|---|
+| `RailsAuditLog::Auditable` | ActiveRecord models | `audit_log(only:, ignore:, meta:, associations:, version_limit:, async:)`, `skip_audit_log { }` |
+| `RailsAuditLog::Controller` | ActionController | `audit_log_actor { }` |
+
+**Model — `RailsAuditLog::AuditLogEntry`**
+
+Scopes: `created_events`, `updated_events`, `destroyed_events`, `by_actor`, `for_resource`, `since`, `until`, `touching`, `slim`, `for_period`
+
+Instance methods: `reify`, `previous`, `next`, `diff`, `changed_attributes`, `actor`
+
+Constants: `EVENTS`, `BLOB_COLUMNS`, `PERIODS`
+
+**Testing helpers**
+
+| Module | Require | Usage |
+|---|---|---|
+| `RailsAuditLog::Matchers` | `require "rails_audit_log/matchers"` | RSpec: `have_audit_log_entry`, `create_audit_log_entry` |
+| `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)
+
+`RailsAuditLog::WriteAuditLogJob` — do not instantiate directly; enqueued when `async: true` is set.
+
+**Generators**
+
+`rails generate rails_audit_log:install` · `rails generate rails_audit_log:initializer`
+
+---
+
+## Migrating from PaperTrail
+
+[↑ Table of contents](#table-of-contents)
+
+Run the migration generator to produce a timestamped data migration:
+
+```bash
+bin/rails generate rails_audit_log:migrate_from_paper_trail
+bin/rails db:migrate
 ```
 
-### RSpec matchers
+The generated migration reads every row from PaperTrail's `versions` table and inserts it into `audit_log_entries`.
+
+### Column mapping
+
+| PaperTrail `versions` | `audit_log_entries` | Notes |
+|---|---|---|
+| `item_type` | `item_type` | Direct copy |
+| `item_id` | `item_id` | Direct copy |
+| `event` | `event` | `create` / `update` / `destroy` only; other values are skipped |
+| `object_changes` | `object_changes` | YAML or JSON → JSON (see below) |
+| `object` | `object` | YAML or JSON → JSON (see below) |
+| `whodunnit` | `whodunnit_snapshot` | PaperTrail stores actor as a plain string |
+| `created_at` | `created_at` | Direct copy |
+| — | `actor_type` / `actor_id` | **Not populated** — cannot be inferred from a string `whodunnit` |
 
-Add to your `spec/rails_helper.rb` (or `spec_helper.rb`):
+### YAML and JSON serialization
+
+PaperTrail serializes `object` and `object_changes` as **YAML** by default and as **JSON** when `PaperTrail.serializer = PaperTrail::Serializers::JSON` is configured. The migration handles both transparently — it tries JSON first, then falls back to YAML (with a permissive class list for the Ruby types PaperTrail commonly serializes).
+
+### Compatibility shim for gradual migration
+
+If you need your codebase to keep using PaperTrail's API while migrating, include `RailsAuditLog::PaperTrailCompat` alongside `Auditable`:
 
 ```ruby
-require "rails_audit_log/matchers"
+require "rails_audit_log/paper_trail_compat"
 
-RSpec.configure do |config|
-  config.include RailsAuditLog::Matchers
+class Article < ApplicationRecord
+  include RailsAuditLog::Auditable
+  include RailsAuditLog::PaperTrailCompat
 end
 ```
 
-Then use the matchers in any spec:
+This adds the familiar PaperTrail surface:
 
 ```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)
+article.versions                          # audit_log_entries ordered oldest-first
+article.paper_trail.version               # most recent AuditLogEntry
+article.paper_trail.previous_version      # reconstructed previous state (reify)
+article.paper_trail.originator            # whodunnit_snapshot string
+article.paper_trail.version_at(1.week.ago) # reconstructed state at a point in time
 ```
 
+`AuditLogEntry#reify` already matches PaperTrail's `Version#reify` — no additional alias needed.
+
+### What is not migrated
+
+- `versions` rows with an `event` value outside `create`, `update`, `destroy` (custom events added by some apps)
+- `actor_type` and `actor_id` — PaperTrail's `whodunnit` is a plain string and does not identify the actor model
+
+---
+
+## Companion gems
+
+[↑ Table of contents](#table-of-contents)
+
+> Coming in the 1.x series
+
+| Gem | What it adds |
+|---|---|
+| `rails_audit_log-graphql` | Mountable GraphQL endpoint at `/audit/graphql` — queryable audit trail for API-first apps without forcing `graphql-ruby` on users who don't need it |
+
+Each companion gem declares `rails_audit_log` as a dependency so you only add what you use.
+
 ## Requirements
 
+[↑ Table of contents](#table-of-contents)
+
 - Ruby >= 3.3
 - Rails >= 7.2
 
+## Performance
+
+[↑ Table of contents](#table-of-contents)
+
+See [BENCHMARKS.md](BENCHMARKS.md) for write throughput, `batch_audit` gains, query performance, storage efficiency, and notes on comparing against PaperTrail. To run the suite locally:
+
+```bash
+bundle exec rake dev:setup
+bundle exec rake benchmark
+```
+
 ## Contributing
 
+[↑ Table of contents](#table-of-contents)
+
 Bug reports and pull requests are welcome on [GitHub](https://github.com/eclectic-coding/rails_audit_log).
 
 ## License
 
+[↑ Table of contents](#table-of-contents)
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -16,6 +16,11 @@ end
 
 task default: ["bundle:audit:update", "bundle:audit:check", :rubocop, :zeitwerk, :spec]
 
+desc "Run the performance benchmark suite (requires dev:setup first)"
+task :benchmark do
+  sh "bundle exec ruby benchmarks/suite.rb"
+end
+
 # Development database tasks (operate on spec/dummy)
 namespace :dev do
   dummy_env = { "RAILS_ENV" => "development" }

data/app/concerns/rails_audit_log/auditable.rb

@@ -1,4 +1,24 @@
 module RailsAuditLog
+  # Include in any ActiveRecord model to automatically track +create+, +update+,
+  # and +destroy+ events as {AuditLogEntry} records.
+  #
+  # == Basic usage
+  #
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #   end
+  #
+  # == Configuring tracking
+  #
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #     audit_log only: %i[title body],
+  #               meta: { tenant_id: -> { Current.tenant_id } },
+  #               version_limit: 50,
+  #               async: true
+  #   end
+  #
+  # Adds a polymorphic +has_many :audit_log_entries+ association to the model.
   module Auditable
     extend ActiveSupport::Concern
 
@@ -12,6 +32,8 @@ module RailsAuditLog
 
       _warn_if_audit_table_missing
 
+      # All {AuditLogEntry} records for this object, newest first by default.
+      # Destroyed when the object is destroyed.
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
                as: :item,
@@ -54,6 +76,7 @@ module RailsAuditLog
     end
 
     class_methods do
+      # @api private
       def _warn_if_audit_table_missing
         return if connection.table_exists?("audit_log_entries")
 
@@ -66,6 +89,33 @@ module RailsAuditLog
         # DB not reachable during this phase (e.g. before db:create) — skip the check
       end
 
+      # Configures auditing options for this model. Call once in the class body
+      # after +include RailsAuditLog::Auditable+.
+      #
+      # @param only [Array<Symbol>, nil] whitelist of attributes to track;
+      #   when set, all other attributes are ignored regardless of +ignore:+
+      # @param ignore [Array<Symbol>, nil] additional attributes to exclude on
+      #   top of {RailsAuditLog.ignored_attributes}; ignored when +only:+ is set
+      # @param meta [Hash{Symbol => Proc}, nil] per-entry metadata; each value
+      #   is a lambda called at write time — zero-argument lambdas receive no
+      #   arguments, one-argument lambdas receive the record instance
+      # @param associations [Boolean, Array<Symbol>, nil] when +true+, tracks
+      #   all +has_many+ and +has_and_belongs_to_many+ associations; pass an
+      #   array of association names to track only specific ones
+      # @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 async [Boolean, nil] when +true+, writes are dispatched via
+      #   +WriteAuditLogJob+; overrides {RailsAuditLog.async} for this model
+      # @return [void]
+      # @example
+      #   class Article < ApplicationRecord
+      #     include RailsAuditLog::Auditable
+      #     audit_log only: %i[title body published_at],
+      #               meta: { tenant_id: -> { Current.tenant_id } },
+      #               associations: %i[tags],
+      #               version_limit: 100
+      #   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
@@ -76,6 +126,13 @@ module RailsAuditLog
       end
     end
 
+    # Executes the block with audit logging disabled for this record's writes.
+    # A convenience wrapper around {RailsAuditLog.disable}.
+    #
+    # @yield executes the block without recording any audit entries
+    # @return [Object] the return value of the block
+    # @example Skip auditing during a bulk update
+    #   post.skip_audit_log { post.update!(cached_at: Time.current) }
     def skip_audit_log
       RailsAuditLog.disable { yield }
     end

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

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