standard_audit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae2015728333aa6f6549bf138de8c27017c78c23f0d930ab3df9cf73c99b14cf
-  data.tar.gz: 6e479ec25dcb88c2538a23efbec0796762b4274fd0baa2c5ad6707f57e90b65d
+  metadata.gz: 6a9a29ab9754c6dbc24134d000864e8d99f60966227691ee782b782423ac7dc7
+  data.tar.gz: 0ee9864f7b073c3376041facfafe575006179b443937883377a5bdda605bc81a
 SHA512:
-  metadata.gz: d3ec930cf81109adf17c563d15dba60a0e82ab33bcb0cb6ce422009f5b157b8d1335c46da73269053ed3e09e8169bbada9c548409080871d6dd9e3c928b65ce8
-  data.tar.gz: 64906fb08b3d97c7e25626790c32fcf6eb08885cd4c0d5f7cf22a6acf9bd2516101f768fe90d93bfd3db4a3120f726b1e63eaa49036beffcf513d139f68d58f8
+  metadata.gz: e156d464655ca40f791b064e264b18ac587b63819f454d8bc98b9b7a9168cbd02519795c14d0333cd148be191715d29498244d1218f505365a1ef669c6f591fe
+  data.tar.gz: 2816bb0d249b20d8464cde9655b5799d8b7525cba615b9a97528bd9ef78ca1b1254fd528bca77ac3390001bdf34adc384add86c5b924d43a2e93bf695620ae89

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-19
+
+### Added
+
+- Rails 8.1+ structured event reporter (`Rails.event`) integration. A new `StandardAudit::EventSubscriber` is registered automatically when `Rails.event` is available, so `Rails.event.notify("myapp.orders.created", actor: user, target: order)` persists an `AuditLog` the same way an `ActiveSupport::Notifications.instrument` call does. Event name is matched against the existing `subscribe_to` patterns (supports `*`, `**`, and `Regexp`). `Rails.event.set_context(...)` values take precedence over the `Current.*` resolvers for `request_id`, `ip_address`, `user_agent`, and `session_id`. `Rails.event.tagged(...)` and `source_location` are captured under the reserved metadata keys `_tags` and `_source`.
+
 ## [0.3.0] - 2026-03-31
 
 ### Added

data/README.md

@@ -52,11 +52,38 @@ StandardAudit::AuditLog.for_actor(current_user).this_week
 
 ## Recording Events
 
