standard_audit 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae2015728333aa6f6549bf138de8c27017c78c23f0d930ab3df9cf73c99b14cf
-  data.tar.gz: 6e479ec25dcb88c2538a23efbec0796762b4274fd0baa2c5ad6707f57e90b65d
+  metadata.gz: 6dff9827071db99dfcb9dc184f3cc20d0bcfd208de8f5d41c86efff0f7e4c2be
+  data.tar.gz: 979f93e8ed8d293695337e453ade9926b553be7904617d7c61d653ef5997a3ea
 SHA512:
-  metadata.gz: d3ec930cf81109adf17c563d15dba60a0e82ab33bcb0cb6ce422009f5b157b8d1335c46da73269053ed3e09e8169bbada9c548409080871d6dd9e3c928b65ce8
-  data.tar.gz: 64906fb08b3d97c7e25626790c32fcf6eb08885cd4c0d5f7cf22a6acf9bd2516101f768fe90d93bfd3db4a3120f726b1e63eaa49036beffcf513d139f68d58f8
+  metadata.gz: 98bf60f4d4d40d46ff28d9203c8686a5c57765a86c4c3ef1db97c59d32b27e355ac7b585730cd69865e54cf8540109c87546259ea19e4afdfa9a3510b5b52e1f
+  data.tar.gz: dda3b2376d9afcd2a61808fc79025e246365302f7b097c17a801bf47cc6a8f3e26a3e11b411dc19b31f6ebac32dc44107e92582e02813a22476be2fa1eaca32a

data/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-29
+
+### Changed
+
+- CI and release workflows migrated to the shared `rarebit-one/.github` reusable workflows (`reusable-gem-ci.yml@v1`, `reusable-gem-release.yml@v1`); `.github/workflows/ci.yml` and `release.yml` are now thin shims.
+- The `standard_audit:install` generator is now idempotent. Re-running it skips the migration when a `*_create_audit_logs.rb` file already exists in `db/migrate/`, and skips the initializer when `config/initializers/standard_audit.rb` already exists. New flags: `--skip-migration`, `--skip-initializer`, and `--force` (overwrite the existing initializer; defaults to skip without an interactive prompt).
+
+### Removed
+
+- **BREAKING:** Removed `Configuration#use_preset` and the `lib/standard_audit/presets/` directory. The preset pattern (`config.use_preset(:standard_id)`) created a direct dependency from `standard_audit` on a specific publisher gem, which inverted the intended dependency direction — `standard_audit` should be a generic event consumer with no knowledge of any particular publisher. Host apps should subscribe to event patterns directly:
+  ```ruby
+  StandardAudit.configure do |c|
+    c.subscribe_to "standard_id.authentication.*"
+    c.subscribe_to "standard_id.session.created"
+    c.subscribe_to "standard_id.session.revoked"
+    c.subscribe_to "standard_id.session.expired"
+    c.subscribe_to "standard_id.account.*"
+  end
+  ```
+  Each publisher gem documents its event namespace.
+- **BREAKING:** Dropped support for Ruby < 4.0. `required_ruby_version` is now `>= 4.0`. Hosts must upgrade to Ruby 4.0+ before bundling this version. CI tests all four published 4.0.x patches.
+- **BREAKING:** Dropped support for Rails < 8.0. `activerecord`, `activejob`, and `activesupport` constraints are now `>= 8.0` (was `>= 7.1`). Hosts on Rails 7.x must upgrade to Rails 8.0+ before bundling this version. Aligns with the org-wide policy of supporting Rails 8 and up.
+
+## [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

@@ -23,6 +23,8 @@ This creates:
 - A migration for the `audit_logs` table (UUID primary keys, JSON metadata)
 - An initializer at `config/initializers/standard_audit.rb`
 
+The generator is idempotent — re-running it skips the migration when a `*_create_audit_logs.rb` already exists in `db/migrate/`, and skips the initializer when `config/initializers/standard_audit.rb` already exists. Pass `--skip-migration` or `--skip-initializer` to opt out of individual steps, or `--force` to overwrite the existing initializer.
+
 ## Quick Start
 
 ### 1. Subscribe to events
