rails_audit_log 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adf2bbd729f0c0a53c0016389d8b8af4ca66cedede3343bb3376cf880edc447c
-  data.tar.gz: 640764fdbe148a2f8d0309350ae74358256b7cc9b530f0c35d0bc045ef736b4c
+  metadata.gz: cf93211ea95d97c01b541195ade4517d221d39035896e06a6432c512e5f284c0
+  data.tar.gz: f1bce85319393eaca9db2e078a0087e1f0818c1025fdd23e472fb8381a322b91
 SHA512:
-  metadata.gz: 938374f49a4385c038124abb6aeb95eaa8369dccc20d8eb125e96071954c3b8858cb22dc94781bdfa31e96d006645df5bb07f989c83d4ca35d1792451cb82f07
-  data.tar.gz: 82f6ca3524c11b954705d62b576d11c8ae5008f49b26c973789d43466a6d1ab3d4462fd012885a0b83177220c8ceda83c381af5db07e0b371deafca1db14badc
+  metadata.gz: f0f9def2049dc5ca95e13fad9746bc84a79c7e8081d8e84dd0f4fbfd3915b57b9dd35aaa600687970475f49b395e15c6725d3c558b1272f7afda6ba3b18054c0
+  data.tar.gz: 1699b3f01dbfd55377144207ff36c987a83419adf318671a16676e5513fd31fc98f908e5b2f83cef3a9f7b597bdf7ac8fe2cf4da2c275f569bdcd4837a3a1727

data/README.md

@@ -39,7 +39,7 @@ Every `create`, `update`, and `destroy` is now recorded automatically:
 
 ```ruby
 article = Article.create!(title: "Hello")
-article.audit_log_entries.count      # => 1
+article.audit_log_entries.count       # => 1
 article.audit_log_entries.first.event # => "create"
 
 article.update!(title: "World")
@@ -77,6 +77,185 @@ RailsAuditLog.with_actor(current_user) do
 end
 ```
 
