rails_audit_log 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40a23f8ea1990a26ea7f575102fb5ddd5f1a7323c796315672de57f0154faec3
-  data.tar.gz: 8b0563eebeeb21fe9836f3ff091640ae4a1c5484b45dc515abfc4647510cfae9
+  metadata.gz: 9e3de1e31a64d33c94042ea45ff4eeb391d48cc65db934bf7b7256656326c480
+  data.tar.gz: e34d558b4687f61336af9a7f7e6ae3faebe6ea77533e7da8e360d27dbfc70060
 SHA512:
-  metadata.gz: 29cc8682459e2d7968555a49faa77e47c00da42a54bf633f286dd01e89979be8fff6790aa0880de5d7516d23f1fc16f4a88c10b1e4aa086921c6052fdb812784
-  data.tar.gz: f1a1ba92cfe1c9a1ff0640b9b8a78f94275195fb018da97d89557b9612d631c31293b228e0715d059b790a3f0d2888069066f9897f376e43a40467c8c0c6dbd2
+  metadata.gz: cd8d51146c5b915b5c00cc863f23cffc70066cf4cfaafc5e667e9b064b225168b71f45d5699199ba37de78f0089cebabb8a1707f6f837642c32b0fb73c290a6c
+  data.tar.gz: 3abf1d5c1894de5496a76b8827eb23f6f8b430e9a4a192505e1012a3be022cf01290b5ef38cc3d9b43e2e4dc5f46c2e2667fdd77015ce0dfb111fab6141530b5

data/README.md

