rails_audit_log 0.9.0 → 1.0.0

data/lib/rails_audit_log.rb

@@ -1,45 +1,153 @@
 require "rails_audit_log/version"
 require "rails_audit_log/engine"
 
+# RailsAuditLog is a Rails engine that tracks ActiveRecord +create+, +update+,
+# and +destroy+ events as {AuditLogEntry} records with JSON-first storage and
+# thread-local actor context.
+#
+# == Quick start
+#
+#   # config/initializers/rails_audit_log.rb
+#   RailsAuditLog.configure do |config|
+#     config.ignored_attributes = %w[updated_at cached_at]
+#     config.store_snapshot      = true
+#     config.async               = false
+#   end
+#
+#   # app/models/article.rb
+#   class Article < ApplicationRecord
+#     include RailsAuditLog::Auditable
+#     audit_log only: %i[title body]
+#   end
+#
+#   # app/controllers/application_controller.rb
+#   class ApplicationController < ActionController::Base
+#     include RailsAuditLog::Controller
+#     audit_log_actor { current_user }
+#   end
 module RailsAuditLog
-  # Global default columns to ignore across all audited models.
-  # Override in an initializer: RailsAuditLog.ignored_attributes = %w[updated_at cached_at]
+  # Columns ignored on every audited model unless overridden with +only:+ or
+  # +ignore:+ on {Auditable.audit_log}.
+  #
+  # @return [Array<String>]
   mattr_accessor :ignored_attributes, default: %w[updated_at]
 
-  def self.configure
-    yield self
-  end
+  # Whether to store a full snapshot of the record's attributes in the +object+
+  # column alongside +object_changes+. Disable to reduce storage at the cost of
+  # losing {AuditLogEntry#reify} fidelity for pre-snapshot entries.
+  #
+  # @return [Boolean]
   mattr_accessor :store_snapshot, default: true
+
+  # When +true+, captures +remote_ip+ and +user_agent+ from the current request
+  # and merges them into every entry's +metadata+ column.
+  # Requires {Controller} to be included in your base controller.
+  #
+  # @return [Boolean]
   mattr_accessor :capture_request_metadata, default: false
+
+  # Global cap on the number of {AuditLogEntry} records kept per tracked object.
+  # Oldest entries are pruned after each write once the limit is exceeded.
+  # Override per-model with <tt>audit_log version_limit: N</tt>.
+  #
+  # @return [Integer, nil]
   mattr_accessor :version_limit, 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>.
+  #
+  # @return [Boolean]
   mattr_accessor :async, default: false
+
+  # Passes +connects_to+ options directly to {AuditLogEntry} so audit entries
+  # can be stored on a separate database.
+  #
+  # @return [Hash, nil]
+  # @example
+  #   RailsAuditLog.connects_to = { database: { writing: :audit_primary } }
   mattr_accessor :connects_to, default: nil
-  mattr_accessor :page_size,   default: 25
 
+  # Number of entries per page in the web dashboard.
+  #
+  # @return [Integer]
+  mattr_accessor :page_size, default: 25
+
+  # Controls how an actor object is serialised into the +whodunnit_snapshot+
+  # string column. Defaults to +actor.name+ when available, otherwise +to_s+.
+  #
+  # @return [Proc]
+  # @example Store email instead of name
+  #   RailsAuditLog.whodunnit_display = ->(actor) { actor.email }
+  mattr_accessor :whodunnit_display, default: ->(actor) {
+    actor.respond_to?(:name) ? actor.name.to_s : actor.to_s
+  }
+
+  # Yields the module so every +mattr_accessor+ setter is reachable as
+  # <tt>config.setting = value</tt>.
+  #
+  # @yield [RailsAuditLog] the module itself
+  # @return [void]
+  # @example
+  #   RailsAuditLog.configure do |config|
+  #     config.ignored_attributes = %w[updated_at]
+  #     config.async = true
+  #   end
+  def self.configure
+    yield self
+  end
+
+  # Sets or returns the authentication block used to gate the web dashboard.
+  # The block is evaluated in controller context, so controller helpers
+  # (e.g. +current_user+) are available directly.
+  # When the block returns falsy, the engine falls back to HTTP Basic auth.
+  #
+  # @yield block evaluated in controller context; return truthy to allow access
+  # @return [Proc, nil] the stored block, or +nil+ when not configured
+  # @example Require admin access
+  #   RailsAuditLog.authenticate { current_user&.admin? }
   def self.authenticate(&block)
     @authenticate = block if block_given?
     @authenticate
   end
-  mattr_accessor :whodunnit_display, default: ->(actor) {
-    actor.respond_to?(:name) ? actor.name.to_s : actor.to_s
-  }
 
+  # Returns the request metadata hash attached to the current thread.
+  # Populated by {Controller} when {.capture_request_metadata} is +true+.
+  #
+  # @return [Hash, nil]
   def self.request_metadata
     Thread.current[:rails_audit_log_request_metadata]
   end
 
+  # @param value [Hash, nil] metadata hash to store on the current thread
+  # @return [Hash, nil]
   def self.request_metadata=(value)
     Thread.current[:rails_audit_log_request_metadata] = value
   end
 
+  # Returns the actor set on the current thread (e.g. the signed-in user).
+  #
+  # @return [Object, nil]
   def self.actor
     Thread.current[:rails_audit_log_actor]
   end
 
+  # Sets the actor on the current thread. Prefer {.with_actor} for scoped
+  # assignment so the value is always restored.
+  #
+  # @param actor [Object, nil]
+  # @return [Object, nil]
   def self.actor=(actor)
     Thread.current[:rails_audit_log_actor] = actor
   end
 
