rails_audit_log 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf93211ea95d97c01b541195ade4517d221d39035896e06a6432c512e5f284c0
-  data.tar.gz: f1bce85319393eaca9db2e078a0087e1f0818c1025fdd23e472fb8381a322b91
+  metadata.gz: 3323e92d5f10ecd832a198a65bf6e0fd65c7bf0ff35069230bc8b7791d14e7fa
+  data.tar.gz: 4cd882a647d273ee3fe8a6c7b7f89a3b241ee0fa9b22b84aed93b8aea2a30c6d
 SHA512:
-  metadata.gz: f0f9def2049dc5ca95e13fad9746bc84a79c7e8081d8e84dd0f4fbfd3915b57b9dd35aaa600687970475f49b395e15c6725d3c558b1272f7afda6ba3b18054c0
-  data.tar.gz: 1699b3f01dbfd55377144207ff36c987a83419adf318671a16676e5513fd31fc98f908e5b2f83cef3a9f7b597bdf7ac8fe2cf4da2c275f569bdcd4837a3a1727
+  metadata.gz: 7c8d577a7b027d8c300b62545930e94798967f5cdc7f57d4d84a06b3f1968d1357b6ea1db9ae8abf1cb3e36bda8e6fd12be6c2da0798cf7d6d6a02e60849621c
+  data.tar.gz: 69a905ee623f28403c53d280a56009cd81696406e22ff2f258ef2d0ec56fc4d7a154f72a0a345557ec8a39e0b36b655b3fba7c1a128bee954834e73d537946b6

data/README.md

@@ -102,6 +102,134 @@ 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:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log associations: true
+  has_many :tags
+  has_many :comments, dependent: :destroy
+end
+```
+
+Each add or remove creates an `update` entry on the parent with the associated record's identity in `object_changes`:
+
+```ruby
+post = Post.create!(title: "Hello")
+tag  = post.tags.create!(name: "Ruby")
+
+entry = post.audit_log_entries.updated_events.last
+entry.object_changes
+# => { "tags" => [nil, { "id" => 1, "type" => "Tag" }] }
+
+post.tags.delete(tag)
+entry = post.audit_log_entries.updated_events.last
+entry.object_changes
+# => { "tags" => [{ "id" => 1, "type" => "Tag" }, nil] }
+```
+
+Track only a named subset of associations:
+
+```ruby
+audit_log associations: [:tags]  # comments changes are not recorded
+```
+
+`has_many :through` and `has_and_belongs_to_many` work the same way — no extra configuration:
+
+```ruby
+class Post < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log associations: true
+  has_many :taggings
+  has_many :tags, through: :taggings   # tracked automatically
+  has_and_belongs_to_many :categories  # tracked automatically
+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:

data/app/concerns/rails_audit_log/auditable.rb

@@ -3,9 +3,12 @@ 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_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
 
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
@@ -15,13 +18,47 @@ module RailsAuditLog
       after_create  :record_audit_create
       after_update  :record_audit_update
       after_destroy :record_audit_destroy
+
+      # Intercept has_many (including :through) and has_and_belongs_to_many to
+      # inject after_add/after_remove callbacks when association tracking is
+      # enabled. Must be defined after has_many :audit_log_entries so that the
+      # internal association is not affected.
+      def self.has_many(name, scope = nil, **options, &extension)
+        if _audit_log_associations && name.to_s != "audit_log_entries"
+          options = _build_audit_association_options(name.to_s, options)
+        end
+        scope ? super(name, scope, **options, &extension) : super(name, **options, &extension)
+      end
+
+      def self.has_and_belongs_to_many(name, scope = nil, **options, &extension)
+        if _audit_log_associations
+          options = _build_audit_association_options(name.to_s, options)
+        end
+        scope ? super(name, scope, **options, &extension) : super(name, **options, &extension)
+      end
+
+      def self._build_audit_association_options(assoc_name, options)
+        tracked = _audit_log_associations == true ||
+                  Array(_audit_log_associations).map(&:to_s).include?(assoc_name)
+        return options unless tracked
+
+        add_cb    = ->(owner, rec) { owner.send(:record_audit_association_change, assoc_name, nil, { "id" => rec.id, "type" => rec.class.name }) }
+        remove_cb = ->(owner, rec) { owner.send(:record_audit_association_change, assoc_name, { "id" => rec.id, "type" => rec.class.name }, nil) }
+        options.merge(
+          after_add:    [*options[:after_add]]    + [add_cb],
+          after_remove: [*options[:after_remove]] + [remove_cb]
+        )
+      end
     end
 
     class_methods do
-      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
+      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
 
@@ -46,6 +83,25 @@ module RailsAuditLog
       record_audit_entry("destroy", changes, snapshot)
     end
 
+    def record_audit_association_change(assoc_name, before, after)
+      return unless RailsAuditLog.enabled?
+
+      actor = RailsAuditLog.actor
+      meta  = build_audit_metadata
+      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,
+        actor_type:         actor&.class&.name,
+        actor_id:           actor.respond_to?(:id) ? actor.id : nil
+      )
+    end
+
     def record_audit_entry(event, changes, snapshot = nil)
       return unless RailsAuditLog.enabled?
 
@@ -53,8 +109,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,
@@ -68,6 +124,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
@@ -51,8 +61,13 @@ module RailsAuditLog
         return instance
       end
 
-      # Fallback: diff-only mode or entries recorded before snapshot support
-      from_attrs = (object_changes || {}).transform_values { |from_to| from_to[0] }
+      # Fallback: diff-only mode or entries recorded before snapshot support.
+      # Filter to column names so association-change entries (e.g. tags, comments)
+      # don't get assigned to the record as if they were scalar attributes.
+      column_names = klass.column_names.map(&:to_s)
+      from_attrs = (object_changes || {})
+        .select { |k, _| column_names.include?(k) }
+        .transform_values { |from_to| from_to[0] }
 
       if event == "update"
         record = klass.find_by(id: item_id)

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/version.rb

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

data/lib/rails_audit_log.rb

@@ -7,6 +7,9 @@ module RailsAuditLog
   mattr_accessor :ignored_attributes, default: %w[updated_at]
   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 +66,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)
@@ -73,7 +94,10 @@ module RailsAuditLog
     return nil if entry.nil? || entry.event == "destroy"
 
     klass = record.class
-    to_attrs = (entry.object_changes || {}).transform_values { |v| v[1] }
+    column_names = klass.column_names.map(&:to_s)
+    to_attrs = (entry.object_changes || {})
+      .select { |k, _| column_names.include?(k) }
+      .transform_values { |v| v[1] }
     attrs = entry.object.present? ? entry.object.merge(to_attrs) : to_attrs
 
     instance = klass.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -41,6 +41,7 @@ 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