standard_audit 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80719c54fd8a1d3859f52741cfc4a478ec670114ad5ab025b1b9b14a10a80625
-  data.tar.gz: d5baa91d4e29844e0e0c375e0ef6c9b3cd4f2d6eba0284696911891270f3befa
+  metadata.gz: a6da3bdedaecde5d44a57afe47372bf419b9290ace08a2312d1c522df5a67561
+  data.tar.gz: 283e8c2839ddce46fa2ec6468423c75380256f51f05a0a52844763d5454b7da3
 SHA512:
-  metadata.gz: 3fc6d5267408dd0858b0cecac9e449c00b6ef6e75b12cb9cb74167634769cd09f95fa51805a948f9a20e100b7bbd43237f473f4508d211a8c66293c0af2bbe3f
-  data.tar.gz: cdb5c7130f54d124da4e2b02586e510b5a75693c729d30d495403d4e948b7d6fcc81b640cb241a138292d452ebb5a52f0d84a6a0f178e8ecb982d7a209c179ea
+  metadata.gz: 96cd2995bbaaab665bc485770604f37b0b4188cf052a30639b804882a70cc276fad7e10b7ee21c65fa0294018687e06cea921ae7e387f4666a3f7298d29bbd09
+  data.tar.gz: 810d2becd35d3e0a5325786b86415c48318b4c23d7c8df46742916053cff6eaf5f97e3cba1e94b8ab479437751ba94177c28b05bc4c12837208a975698788aa0

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-09-24
+
+### Upgrade steps
+
+1. **If you installed the 0.12.0 `add_anonymized_at` migration, check your copy.** The 0.12.0 template put `return if column_exists?(:audit_logs, :anonymized_at)` inside `change`. That early return also runs on rollback, so `db:rollback` deleted the `schema_migrations` row and silently left the column in place. Replace the body with `add_column :audit_logs, :anonymized_at, :datetime, if_not_exists: true` (in `change`), or copy the new up/down template. Nothing to do if your copy already uses `if_not_exists:` (sidekick-web, jumpdrive-web) or if you never ran the generator.
+2. If an error-tracker search or alert matches `before_checksum` hook failures on the `audit_event` context key, see Fixed.
+
+### Fixed
+
+- **The `add_anonymized_at` migration is reversible.** The template now uses explicit `up` / `down` with `add_column ..., if_not_exists: true` and `remove_column ..., if_exists: true`. It is still idempotent, and rollback now removes the column. A new generator spec runs the generated migration up, down and up.
+- **`before_checksum` hook failures use `config.audit_error_context_key`.** The hook's `Rails.error.report` hard-coded `audit_event:` as its context key. Every other audit-error report site uses the configured key (default `:audit_action`). Apps that set `audit_error_context_key = :audit_event` see no change. Apps on the default now get `audit_action:` for hook failures too, matching every other audit error.
+
+### Documentation
+
+- `current_scope_resolver` is for scope derived from `Current`. Scope derived from the row (e.g. the target's organisation) belongs in a `before_checksum` or `before_write` hook. The README no longer describes sidekick-web's target-derived hook as a `Current` back-fill.
+- New note: `before_write` / `before_checksum` run once per row, batched writes included. Memoize per-actor lookups (e.g. in a `CurrentAttributes` cache) to avoid an N+1 on a batch flush.
+- `record(raise: false)` reports through `Rails.error`, so failures reach Sentry only if a `Rails.error` subscriber is registered (`sentry-rails` registers one).
+
 ## [0.12.0] - 2026-09-24
 
 ### Upgrade steps

data/README.md

@@ -116,6 +116,12 @@ StandardAudit.record("auth.token_invalid",
 The default is `raise: true` (unchanged). In block form the option only
 governs the audit write; errors from your block always propagate.
 
+`raise: false` does not talk to Sentry (or any other tracker) itself. It calls
+`Rails.error.report`, so a swallowed failure reaches your error tracker only if
+something subscribes to `Rails.error`. `sentry-rails` registers that subscriber
+for you. With a hand-rolled Sentry setup, register one
+(`Rails.error.subscribe(...)`), or these failures show up only in the log.
+
 **Replace your host code with** `raise: false`. It supersedes the
 `AuditAuthFailure#record_auth_failure` rescue-and-report wrapper
 (sidekick-web, luminality-web, nutripod-web
@@ -179,6 +185,27 @@ dereferencing and `sensitive_keys` redaction, so anything it injects is still
 filtered. Mutate `entry` in place; the return value is ignored. Raising aborts
 the write: direct callers see the error, the subscribers rescue and report it.
 
+**Hooks run once per row, batched writes included.** `before_write` and
+`before_checksum` run for every row inside `StandardAudit.batch` too (at flush
+time for `before_checksum`). A hook that looks something up per actor (a role,
+a membership, a tenant) therefore runs one query per row and turns a batch into
+an N+1. Memoize those lookups for the unit of work, for example in a
+`CurrentAttributes` cache that resets with the request or job:
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :audit_actor_roles
+
+  def self.audit_role_for(actor)
+    self.audit_actor_roles ||= {}
+    audit_actor_roles[actor.to_global_id.to_s] ||= actor.audit_role
+  end
+end
+
+# actor_role: a column your app added to audit_logs
+config.before_checksum { |log| log.actor_role = Current.audit_role_for(log.actor) if log.actor }
+```
+
 **Replace your host code with** a `before_write`. It supersedes:
 
 - a hand-built job-side wrapper that runs a guard before `StandardAudit.record`
@@ -641,14 +668,25 @@ It is a *fallback*: an explicit `scope:` and a scope found by `scope_extractor`
 always win. It applies on every write path (direct `record`, `audit!`,
 `record_audit`, both subscribers; sync, async and batched). Default `nil`.
 
-**Replace your host code with** the one line above. It supersedes:
+`current_scope_resolver` is for scope that comes from **ambient request
+state** (`Current`). It takes no arguments and never sees the row. Scope that
+derives from the **row itself**, such as the organisation that owns the
+target, belongs in a `before_checksum` hook (or `before_write`), which receives
+the record or entry:
+
+```ruby
+config.before_checksum do |log|
+  log.scope ||= log.target.organisation if log.target.respond_to?(:organisation)
+end
+```
 
-- a `scope_extractor` that falls back to `Current` (nutripod-web:
-  `->(payload) { payload[:scope] || Current.channel || Current.organisation }`),
-  which only ever covered the subscriber path — keep `scope_extractor` for
-  reading the payload, move the `Current` fallback here;
-- a `before_checksum` hook that back-fills `log.scope` from `Current`
-  (sidekick-web), which before 0.12.0 never ran on the batched path.
+**Replace your host code with** the one line above when your fallback reads
+`Current`. It supersedes a `scope_extractor` that falls back to `Current`
+(nutripod-web:
+`->(payload) { payload[:scope] || Current.channel || Current.organisation }`),
+which only ever covered the subscriber path. Keep `scope_extractor` for reading
+the payload and move the `Current` fallback here. Target-derived scope hooks
+stay as they are; since 0.12.0 they also run on the batched path.
 
 ## Async Processing
 

data/app/models/standard_audit/audit_log.rb

@@ -597,7 +597,13 @@ module StandardAudit
         # persist — so the hook would not actually be "skipped".
         restore_attributes_from(snapshot)
         Rails.logger.warn("[StandardAudit] before_checksum hook failed: #{e.class}: #{e.message}")
-        Rails.error.report(e, handled: true, context: { audit_event: event_type }) if Rails.respond_to?(:error)
+        if Rails.respond_to?(:error) && Rails.error
+          Rails.error.report(
+            e,
+            handled: true,
+            context: { StandardAudit.config.audit_error_context_key => event_type }
+          )
+        end
         nil
       end
     end

data/lib/generators/standard_audit/add_anonymized_at/templates/add_anonymized_at_to_audit_logs.rb.erb

@@ -1,15 +1,25 @@
 class AddAnonymizedAtToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    # A nullable column with no default: a metadata-only change on PostgreSQL,
-    # no table rewrite, nothing for StrongMigrations to object to. Idempotent,
-    # so it is safe on a host that already has the column (a 0.12+ install).
-    #
-    # Rows anonymized BEFORE this migration keep a NULL stamp and still fail
-    # `verify_chain` as `digest_mismatch`; there is no way to tell them apart
-    # from tampered rows after the fact. If your erasure records identify them,
-    # stamp them by hand (`update_columns(anonymized_at: ...)`).
-    return if column_exists?(:audit_logs, :anonymized_at)
+  # A nullable column with no default: a metadata-only change on PostgreSQL,
+  # no table rewrite, nothing for StrongMigrations to object to. Idempotent,
+  # so it is safe on a host that already has the column (a 0.12+ install).
+  #
+  # Rows anonymized BEFORE this migration keep a NULL stamp and still fail
+  # `verify_chain` as `digest_mismatch`; there is no way to tell them apart
+  # from tampered rows after the fact. If your erasure records identify them,
+  # stamp them by hand (`update_columns(anonymized_at: ...)`).
+  #
+  # Explicit up/down with `if_not_exists:` / `if_exists:` rather than an early
+  # `return if column_exists?` inside `change`: that return also runs on
+  # rollback, which then deletes the schema_migrations row and silently leaves
+  # the column behind.
+  #
+  # Rolling back drops the column even if it came from your create_audit_logs
+  # migration (0.12+ installs). Those installs do not need this migration.
+  def up
+    add_column :audit_logs, :anonymized_at, :datetime, if_not_exists: true
+  end
 
-    add_column :audit_logs, :anonymized_at, :datetime
+  def down
+    remove_column :audit_logs, :anonymized_at, if_exists: true
   end
 end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.12.0"
+  VERSION = "0.12.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Jaryl Sim