+  # Sets the actor for the duration of the block, then restores the previous
+  # value. Use this in background jobs and rake tasks.
+  #
+  # @param actor [Object] the actor to set (e.g. a +User+ record)
+  # @yield executes the block with +actor+ as the current actor
+  # @return [Object] the return value of the block
+  # @example
+  #   RailsAuditLog.with_actor(robot_user) { DataImporter.new.run }
   def self.with_actor(actor)
     previous = self.actor
     self.actor = actor
@@ -48,10 +156,20 @@ module RailsAuditLog
     self.actor = previous
   end
 
+  # Returns +true+ when audit logging is active on the current thread.
+  #
+  # @return [Boolean]
   def self.enabled?
     !Thread.current[:rails_audit_log_disabled]
   end
 
+  # Suspends audit logging for the duration of the block on the current thread.
+  # Useful in seeds, factories, and test setup where audit noise is unwanted.
+  #
+  # @yield executes the block with audit logging disabled
+  # @return [Object] the return value of the block
+  # @example
+  #   RailsAuditLog.disable { Post.create!(title: "seed post") }
   def self.disable
     previous = Thread.current[:rails_audit_log_disabled]
     Thread.current[:rails_audit_log_disabled] = true
@@ -60,14 +178,27 @@ module RailsAuditLog
     Thread.current[:rails_audit_log_disabled] = previous
   end
 
+  # Returns the reason string set on the current thread.
+  #
+  # @return [String, nil]
   def self.reason
     Thread.current[:rails_audit_log_reason]
   end
 
+  # @param value [String, nil]
+  # @return [String, nil]
   def self.reason=(value)
     Thread.current[:rails_audit_log_reason] = value
   end
 
+  # Sets a human-readable reason for the changes made within the block.
+  # The reason is stored in each {AuditLogEntry#reason} and restored afterwards.
+  #
+  # @param value [String] reason to attach to every entry written in the block
+  # @yield executes the block with +value+ as the current reason
+  # @return [Object] the return value of the block
+  # @example
+  #   RailsAuditLog.audit_log_reason("bulk import") { records.each(&:save!) }
   def self.audit_log_reason(value)
     previous = self.reason
     self.reason = value
@@ -76,6 +207,18 @@ module RailsAuditLog
     self.reason = previous
   end
 
+  # Collects all {AuditLogEntry} records created within the block and inserts
+  # them with a single <tt>INSERT ... VALUES (…), (…)</tt> via +insert_all!+
+  # instead of one INSERT per record.
+  #
+  # Calls are idempotent: if a batch is already in progress on the current
+  # thread (i.e. a nested call), the inner block joins the outer batch.
+  #
+  # @yield executes the block; any audit entries created are buffered
+  # @return [Object] the return value of the block
+  # @raise [ActiveRecord::RecordInvalid] if any entry fails the +insert_all!+
+  # @example
+  #   RailsAuditLog.batch_audit { 500.times { |i| Post.create!(title: "Post #{i}") } }
   def self.batch_audit
     return yield if Thread.current[:rails_audit_log_batch]
 
@@ -90,10 +233,29 @@ module RailsAuditLog
     end
   end
 
+  # Returns the in-progress batch buffer for the current thread, or +nil+ when
+  # no batch is active.
+  #
+  # @api private
+  # @return [Array<Hash>, nil]
   def self.batch_audit_buffer
     Thread.current[:rails_audit_log_batch]
   end
 
+  # Reconstructs the state of +record+ as it was at +time+ by replaying audit
+  # entries up to that timestamp.
+  #
+  # Returns an unsaved, non-persisted instance of +record.class+ whose
+  # attributes match the record's state at +time+, or +nil+ when no audit
+  # entry exists before +time+ or the record was destroyed at or before +time+.
+  #
+  # @param record [ActiveRecord::Base] the record to reconstruct
+  # @param time [Time] the point in time to reconstruct at
+  # @return [ActiveRecord::Base, nil] a new, unpersisted instance; or +nil+
+  # @example
+  #   post = Post.find(42)
+  #   snapshot = RailsAuditLog.version_at(post, 1.week.ago)
+  #   snapshot.title  # => title as it was a week ago
   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.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -65,9 +65,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '43.0'
-description: A modern Rails engine that tracks ActiveRecord create, update, and destroy
-  events with JSON-first storage, whodunnit actor context, and a clean query API.
-  Drop-in replacement for PaperTrail with no legacy baggage.
+description: Rails engine that tracks ActiveRecord create, update, and destroy events
+  as structured JSON records. Ships a mountable web dashboard, whodunnit actor context,
+  batch inserts via insert_all!, async writes via ActiveJob, time-travel reconstruction,
+  RSpec matchers, Minitest assertions, and a migration path from PaperTrail.
 email:
 - chuck@eclecticcoding.com
 executables: []
@@ -111,10 +112,13 @@ files:
 - 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/generators/rails_audit_log/migrate_from_paper_trail/migrate_from_paper_trail_generator.rb
+- lib/generators/rails_audit_log/migrate_from_paper_trail/templates/migrate_from_paper_trail.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/paper_trail_compat.rb
 - lib/rails_audit_log/test_helpers.rb
 - lib/rails_audit_log/version.rb
 - lib/tasks/rails_audit_log_tasks.rake
@@ -142,5 +146,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Zeitwerk-native audit logging for ActiveRecord
+summary: Audit logging for Rails with a web dashboard and JSON-first storage
 test_files: []