@@ -26,6 +26,8 @@ Audit logging for Rails. Tracks `create`, `update`, and `destroy` events as stru
   - [Time-based retention](#time-based-retention)
   - [Scheduled and manual pruning](#scheduled-and-manual-pruning)
   - [Encrypting audit data](#encrypting-audit-data)
+  - [Multi-tenancy](#multi-tenancy)
+  - [Event streaming](#event-streaming)
   - [Selective tracking](#selective-tracking)
   - [Disabling auditing](#disabling-auditing)
   - [Object reconstruction](#object-reconstruction)
@@ -427,6 +429,131 @@ The generator creates:
 - `config/initializers/rails_audit_log_encryption.rb` — reads the generated keys from credentials and passes them to `ActiveRecord::Encryption`
 - `db/migrate/TIMESTAMP_encrypt_rails_audit_log_entries.rb` — re-encrypts existing plain-text audit entries; edit `ENCRYPTED_MODELS` to list your model class names, then run `bin/rails db:migrate`
 
+### Multi-tenancy
+
+Store the current tenant on every audit entry so queries are naturally isolated per tenant.
+
+Run the generator to add the `tenant_id` column:
+
+```bash
+bin/rails generate rails_audit_log:tenant
+bin/rails db:migrate
+```
+
+Set a global resolver in your initializer — the block is called at write time:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.current_tenant { Current.tenant_id }
+```
+
+Or override per model:
+
+```ruby
+class Order < ApplicationRecord
+  include RailsAuditLog::Auditable
+  audit_log tenant: -> { Current.tenant_id }
+end
+```
+
+The per-model lambda takes precedence over the global resolver. Both accept zero-argument lambdas and store whatever the block returns in the `tenant_id` string column.
+
+Scope queries to a single tenant with `for_tenant`:
+
+```ruby
+AuditLogEntry.for_tenant("acme")
+AuditLogEntry.for_tenant(Current.tenant_id).updated_events.since(1.week.ago)
+```
+
+The web dashboard (`/audit`) automatically applies `for_tenant` when `current_tenant` is configured, so entries from other tenants are never exposed.
+
+#### Acts As Tenant integration
+
+Wire the resolver to `ActsAsTenant` in one line:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.acts_as_tenant!
+```
+
+This is equivalent to `RailsAuditLog.current_tenant { ActsAsTenant.current_tenant&.id }`.
+
+### Event streaming
+
+Publish every audit entry to an external consumer as it is written. Set any object implementing `#publish(entry)` as the adapter:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::NotificationsAdapter.new
+```
+
+#### NotificationsAdapter (built-in, zero dependencies)
+
+Publishes `rails_audit_log.entry_created` synchronously via `ActiveSupport::Notifications`:
+
+```ruby
+ActiveSupport::Notifications.subscribe("rails_audit_log.entry_created") do |*, payload|
+  entry = payload[:entry]
+  Rails.logger.info "Audit: #{entry.event} #{entry.item_type}##{entry.item_id}"
+end
+```
+
+#### ActiveJobAdapter (async)
+
+Enqueues `PublishEntryJob` so publishing does not block the request. The job fires the same `rails_audit_log.entry_created` notification when performed:
+
+```ruby
+RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::ActiveJobAdapter.new
+# or with a custom queue:
+RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::ActiveJobAdapter.new(queue: :streaming)
+```
+
+#### Custom adapters
+
+Any object implementing `#publish(entry)` works — no companion gem needed for Kafka, SQS, or any other transport:
+
+```ruby
+# Kafka via WaterDrop
+class KafkaAuditAdapter
+  def initialize(producer: WaterDrop::SyncProducer)
+    @producer = producer
+  end
+
+  def publish(entry)
+    @producer.call(entry.attributes.to_json, topic: "audit_log")
+  end
+end
+
+RailsAuditLog.streaming_adapter = KafkaAuditAdapter.new
+```
+
+```ruby
+# SQS via aws-sdk-sqs
+class SqsAuditAdapter
+  def initialize(queue_url:, client: Aws::SQS::Client.new)
+    @queue_url = queue_url
+    @client    = client
+  end
+
+  def publish(entry)
+    @client.send_message(
+      queue_url:    @queue_url,
+      message_body: entry.attributes.to_json
+    )
+  end
+end
+
+RailsAuditLog.streaming_adapter = SqsAuditAdapter.new(
+  queue_url: ENV.fetch("AUDIT_SQS_URL")
+)
+```
+
+Wrap the adapter in `ActiveJobAdapter` if you want publishing to be asynchronous and not block the request thread.
+
+#### Batch mode
+
+`batch_audit` flushes the bulk `INSERT` first, then calls `#publish` for each entry individually — streaming consumers receive every entry even in batch mode.
+
 ### Selective tracking
 
 Track only specific attributes, or exclude noisy ones:

data/app/concerns/rails_audit_log/auditable.rb

@@ -31,6 +31,7 @@ module RailsAuditLog
       class_attribute :_audit_log_retain_for,     default: nil
       class_attribute :_audit_log_async,          default: false
       class_attribute :_audit_log_encrypt,        default: nil
+      class_attribute :_audit_log_tenant,         default: nil
 
       _warn_if_audit_table_missing
 
@@ -119,18 +120,21 @@ module RailsAuditLog
       #   host app to configure +config.active_record.encryption+; decryption is
       #   transparent — {AuditLogEntry#diff}, {AuditLogEntry#reify}, and
       #   {AuditLogEntry.touching} work unchanged for non-SQL access paths
+      # @param tenant [Proc, nil] zero-argument lambda evaluated at write time;
+      #   return value is stored in the +tenant_id+ column; overrides
+      #   {RailsAuditLog.current_tenant} for this model
       # @return [void]
       # @example
       #   class Article < ApplicationRecord
       #     include RailsAuditLog::Auditable
       #     audit_log only: %i[title body published_at],
-      #               meta: { tenant_id: -> { Current.tenant_id } },
+      #               tenant: -> { Current.tenant_id },
       #               associations: %i[tags],
       #               version_limit: 100,
       #               retain_for: 30.days,
       #               encrypt: true
       #   end
-      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, retain_for: nil, async: nil, encrypt: nil)
+      def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, retain_for: nil, async: nil, encrypt: nil, tenant: 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
@@ -139,6 +143,7 @@ module RailsAuditLog
         self._audit_log_retain_for    = retain_for          unless retain_for.nil?
         self._audit_log_async         = async               unless async.nil?
         self._audit_log_encrypt       = encrypt             unless encrypt.nil?
+        self._audit_log_tenant        = tenant              unless tenant.nil?
       end
     end
 
@@ -183,6 +188,7 @@ module RailsAuditLog
         object:             nil,
         reason:             RailsAuditLog.reason,
         metadata:           meta.presence,
+        tenant_id:          resolve_tenant_id,
         whodunnit_snapshot: actor ? RailsAuditLog.whodunnit_display.call(actor) : nil,
         actor_type:         actor&.class&.name,
         actor_id:           actor.respond_to?(:id) ? actor.id : nil
@@ -205,6 +211,7 @@ module RailsAuditLog
         object:              maybe_encrypt(snapshot),
         reason:              RailsAuditLog.reason,
         metadata:            meta.presence,
+        tenant_id:           resolve_tenant_id,
         whodunnit_snapshot:  actor ? RailsAuditLog.whodunnit_display.call(actor) : nil,
         actor_type:          actor&.class&.name,
         actor_id:            actor.respond_to?(:id) ? actor.id : nil
@@ -227,8 +234,9 @@ module RailsAuditLog
         period = self.class._audit_log_retain_for || RailsAuditLog.retention_period
         WriteAuditLogJob.perform_later(entry_attrs.stringify_keys, version_limit: limit, retention_period: period)
       else
-        RailsAuditLog::AuditLogEntry.create!(entry_attrs)
+        entry = RailsAuditLog::AuditLogEntry.create!(entry_attrs)
         prune_audit_entries
+        RailsAuditLog.publish_entry(entry)
       end
     end
 
@@ -248,6 +256,11 @@ module RailsAuditLog
       end
     end
 
+    def resolve_tenant_id
+      tenant_proc = self.class._audit_log_tenant || RailsAuditLog.current_tenant
+      tenant_proc&.call
+    end
+
     def build_audit_metadata
       meta = {}
       if self.class._audit_log_meta

data/app/controllers/rails_audit_log/application_controller.rb

@@ -13,5 +13,10 @@ module RailsAuditLog
 
       instance_exec(self, &auth) || request_http_basic_authentication("Audit Log")
     end
+
+    def base_audit_scope
+      tenant_id = RailsAuditLog.current_tenant&.call
+      tenant_id ? AuditLogEntry.for_tenant(tenant_id) : AuditLogEntry.all
+    end
   end
 end

data/app/controllers/rails_audit_log/audit_log_entries_controller.rb

@@ -21,7 +21,7 @@ module RailsAuditLog
     end
 
     def filtered_scope
-      scope = AuditLogEntry.order(created_at: :desc)
+      scope = base_audit_scope.order(created_at: :desc)
       scope = scope.where(event: @event)                          if @event
       scope = scope.where(item_type: @item_type)                  if @item_type
       scope = scope.for_period(@period)                           if @period

data/app/controllers/rails_audit_log/resources_controller.rb

@@ -5,7 +5,7 @@ module RailsAuditLog
       @item_type = params[:item_type]
       @item_id   = params[:item_id]
       @pagy, @entries = pagy(
-        AuditLogEntry
+        base_audit_scope
           .where(item_type: @item_type, item_id: @item_id)
           .order(created_at: :asc)
       )

data/app/jobs/rails_audit_log/streaming/publish_entry_job.rb

@@ -0,0 +1,13 @@
+module RailsAuditLog
+  module Streaming
+    class PublishEntryJob < ApplicationJob
+      def perform(entry_attrs)
+        entry = AuditLogEntry.new(entry_attrs)
+        ActiveSupport::Notifications.instrument(
+          NotificationsAdapter::EVENT,
+          entry: entry
+        )
+      end
+    end
+  end
+end

data/app/jobs/rails_audit_log/write_audit_log_job.rb

@@ -1,7 +1,8 @@
 module RailsAuditLog
   class WriteAuditLogJob < ApplicationJob
     def perform(entry_attrs, version_limit: nil, retention_period: nil)
-      AuditLogEntry.create!(entry_attrs)
+      entry = AuditLogEntry.create!(entry_attrs)
+      RailsAuditLog.publish_entry(entry)
 
       item_type = entry_attrs["item_type"]
       item_id   = entry_attrs["item_id"]

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -91,6 +91,16 @@ module RailsAuditLog
       end
     }
 
+    # Entries belonging to a specific tenant.
+    # Composable with all other scopes.
+    #
+    # @param id [String, Integer] the tenant identifier stored in +tenant_id+
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.for_tenant("acme")
+    #   AuditLogEntry.for_tenant(Current.tenant_id).updated_events
+    scope :for_tenant, ->(id) { where(tenant_id: id) }
+
     # @!endgroup
 
     # @!group Time scopes

data/lib/generators/rails_audit_log/tenant/templates/add_tenant_id_to_audit_log_entries.rb

@@ -0,0 +1,6 @@
+class AddTenantIdToAuditLogEntries < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :audit_log_entries, :tenant_id, :string
+    add_index  :audit_log_entries, :tenant_id
+  end
+end

data/lib/generators/rails_audit_log/tenant/tenant_generator.rb

@@ -0,0 +1,33 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsAuditLog
+  module Generators
+    class TenantGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration that adds a tenant_id column and index to audit_log_entries."
+
+      def create_migration_file
+        migration_template(
+          "add_tenant_id_to_audit_log_entries.rb",
+          "db/migrate/add_tenant_id_to_audit_log_entries.rb"
+        )
+      end
+
+      def print_next_steps
+        say ""
+        say "Next steps:", :green
+        say "  1. Run `bin/rails db:migrate` to add the tenant_id column."
+        say "  2. Set a global resolver in your initializer:"
+        say "       RailsAuditLog.current_tenant { Current.tenant_id }"
+        say "     or per-model:"
+        say "       audit_log tenant: -> { Current.tenant_id }"
+        say "  3. Use AuditLogEntry.for_tenant(id) to scope queries to a tenant."
+        say ""
+      end
+    end
+  end
+end

data/lib/rails_audit_log/streaming/active_job_adapter.rb

@@ -0,0 +1,25 @@
+module RailsAuditLog
+  module Streaming
+    # Publishes each audit entry asynchronously by enqueuing
+    # {RailsAuditLog::Streaming::PublishEntryJob}. The job fires a
+    # +rails_audit_log.entry_created+ notification when performed, so subscribers
+    # receive the entry out-of-band without blocking the request.
+    #
+    # @example
+    #   RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::ActiveJobAdapter.new
+    #
+    #   # Custom queue:
+    #   RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::ActiveJobAdapter.new(queue: :streaming)
+    class ActiveJobAdapter
+      def initialize(queue: nil)
+        @queue = queue
+      end
+
+      def publish(entry)
+        job = RailsAuditLog::Streaming::PublishEntryJob
+        job = job.set(queue: @queue) if @queue
+        job.perform_later(entry.attributes.compact)
+      end
+    end
+  end
+end

data/lib/rails_audit_log/streaming/notifications_adapter.rb

@@ -0,0 +1,21 @@
+module RailsAuditLog
+  module Streaming
+    # Publishes each audit entry synchronously via +ActiveSupport::Notifications+.
+    # Zero external dependencies — subscribe with +ActiveSupport::Notifications.subscribe+.
+    #
+    # @example
+    #   RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::NotificationsAdapter.new
+    #
+    #   ActiveSupport::Notifications.subscribe("rails_audit_log.entry_created") do |*, payload|
+    #     entry = payload[:entry]
+    #     Rails.logger.info "Audit: #{entry.event} on #{entry.item_type}##{entry.item_id}"
+    #   end
+    class NotificationsAdapter
+      EVENT = "rails_audit_log.entry_created"
+
+      def publish(entry)
+        ActiveSupport::Notifications.instrument(EVENT, entry: entry)
+      end
+    end
+  end
+end

data/lib/rails_audit_log/version.rb

@@ -1,3 +1,3 @@
 module RailsAuditLog
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/rails_audit_log.rb

@@ -1,5 +1,7 @@
 require "rails_audit_log/version"
 require "rails_audit_log/engine"
+require "rails_audit_log/streaming/notifications_adapter"
+require "rails_audit_log/streaming/active_job_adapter"
 
 # RailsAuditLog is a Rails engine that tracks ActiveRecord +create+, +update+,
 # and +destroy+ events as {AuditLogEntry} records with JSON-first storage and
@@ -90,6 +92,15 @@ module RailsAuditLog
   # @return [Integer]
   mattr_accessor :page_size, default: 25
 
+  # The active streaming adapter. Any object implementing +#publish(entry)+.
+  # Called after every audit entry is persisted, including batch writes.
+  # Set to +nil+ (default) to disable streaming.
+  #
+  # @return [#publish, nil]
+  # @example
+  #   RailsAuditLog.streaming_adapter = RailsAuditLog::Streaming::NotificationsAdapter.new
+  mattr_accessor :streaming_adapter, default: nil
+
   # Controls how an actor object is serialised into the +whodunnit_snapshot+
   # string column. Defaults to +actor.name+ when available, otherwise +to_s+.
   #
@@ -114,6 +125,45 @@ module RailsAuditLog
     yield self
   end
 
+  # Sets or returns the global tenant resolver block. The block is called at
+  # write time and its return value is stored in the +tenant_id+ column of each
+  # {AuditLogEntry}. Override per-model with <tt>audit_log tenant: -> { ... }</tt>.
+  #
+  # @yield block called with no arguments at write time; return the tenant id
+  # @return [Proc, nil] the stored block, or +nil+ when not configured
+  # @example
+  #   RailsAuditLog.current_tenant { Current.tenant_id }
+  def self.current_tenant(&block)
+    @current_tenant = block if block_given?
+    @current_tenant
+  end
+
+  # Wires {.current_tenant} to +ActsAsTenant.current_tenant&.id+ so audit
+  # entries are automatically scoped to the Acts As Tenant context.
+  # Call once in an initializer after the gem is loaded.
+  #
+  # @raise [RuntimeError] if the +acts_as_tenant+ gem is not loaded
+  # @return [void]
+  # @example
+  #   RailsAuditLog.acts_as_tenant!
+  def self.acts_as_tenant!
+    unless defined?(ActsAsTenant)
+      raise "ActsAsTenant is not loaded. Add the `acts_as_tenant` gem to your Gemfile."
+    end
+
+    current_tenant { ActsAsTenant.current_tenant&.id }
+  end
+
+  # Passes +entry+ to the configured {.streaming_adapter} if one is set.
+  # No-ops when no adapter is configured.
+  #
+  # @api private
+  # @param entry [AuditLogEntry]
+  # @return [void]
+  def self.publish_entry(entry)
+    streaming_adapter&.publish(entry)
+  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.
@@ -244,7 +294,10 @@ module RailsAuditLog
     begin
       result = yield
       batch = Thread.current[:rails_audit_log_batch]
-      AuditLogEntry.insert_all!(batch) if batch.any?
+      if batch.any?
+        AuditLogEntry.insert_all!(batch)
+        batch.each { |attrs| publish_entry(AuditLogEntry.new(attrs)) } if streaming_adapter
+      end
       result
     ensure
       Thread.current[:rails_audit_log_batch] = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -99,6 +99,7 @@ files:
 - app/javascript/rails_audit_log/search_controller.js
 - app/jobs/rails_audit_log/application_job.rb
 - app/jobs/rails_audit_log/prune_audit_log_job.rb
+- app/jobs/rails_audit_log/streaming/publish_entry_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
@@ -118,11 +119,15 @@ files:
 - 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/generators/rails_audit_log/tenant/templates/add_tenant_id_to_audit_log_entries.rb
+- lib/generators/rails_audit_log/tenant/tenant_generator.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/streaming/active_job_adapter.rb
+- lib/rails_audit_log/streaming/notifications_adapter.rb
 - lib/rails_audit_log/test_helpers.rb
 - lib/rails_audit_log/version.rb
 - lib/tasks/rails_audit_log_tasks.rake