+### Querying the audit log
+
+```ruby
+# Event scopes
+article.audit_log_entries.created_events
+article.audit_log_entries.updated_events
+article.audit_log_entries.destroyed_events
+
+# Filter by actor, resource, or time
+RailsAuditLog::AuditLogEntry.by_actor(current_user)
+RailsAuditLog::AuditLogEntry.for_resource(Article)
+RailsAuditLog::AuditLogEntry.for_resource(article)
+RailsAuditLog::AuditLogEntry.since(1.week.ago)
+RailsAuditLog::AuditLogEntry.until(Date.yesterday)
+
+# Find entries that touched a specific attribute
+RailsAuditLog::AuditLogEntry.touching(:title)
+
+# Inspect what changed
+entry = article.audit_log_entries.last
+entry.changed_attributes  # => ["title"]
+entry.diff
+# => { "title" => { from: "Hello", to: "World" } }
+```
+
+### Selective tracking
+
+Track only specific attributes, or exclude noisy ones:
+
+```ruby
+class Article < ApplicationRecord
+  include RailsAuditLog::Auditable
+
+  # Track only these columns
+  audit_log only: [:title, :status]
+
+  # Or exclude specific columns
+  audit_log ignore: [:cached_at, :views_count]
+end
+```
+
+Configure global defaults in an initializer:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.ignored_attributes = %w[updated_at cached_at]
+```
+
+Updates that produce no tracked changes after filtering are silently skipped.
+
+### Disabling auditing
+
+Suppress all audit writes inside a block — thread-safe, works in jobs and imports:
+
+```ruby
+RailsAuditLog.disable do
+  Article.insert_all!(bulk_rows)
+end
+
+RailsAuditLog.enabled? # => true (restored after the block)
+```
+
+Disable on a specific record instance:
+
+```ruby
+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:
+
+```ruby
+article.update!(title: "v2")
+entry = article.audit_log_entries.updated_events.last
+
+previous = entry.reify
+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
+
+```ruby
+snapshot = RailsAuditLog.version_at(article, 1.week.ago)
+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
+
+```ruby
+entry = article.audit_log_entries.updated_events.last
+entry.previous  # => the entry before this one
+entry.next      # => the entry after this one (nil if last)
+```
+
+### Attaching a reason
+
+Record a free-text rationale alongside any write using a thread-local block — safe to nest, cleared automatically:
+
+```ruby
+RailsAuditLog.audit_log_reason("Approved by legal") do
+  contract.update!(status: "approved")
+end
+
+entry.reason  # => "Approved by legal"
+```
+
+### Arbitrary metadata
+
+The `metadata` JSON column accepts any key/value hash. Populate it automatically with `audit_log meta:`:
+
+```ruby
+class Article < ApplicationRecord
+  include RailsAuditLog::Auditable
+
+  # Zero-arg lambda — evaluated at write time (good for thread-locals)
+  # One-arg lambda — receives the record instance
+  audit_log meta: {
+    tenant_id:    -> { Current.tenant.id },
+    title_length: ->(record) { record.title.length }
+  }
+end
+
+entry.metadata  # => { "tenant_id" => "acme", "title_length" => 12 }
+```
+
+### Request metadata capture
+
+Enable opt-in capture of `remote_ip` and `user_agent` from the current request in an initializer:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.capture_request_metadata = true
+```
+
+When enabled, the `Controller` concern automatically stores these into each entry's `metadata` column:
+
+```ruby
+entry.metadata  # => { "remote_ip" => "203.0.113.1", "user_agent" => "Mozilla/5.0 ..." }
+```
+
+Request metadata and `audit_log meta:` values are merged together automatically.
+
+### Actor display name snapshot
+
+`whodunnit_snapshot` stores the actor's display name at write time so entries remain meaningful even after the actor record is deleted:
+
+```ruby
+entry.whodunnit_snapshot  # => "Alice"  (even if the User record is later deleted)
+```
+
+The default display proc uses `actor.name` if available, otherwise `actor.to_s`. Override globally in an initializer:
+
+```ruby
+RailsAuditLog.whodunnit_display = ->(actor) { actor.email }
+```
+
+### Object snapshot storage
+
+By default every entry stores a full `object` snapshot of the pre-change state alongside `object_changes`. This makes `reify` and `version_at` reliable without any database lookups:
+
+```ruby
+entry.object          # => { "id" => 1, "title" => "v1", ... }
+entry.object_changes  # => { "title" => ["v1", "v2"] }
+```
+
+To save storage at the cost of reduced reification accuracy, switch to diff-only mode:
+
+```ruby
+RailsAuditLog.store_snapshot = false
+```
+
 ## Requirements
 
 - Ruby >= 3.3

data/app/concerns/rails_audit_log/auditable.rb

@@ -5,6 +5,7 @@ module RailsAuditLog
     included do
       class_attribute :_audit_log_only,   default: nil
       class_attribute :_audit_log_ignore, default: nil
+      class_attribute :_audit_log_meta,   default: nil
 
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
@@ -17,9 +18,10 @@ module RailsAuditLog
     end
 
     class_methods do
-      def audit_log(only: nil, ignore: nil)
+      def audit_log(only: nil, ignore: nil, meta: 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
       end
     end
 
@@ -30,35 +32,53 @@ module RailsAuditLog
     private
 
     def record_audit_create
-      record_audit_entry("create", saved_changes)
+      record_audit_entry("create", saved_changes, nil)
     end
 
     def record_audit_update
-      record_audit_entry("update", saved_changes)
+      snapshot = attributes.merge(saved_changes.transform_values { |v| v[0] }) if RailsAuditLog.store_snapshot
+      record_audit_entry("update", saved_changes, snapshot)
     end
 
     def record_audit_destroy
+      snapshot = attributes.dup if RailsAuditLog.store_snapshot
       changes = attributes.transform_values { |v| [v, nil] }
-      record_audit_entry("destroy", changes)
+      record_audit_entry("destroy", changes, snapshot)
     end
 
-    def record_audit_entry(event, changes)
+    def record_audit_entry(event, changes, snapshot = nil)
       return unless RailsAuditLog.enabled?
 
       filtered = filter_changes(changes)
       return if filtered.empty? && event == "update"
 
       actor = RailsAuditLog.actor
+      meta = build_audit_metadata
       RailsAuditLog::AuditLogEntry.create!(
-        event:          event,
-        item_type:      self.class.name,
-        item_id:        id,
-        object_changes: filtered,
-        actor_type:     actor&.class&.name,
-        actor_id:       actor.respond_to?(:id) ? actor.id : nil
+        event:               event,
+        item_type:           self.class.name,
+        item_id:             id,
+        object_changes:      filtered,
+        object:              snapshot,
+        reason:              RailsAuditLog.reason,
+        metadata:            meta.presence,
+        whodunnit_snapshot:  actor ? RailsAuditLog.whodunnit_display.call(actor) : nil,
+        actor_type:          actor&.class&.name,
+        actor_id:            actor.respond_to?(:id) ? actor.id : nil
       )
     end
 
+    def build_audit_metadata
+      meta = {}
+      if self.class._audit_log_meta
+        self.class._audit_log_meta.each do |key, callable|
+          meta[key.to_s] = callable.arity == 0 ? callable.call : callable.call(self)
+        end
+      end
+      meta.merge!(RailsAuditLog.request_metadata || {})
+      meta
+    end
+
     def filter_changes(changes)
       result = changes.dup
 

data/app/concerns/rails_audit_log/controller.rb

@@ -5,6 +5,8 @@ module RailsAuditLog
     included do
       before_action :set_audit_log_actor
       after_action  :clear_audit_log_actor
+      before_action :capture_audit_log_request_metadata
+      after_action  :clear_audit_log_request_metadata
     end
 
     class_methods do
@@ -27,5 +29,20 @@ module RailsAuditLog
     def clear_audit_log_actor
       RailsAuditLog.actor = nil
     end
+
+    def capture_audit_log_request_metadata
+      return unless RailsAuditLog.capture_request_metadata
+
+      RailsAuditLog.request_metadata = {
+        "remote_ip" => request.remote_ip,
+        "user_agent" => request.user_agent
+      }.compact
+    end
+
+    def clear_audit_log_request_metadata
+      return unless RailsAuditLog.capture_request_metadata
+
+      RailsAuditLog.request_metadata = nil
+    end
   end
 end

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -10,6 +10,7 @@ module RailsAuditLog
     validates :event, presence: true, inclusion: { in: EVENTS }
     validates :item_type, presence: true
     validates :item_id, presence: true
+    validate :metadata_must_be_a_hash
 
     # Event scopes
     scope :created_events,  -> { where(event: "create") }
@@ -38,6 +39,40 @@ module RailsAuditLog
 
     # Instance methods
 
+    def reify
+      return nil if event == "create"
+
+      klass = item_type.constantize
+
+      if object.present?
+        instance = klass.new
+        instance.assign_attributes(object.except("id"))
+        instance.id = object.fetch("id") { item_id }
+        return instance
+      end
+
+      # Fallback: diff-only mode or entries recorded before snapshot support
+      from_attrs = (object_changes || {}).transform_values { |from_to| from_to[0] }
+
+      if event == "update"
+        record = klass.find_by(id: item_id)
+        from_attrs = record.attributes.merge(from_attrs) if record
+      end
+
+      instance = klass.new
+      instance.assign_attributes(from_attrs.except("id"))
+      instance.id = from_attrs.fetch("id") { item_id }
+      instance
+    end
+
+    def previous
+      self.class.where(item_type: item_type, item_id: item_id).where("id < ?", id).order(id: :desc).first
+    end
+
+    def next
+      self.class.where(item_type: item_type, item_id: item_id).where("id > ?", id).order(id: :asc).first
+    end
+
     def changed_attributes
       object_changes&.keys || []
     end
@@ -48,11 +83,19 @@ module RailsAuditLog
       object_changes.transform_values { |from_to| { from: from_to[0], to: from_to[1] } }
     end
 
-    # Attribute scope — uses json_extract (SQLite/MySQL) or json ? key (PostgreSQL)
+    private
+
+    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 ? :key", key: attribute.to_s)
+        where("object_changes->>? IS NOT NULL", attribute.to_s)
         # :nocov:
       else
         where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")

data/lib/generators/rails_audit_log/install/templates/create_audit_log_entries.rb

@@ -5,6 +5,10 @@ class CreateAuditLogEntries < ActiveRecord::Migration[<%= ActiveRecord::Migratio
       t.string  :item_type,  null: false
       t.bigint  :item_id,    null: false
       t.json    :object_changes
+      t.json    :object
+      t.json    :metadata
+      t.string  :reason
+      t.string  :whodunnit_snapshot
       t.string  :actor_type
       t.bigint  :actor_id
       t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }

data/lib/rails_audit_log/version.rb

@@ -1,3 +1,3 @@
 module RailsAuditLog
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/rails_audit_log.rb

@@ -5,6 +5,19 @@ 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]
+  mattr_accessor :store_snapshot, default: true
+  mattr_accessor :capture_request_metadata, default: false
+  mattr_accessor :whodunnit_display, default: ->(actor) {
+    actor.respond_to?(:name) ? actor.name.to_s : actor.to_s
+  }
+
+  def self.request_metadata
+    Thread.current[:rails_audit_log_request_metadata]
+  end
+
+  def self.request_metadata=(value)
+    Thread.current[:rails_audit_log_request_metadata] = value
+  end
 
   def self.actor
     Thread.current[:rails_audit_log_actor]
@@ -33,4 +46,39 @@ module RailsAuditLog
   ensure
     Thread.current[:rails_audit_log_disabled] = previous
   end
+
+  def self.reason
+    Thread.current[:rails_audit_log_reason]
+  end
+
+  def self.reason=(value)
+    Thread.current[:rails_audit_log_reason] = value
+  end
+
+  def self.audit_log_reason(value)
+    previous = self.reason
+    self.reason = value
+    yield
+  ensure
+    self.reason = previous
+  end
+
+  def self.version_at(record, time)
+    entry = AuditLogEntry
+      .where(item_type: record.class.name, item_id: record.id)
+      .where(created_at: ..time)
+      .order(created_at: :desc, id: :desc)
+      .first
+
+    return nil if entry.nil? || entry.event == "destroy"
+
+    klass = record.class
+    to_attrs = (entry.object_changes || {}).transform_values { |v| v[1] }
+    attrs = entry.object.present? ? entry.object.merge(to_attrs) : to_attrs
+
+    instance = klass.new
+    instance.assign_attributes(attrs.except("id"))
+    instance.id = attrs.fetch("id") { entry.item_id }
+    instance
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Chuck Smith