rails_audit_log 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb82307e35624fe226336c4fb33559b5432a6290c4978076aadec80e6939afa0
-  data.tar.gz: 47e700f38e3d1fbe2a0953ba687285389721b31e8a6531dcbc5e336c6d9af438
+  metadata.gz: 6cc56d9335d26c5f43d52de380aa354a268cbb266696799cf1775f051162c2d8
+  data.tar.gz: '027792cdf8815ec2822177492b674d05534a3d96163d463dd603a415d471ace2'
 SHA512:
-  metadata.gz: 5dc66b780e8d1875260ef21c143b3ec823832ffa7e90c58f8392e002515d4cbe30c797936f4766bd15791a9b1b37e2f8918973f33fec58e396ca117a3623a563
-  data.tar.gz: d7fbf0c15e39d95a57270203b296ce5bac2835cc15f69d44cd6a7b000a884bc8d639cee91de5c1dd84aeaec64795fa6325397a1926a67f9a8317cc1128c18808
+  metadata.gz: 107247da00cc1f7eec9750f9d59eb2b41fa47f4ec9c3a0b00f587882bf6080250fe5af5152a2d13491fdb6ebf6aa7d3f82a6418f89777b9dca3819c024692805
+  data.tar.gz: 3715691ec2538d7fca5538af23e9f087899469876dcb98b660d82f18230ee531f45660950c95e4230f15a6a430b4b85999691472b9c61cf1d4e88af6c90849c2

data/README.md

@@ -102,6 +102,55 @@ entry.diff
 # => { "title" => { from: "Hello", to: "World" } }
 ```
 
+### 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.
+
 ### Selective tracking
 
 Track only specific attributes, or exclude noisy ones:
@@ -179,6 +228,68 @@ 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:

data/app/concerns/rails_audit_log/auditable.rb

@@ -3,8 +3,10 @@ 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_only,         default: nil
+      class_attribute :_audit_log_ignore,        default: nil
+      class_attribute :_audit_log_meta,          default: nil
+      class_attribute :_audit_log_associations,  default: nil
 
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
@@ -14,12 +16,45 @@ 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)
+      def audit_log(only: nil, ignore: nil, meta: nil, associations: 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?
       end
     end
 
@@ -44,6 +79,24 @@ 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
+      RailsAuditLog::AuditLogEntry.create!(
+        event:              "update",
+        item_type:          self.class.name,
+        item_id:            id,
+        object_changes:     { assoc_name => [before, after] },
+        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?
 
@@ -51,17 +104,32 @@ module RailsAuditLog
       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,
-        object:         snapshot,
-        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") }
@@ -50,8 +51,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)
@@ -82,6 +88,14 @@ module RailsAuditLog
       object_changes.transform_values { |from_to| { from: from_to[0], to: from_to[1] } }
     end
 
+    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

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

@@ -6,6 +6,9 @@ class CreateAuditLogEntries < ActiveRecord::Migration[<%= ActiveRecord::Migratio
       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.4.0"
+  VERSION = "0.6.0"
 end

data/lib/rails_audit_log.rb

@@ -6,6 +6,18 @@ module RailsAuditLog
   # 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]
@@ -35,6 +47,22 @@ module RailsAuditLog
     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)
@@ -45,7 +73,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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chuck Smith