@@ -52,11 +54,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 +100,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/generators/standard_audit/install/install_generator.rb

@@ -1,19 +1,85 @@
+require "rails/generators"
+
 module StandardAudit
   module Generators
+    # Installs StandardAudit in a host Rails application.
+    #
+    # Creates the migration for the `audit_logs` table and writes the
+    # initializer at `config/initializers/standard_audit.rb`.
+    #
+    # Idempotent: re-running the generator will skip pieces it has already
+    # installed. Pass `--skip-*` flags to opt out of individual steps and
+    # `--force` to overwrite an existing initializer.
     class InstallGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
       source_root File.expand_path("templates", __dir__)
 
+      desc <<~DESC
+        Installs StandardAudit. By default this:
+          * copies a CreateAuditLogs migration into db/migrate/
+          * writes config/initializers/standard_audit.rb
+
+        Use --skip-* flags to opt out of individual steps when re-running on an
+        existing install. The generator is idempotent — already-installed
+        pieces are skipped with a clear message. Pass --force to overwrite an
+        existing initializer.
+      DESC
+
+      class_option :skip_migration, type: :boolean, default: false,
+        desc: "Do not copy the CreateAuditLogs migration into db/migrate"
+      class_option :skip_initializer, type: :boolean, default: false,
+        desc: "Do not write config/initializers/standard_audit.rb"
+      class_option :force, type: :boolean, default: false,
+        desc: "Overwrite config/initializers/standard_audit.rb if it already exists"
+
       def self.next_migration_number(dirname)
         Time.now.utc.strftime("%Y%m%d%H%M%S")
       end
 
       def copy_migration
+        if options[:skip_migration]
+          say_status("skip", "db/migrate/*_create_audit_logs.rb (--skip-migration)", :yellow)
+          return
+        end
+
+        if existing_migration
+          say_status(
+            "identical",
+            "AuditLog migration already present (#{relative_migration_path(existing_migration)}), skipping",
+            :blue
+          )
+          return
+        end
+
         migration_template "create_audit_logs.rb.erb", "db/migrate/create_audit_logs.rb"
       end
 
       def copy_initializer
-        template "initializer.rb.erb", "config/initializers/standard_audit.rb"
+        initializer_path = "config/initializers/standard_audit.rb"
+
+        if options[:skip_initializer]
+          say_status("skip", "#{initializer_path} (--skip-initializer)", :yellow)
+          return
+        end
+
+        if File.exist?(File.join(destination_root, initializer_path)) && !options[:force]
+          say_status("identical", "#{initializer_path} (already exists; pass --force to overwrite)", :blue)
+          return
+        end
+
+        template "initializer.rb.erb", initializer_path, force: options[:force]
+      end
+
+      no_commands do
+        def existing_migration
+          Dir.glob(File.join(destination_root, "db/migrate/*_create_audit_logs.rb")).first
+        end
+
+        def relative_migration_path(absolute_path)
+          Pathname.new(absolute_path).relative_path_from(Pathname.new(destination_root)).to_s
+        rescue ArgumentError
+          absolute_path
+        end
       end
     end
   end

data/lib/generators/standard_audit/install/templates/initializer.rb.erb

@@ -1,8 +1,11 @@
 StandardAudit.configure do |config|
-  # Use a preset to subscribe to common event patterns
-  # config.use_preset(:standard_id)
-
-  # Or subscribe to ActiveSupport::Notifications patterns manually
+  # Subscribe to ActiveSupport::Notifications / Rails.event patterns.
+  # Each gem documents its own event namespace; subscribe to whichever
+  # patterns you want audited:
+  # config.subscribe_to "standard_id.authentication.*"
+  # config.subscribe_to "standard_id.session.created"
+  # config.subscribe_to "standard_id.session.revoked"
+  # config.subscribe_to "standard_circuit.circuit.*"
   # config.subscribe_to "audit.**"
 
   # Actor extractor from notification payload

