rails_audit_log 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99754d2a1e8f4d7bba4cff5815b8bd6df8e8569f8817da525611e97a586d3114
-  data.tar.gz: 9fe8b370070705d1eb5685bceaa82474b63f981a51b22911db337793dabe38ff
+  metadata.gz: cb82307e35624fe226336c4fb33559b5432a6290c4978076aadec80e6939afa0
+  data.tar.gz: 47e700f38e3d1fbe2a0953ba687285389721b31e8a6531dcbc5e336c6d9af438
 SHA512:
-  metadata.gz: d7122bfd0a99dd298a48597690267a050a8baac1c7d7152f16e2b5766b3e4fac60b1d334f1fdc897a35d6e5b9dd26019204497ec73386257c3eecbe02ea9e36a
-  data.tar.gz: fea300d386237a044f3f57eb3fe94ac0109b5d8ec4e5704bcacdf80137bfeff8bb3df2ae05ee67baaaeee72b9f6a05f86cd8da625603d87b2fd9f801e27dd1c5
+  metadata.gz: 5dc66b780e8d1875260ef21c143b3ec823832ffa7e90c58f8392e002515d4cbe30c797936f4766bd15791a9b1b37e2f8918973f33fec58e396ca117a3623a563
+  data.tar.gz: d7fbf0c15e39d95a57270203b296ce5bac2835cc15f69d44cd6a7b000a884bc8d639cee91de5c1dd84aeaec64795fa6325397a1926a67f9a8317cc1128c18808

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,123 @@ 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)
+```
+
+### 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

@@ -3,6 +3,9 @@ module RailsAuditLog
     extend ActiveSupport::Concern
 
     included do
+      class_attribute :_audit_log_only,   default: nil
+      class_attribute :_audit_log_ignore, default: nil
+
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
                as: :item,
@@ -13,31 +16,63 @@ module RailsAuditLog
       after_destroy :record_audit_destroy
     end
 
+    class_methods do
+      def audit_log(only: nil, ignore: nil)
+        self._audit_log_only   = only.map(&:to_s)   if only
+        self._audit_log_ignore = ignore.map(&:to_s) if ignore
+      end
+    end
+
+    def skip_audit_log
+      RailsAuditLog.disable { yield }
+    end
+
     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
       RailsAuditLog::AuditLogEntry.create!(
         event:          event,
         item_type:      self.class.name,
         item_id:        id,
-        object_changes: changes,
+        object_changes: filtered,
+        object:         snapshot,
         actor_type:     actor&.class&.name,
         actor_id:       actor.respond_to?(:id) ? actor.id : nil
       )
     end
+
+    def filter_changes(changes)
+      result = changes.dup
+
+      if self.class._audit_log_only
+        result.select! { |k, _| self.class._audit_log_only.include?(k) }
+      else
+        ignored = self.class._audit_log_ignore || RailsAuditLog.ignored_attributes
+        result.reject! { |k, _| ignored.include?(k) }
+      end
+
+      result
+    end
   end
 end

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -38,6 +38,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 +82,11 @@ 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)
+    # 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,7 @@ 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.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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/rails_audit_log.rb

@@ -2,6 +2,11 @@ require "rails_audit_log/version"
 require "rails_audit_log/engine"
 
 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
+
   def self.actor
     Thread.current[:rails_audit_log_actor]
   end
@@ -17,4 +22,35 @@ module RailsAuditLog
   ensure
     self.actor = previous
   end
+
+  def self.enabled?
+    !Thread.current[:rails_audit_log_disabled]
+  end
+
+  def self.disable
+    previous = Thread.current[:rails_audit_log_disabled]
+    Thread.current[:rails_audit_log_disabled] = true
+    yield
+  ensure
+    Thread.current[:rails_audit_log_disabled] = 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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chuck Smith