-StandardAudit provides three ways to record audit events.
+StandardAudit provides four ways to record audit events. On Rails 8.1+, prefer `Rails.event` — it is the standard Rails interface for structured events.
+
+### Rails.event (Rails 8.1+)
+
+StandardAudit registers a `Rails.event` subscriber at boot, so any `notify` call whose name matches a configured `subscribe_to` pattern is persisted automatically:
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action do
+    Rails.event.set_context(
+      request_id: request.request_id,
+      ip_address: request.remote_ip,
+      user_agent: request.user_agent
+    )
+  end
+end
+
+Rails.event.tagged("checkout") do
+  Rails.event.notify("myapp.orders.created",
+    actor: current_user,
+    target: @order,
+    scope: current_organisation,
+    total: @order.total
+  )
+end
+```
+
+`Rails.event.set_context` values override the `Current.*` resolvers for `request_id`, `ip_address`, `user_agent`, and `session_id`. Tags and `source_location` are captured as metadata under the reserved keys `_tags` and `_source`.
 
 ### Convenience API
 
-The simplest approach — call `StandardAudit.record` directly:
+Call `StandardAudit.record` directly:
 
 ```ruby
 StandardAudit.record("orders.created",
@@ -71,7 +98,7 @@ When `actor` is omitted, it falls back to the configured `current_actor_resolver
 
 ### ActiveSupport::Notifications
 
-Instrument events and let the subscriber handle persistence:
+For Rails < 8.1, or when `Rails.event` is unavailable, instrument events via `ActiveSupport::Notifications`:
 
 ```ruby
 ActiveSupport::Notifications.instrument("myapp.orders.created", {

data/lib/standard_audit/engine.rb

@@ -5,6 +5,12 @@ module StandardAudit
     initializer "standard_audit.subscriber" do
       ActiveSupport.on_load(:active_record) do
         StandardAudit.subscriber.setup!
+
+        # Rails 8.1+ structured event reporter. Feature-detected so the gem
+        # still works on older Rails versions that only have AS::Notifications.
+        if Rails.respond_to?(:event) && Rails.event.respond_to?(:subscribe)
+          Rails.event.subscribe(StandardAudit.event_subscriber)
+        end
       end
     end
   end

data/lib/standard_audit/event_subscriber.rb

@@ -0,0 +1,101 @@
+module StandardAudit
+  # Subscriber for Rails 8.1+ structured event reporting (`Rails.event`).
+  #
+  # Registered with `Rails.event.subscribe(...)` so that every `Rails.event.notify`
+  # call flows through StandardAudit for persistence. Events whose name does not
+  # match any configured `subscribe_to` pattern are ignored.
+  #
+  # Payload is extracted with the same extractors used by the
+  # ActiveSupport::Notifications subscriber. Rails.event `context` supplies
+  # request_id/ip_address/user_agent/session_id and takes precedence over the
+  # Current.* resolvers. Tags and source_location are captured as metadata
+  # under the reserved keys `_tags` and `_source`.
+  class EventSubscriber
+    RESERVED_PAYLOAD_KEYS = %i[actor target scope request_id ip_address user_agent session_id].freeze
+
+    def initialize
+      @pattern_cache = {}
+      @pattern_cache_mutex = Mutex.new
+    end
+
+    def emit(event)
+      return unless StandardAudit.config.enabled
+
+      name = event[:name]
+      return if name.nil?
+      return unless matches_subscription?(name)
+
+      config  = StandardAudit.config
+      payload = event[:payload] || {}
+      context = event[:context] || {}
+
+      actor  = config.actor_extractor.call(payload)
+      target = config.target_extractor.call(payload)
+      scope  = config.scope_extractor.call(payload)
+
+      metadata = build_metadata(payload, event[:tags], event[:source_location], config)
+
+      StandardAudit.record(
+        name,
+        actor: actor,
+        target: target,
+        scope: scope,
+        metadata: metadata,
+        request_id: context[:request_id] || payload[:request_id],
+        ip_address: context[:ip_address] || payload[:ip_address],
+        user_agent: context[:user_agent] || payload[:user_agent],
+        session_id: context[:session_id] || payload[:session_id]
+      )
+    rescue => e
+      Rails.logger.error("[StandardAudit] Error handling Rails.event: #{e.class}: #{e.message}")
+    end
+
+    private
+
+    def matches_subscription?(name)
+      StandardAudit.config.subscriptions.any? { |pattern| pattern_match?(pattern, name) }
+    end
+
+    # Supports the same pattern shapes as ActiveSupport::Notifications.subscribe:
+    # a Regexp, or a String with `*` matching a single segment and `**` matching
+    # the remainder.
+    def pattern_match?(pattern, name)
+      case pattern
+      when Regexp
+        pattern.match?(name)
+      when String
+        compiled_pattern_for(pattern).match?(name)
+      else
+        false
+      end
+    end
+
+    def compiled_pattern_for(pattern)
+      cached = @pattern_cache[pattern]
+      return cached if cached
+
+      @pattern_cache_mutex.synchronize do
+        @pattern_cache[pattern] ||= Regexp.new(
+          "\\A" + Regexp.escape(pattern).gsub('\\*\\*', ".*").gsub('\\*', "[^.]*") + "\\z"
+        )
+      end
+    end
+
+    # `_tags` and `_source` are reserved metadata keys owned by this
+    # subscriber. Sensitive-key filtering is handled downstream by
+    # `StandardAudit.record`, so we don't re-run it here.
+    def build_metadata(payload, tags, source_location, config)
+      reserved = RESERVED_PAYLOAD_KEYS.map(&:to_s)
+      raw = payload.reject { |k, _| reserved.include?(k.to_s) }
+      raw = config.metadata_builder.call(raw) if config.metadata_builder
+
+      if tags.is_a?(Hash) && tags.any?
+        raw[:_tags] = tags
+      elsif tags && !tags.is_a?(Hash)
+        Rails.logger.warn("[StandardAudit] Dropping Rails.event tags of unexpected type: #{tags.class}")
+      end
+      raw[:_source] = source_location if source_location
+      raw
+    end
+  end
+end

data/lib/standard_audit/subscriber.rb

@@ -67,7 +67,7 @@ module StandardAudit
         log.save!
       end
     rescue => e
-      Rails.logger.error("[StandardAudit] Error creating audit log: #{e.message}")
+      Rails.logger.error("[StandardAudit] Error creating audit log: #{e.class}: #{e.message}")
     end
 
     def extract_metadata(payload, config)

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/standard_audit.rb

@@ -2,10 +2,15 @@ require "standard_audit/version"
 require "standard_audit/engine"
 require "standard_audit/configuration"
 require "standard_audit/subscriber"
+require "standard_audit/event_subscriber"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
 
 module StandardAudit
+  # Metadata keys owned internally by StandardAudit. Never filtered by
+  # `sensitive_keys` even if a user adds them there.
+  RESERVED_METADATA_KEYS = %w[_tags _source].freeze
+
   class << self
     def configure
       yield(config) if block_given?
@@ -20,8 +25,9 @@ module StandardAudit
 
       actor ||= config.current_actor_resolver.call
 
-      # Filter sensitive keys
-      sensitive = config.sensitive_keys.map(&:to_s)
+      # Filter sensitive keys. `_tags` and `_source` are reserved internal
+      # metadata keys owned by EventSubscriber and are never stripped.
+      sensitive = config.sensitive_keys.map(&:to_s) - RESERVED_METADATA_KEYS
       filtered_metadata = metadata.reject { |k, _| sensitive.include?(k.to_s) }
 
       attrs = {
@@ -90,6 +96,10 @@ module StandardAudit
       @subscriber ||= Subscriber.new
     end
 
+    def event_subscriber
+      @event_subscriber ||= EventSubscriber.new
+    end
+
     def reset_configuration!
       @configuration = nil
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -65,8 +65,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-description: StandardAudit is a standalone Rails gem for database-backed audit logging
-  via ActiveSupport::Notifications. Generic, flexible, and works with any Rails application.
+description: StandardAudit is a standalone Rails gem for database-backed audit logging.
+  On Rails 8.1+ it subscribes to Rails.event; on earlier versions it subscribes to
+  ActiveSupport::Notifications. Generic, flexible, and works with any Rails application.
 email:
 - code@jaryl.dev
 executables: []
@@ -92,6 +93,7 @@ files:
 - lib/standard_audit/auditable.rb
 - lib/standard_audit/configuration.rb
 - lib/standard_audit/engine.rb
+- lib/standard_audit/event_subscriber.rb
 - lib/standard_audit/presets/standard_id.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb
@@ -120,5 +122,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Database-backed audit logging for Rails via ActiveSupport::Notifications.
+summary: Database-backed audit logging for Rails via Rails.event and ActiveSupport::Notifications.
 test_files: []