data/lib/standard_audit/configuration.rb

@@ -10,7 +10,6 @@ module StandardAudit
 
     def initialize
       @subscriptions = []
-      @applied_presets = []
       @async = false
       @queue_name = :default
       @enabled = true
@@ -56,22 +55,5 @@ module StandardAudit
     def subscriptions
       @subscriptions.dup.freeze
     end
-
-    def use_preset(name)
-      key = name.to_sym
-      return self if @applied_presets.include?(key)
-
-      preset = case key
-      when :standard_id
-        require "standard_audit/presets/standard_id"
-        StandardAudit::Presets::StandardId
-      else
-        raise ArgumentError, "Unknown preset: #{name}. Available presets: :standard_id"
-      end
-
-      preset.apply(self)
-      @applied_presets << key
-      self
-    end
   end
 end

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

@@ -0,0 +1,29 @@
+require "standard_audit"
+
+# StandardAudit state reset between examples.
+#
+# - Clears the thread-local batch buffer so a spec that exits inside a
+#   `StandardAudit.batch { ... }` block (e.g. via an unhandled error or
+#   abort) cannot leak buffered records into the next example.
+# - Resets the Configuration via `StandardAudit.reset_configuration!` so
+#   that mutations to `StandardAudit.config` (subscriptions, sensitive
+#   keys, async flag, custom resolvers, etc.) do not bleed across specs.
+#   Consumers that customise configuration must re-call
+#   `StandardAudit.configure { |c| ... }` from a `before` hook in their
+#   own suite if they need a non-default baseline.
+#
+# The memoized `Subscriber` and `EventSubscriber` instances are *not*
+# torn down here — they are wired up at engine boot via initializers and
+# rebuilding them per-example would unsubscribe from
+# `ActiveSupport::Notifications` / `Rails.event` for the rest of the run.
+# Specs that need to assert on subscriber behaviour should manage that
+# locally.
+#
+# Intentionally `before(:example)` rather than `after(:example)` so the
+# reset always runs even when a previous example aborted in an after hook.
+RSpec.configure do |config|
+  config.before(:example) do
+    Thread.current[:standard_audit_batch] = nil
+    StandardAudit.reset_configuration!
+  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.5.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.5.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,42 +15,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: globalid
   requirement: !ruby/object:Gem::Requirement
@@ -65,8 +65,23 @@ 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.
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: StandardAudit is a standalone Rails gem for database-backed audit logging.
+  On Rails 8.1+ it subscribes to Rails.event; on Rails 8.0 it falls back to ActiveSupport::Notifications.
+  Generic, flexible, and works with any Rails application.
 email:
 - code@jaryl.dev
 executables: []
@@ -92,7 +107,8 @@ files:
 - lib/standard_audit/auditable.rb
 - lib/standard_audit/configuration.rb
 - lib/standard_audit/engine.rb
-- lib/standard_audit/presets/standard_id.rb
+- lib/standard_audit/event_subscriber.rb
+- lib/standard_audit/rspec.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb
 - lib/tasks/standard_audit_tasks.rake
@@ -111,7 +127,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -120,5 +136,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: []

data/lib/standard_audit/presets/standard_id.rb

@@ -1,22 +0,0 @@
-module StandardAudit
-  module Presets
-    module StandardId
-      # Regex wildcards capture all events in a namespace. Session uses
-      # explicit strings to exclude noisy events like session.validated
-      # that fire on every authenticated request.
-      SUBSCRIPTIONS = [
-        /\Astandard_id\.authentication\./,
-        "standard_id.session.created",
-        "standard_id.session.revoked",
-        "standard_id.session.expired",
-        /\Astandard_id\.account\./,
-        /\Astandard_id\.social\./,
-        /\Astandard_id\.passwordless\./
-      ].freeze
-
-      def self.apply(config)
-        SUBSCRIPTIONS.each { |pattern| config.subscribe_to(pattern) }
-      end
-    end
-  end
-end