standard_audit 0.11.0 → 0.12.0

data/lib/standard_audit.rb

@@ -48,71 +48,92 @@ module StandardAudit
       @configuration ||= Configuration.new
     end
 
-    def record(event_type, actor: nil, target: nil, scope: nil, metadata: {}, **options)
+    # Writes one audit row. Every write path in the gem ends here — direct
+    # calls, `Auditable#record_audit`, `Operation#audit!`, and both event
+    # subscribers — so actor/scope resolution, `metadata_builder`,
+    # `before_write`, redaction, batching and async all apply uniformly.
+    #
+    # Block form instruments `event_type` via ActiveSupport::Notifications
+    # around the block and lets the Subscriber write the row (which lands back
+    # here), so it records only when the event is subscribed to.
+    #
+    # `raise: false` makes a failed write non-fatal: the error is logged and
+    # reported to `Rails.error` as handled, and nil is returned. For call
+    # sites where a missing audit row must never break the request (auth
+    # failure logging, say). It governs only the audit write — in block form
+    # the subscriber already rescues, and the block's own errors always
+    # propagate.
+    def record(event_type, actor: nil, target: nil, scope: nil, metadata: {}, **options, &block)
+      raise_errors = options.key?(:raise) ? options.delete(:raise) : true
       return unless config.enabled
 
-      actor ||= config.current_actor_resolver.call
-
-      if block_given?
-        # Block form: instrument via ActiveSupport::Notifications and let the
-        # Subscriber write the row, which it does with its own dereferencing and
-        # filtering. Nothing built below would be used, so it is not built —
-        # dereferencing a Relation here would load it eagerly, before the block
-        # has run, purely to discard the result.
+      if block
+        actor ||= config.current_actor_resolver.call
+        # Nothing is built here: the Subscriber writes the row through
+        # `write_entry`. Dereferencing a Relation now would load it eagerly,
+        # before the block has run, purely to discard the result.
         ActiveSupport::Notifications.instrument(event_type, metadata.merge(
           actor: actor, target: target, scope: scope
-        )) do
-          yield
-        end
+        ), &block)
         return
       end
 
-      # Redaction lives in MetadataFilter, shared with Subscriber, so the two
-      # write paths cannot drift apart. Record dereferencing is applied on both
-      # paths for the same reason: a snapshot of a whole row is as unrecoverable
-      # here as it is on the notifications path.
-      dereferenced = config.dereference_record_metadata ? RecordReference.call(metadata) : metadata
-      filtered_metadata = MetadataFilter.call(dereferenced, config: config)
+      begin
+        write_entry(event_type, actor: actor, target: target, scope: scope,
+          metadata: metadata, context: options)
+      rescue => e
+        raise if raise_errors
 
-      attrs = {
+        report_write_error(e, event_type, source: "StandardAudit.record")
+        nil
+      end
+    end
+
+    # @api private — the single write path shared by `record` and the two
+    # subscribers. Hosts call `record`.
+    #
+    # `context` carries explicit request_id/ip_address/user_agent/session_id
+    # values; nil entries fall back to the Current resolvers. `reserved` is
+    # merged into metadata AFTER `metadata_builder` (the Rails.event subscriber
+    # uses it for `_tags` / `_source`, which a builder never saw before 0.12).
+    def write_entry(event_type, actor:, target:, scope:, metadata:, context: {}, reserved: {})
+      actor ||= config.current_actor_resolver.call
+      scope ||= config.current_scope_resolver&.call
+
+      metadata = (metadata || {}).dup
+      metadata = config.metadata_builder.call(metadata) if config.metadata_builder
+      metadata = metadata.merge(reserved) if reserved.present?
+
+      entry = {
         event_type: event_type,
-        occurred_at: Time.current,
-        request_id: options[:request_id] || config.current_request_id_resolver.call,
-        ip_address: options[:ip_address] || config.current_ip_address_resolver.call,
-        user_agent: options[:user_agent] || config.current_user_agent_resolver.call,
-        session_id: options[:session_id] || config.current_session_id_resolver.call,
-        metadata: filtered_metadata
+        actor: actor,
+        target: target,
+        scope: scope,
+        metadata: metadata,
+        request_id: context[:request_id] || config.current_request_id_resolver.call,
+        ip_address: context[:ip_address] || config.current_ip_address_resolver.call,
+        user_agent: context[:user_agent] || config.current_user_agent_resolver.call,
+        session_id: context[:session_id] || config.current_session_id_resolver.call
       }
 
-      gid_attrs = {
-        actor_gid: actor&.to_global_id&.to_s,
-        actor_type: actor&.class&.name,
-        target_gid: target&.to_global_id&.to_s,
-        target_type: target&.class&.name,
-        scope_gid: scope&.to_global_id&.to_s,
-        scope_type: scope&.class&.name
-      }
+      # Runs on EVERY path, before redaction, so anything it injects into
+      # metadata is still subject to `sensitive_keys` and dereferencing. It may
+      # mutate `entry` in place; its return value is ignored. It may raise —
+      # that is how a host guard rejects a write — and the error propagates
+      # exactly as a failed save would.
+      config.before_write&.call(entry)
 
-      if batching?
-        Thread.current[:standard_audit_batch] << attrs.merge(gid_attrs)
-        nil
-      elsif config.async
-        StandardAudit::CreateAuditLogJob.perform_later(attrs.merge(gid_attrs).stringify_keys)
-      else
-        log = StandardAudit::AuditLog.new(attrs)
-        log.actor = actor
-        log.target = target
-        log.scope = scope
-        log.save!
-        log
-      end
+      persist(entry)
     end
 
     # Buffers record calls and flushes them via insert_all! on block exit.
     # If the block raises, buffered records are dropped — only successful
     # batches are persisted. Nested batches flush independently.
-    # Block-form record calls (with AS::Notifications) bypass the buffer
-    # and are processed normally since they don't persist records directly.
+    # Every write path buffers here, including events delivered by the
+    # ActiveSupport::Notifications and Rails.event subscribers (the former
+    # bypassed the buffer before 0.12.0). `before_write` runs before buffering,
+    # and `before_checksum` hooks run at flush time, before each row's checksum
+    # is computed — the same pipeline as a non-batched write.
     # Note: uses Thread.current for storage, which is not fiber-safe.
     # Apps using async adapters (Falcon) should avoid concurrent batches.
     def batch
@@ -126,6 +147,22 @@ module StandardAudit
       Thread.current[:standard_audit_batch] = previous
     end
 
+    # @api private — logs a failed audit write and reports it to Rails.error
+    # as handled. Used by the subscribers, which must never let an audit
+    # failure break the instrumented code path.
+    def report_write_error(error, event_type, **context)
+      Rails.logger.error("[StandardAudit] Error creating audit log for #{event_type}: #{error.class}: #{error.message}")
+      return unless Rails.respond_to?(:error) && Rails.error
+
+      Rails.error.report(
+        error,
+        handled: true,
+        context: { config.audit_error_context_key => event_type, **context }
+      )
+    rescue => report_failure
+      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
+    end
+
     def subscriber
       @subscriber ||= Subscriber.new
     end
@@ -156,6 +193,51 @@ module StandardAudit
 
     private
 
+    def persist(entry)
+      actor = entry[:actor]
+      target = entry[:target]
+      scope = entry[:scope]
+
+      # Redaction lives in MetadataFilter and record dereferencing in
+      # RecordReference; both run here, once, for every write path.
+      metadata = entry[:metadata] || {}
+      metadata = RecordReference.call(metadata) if config.dereference_record_metadata
+      metadata = MetadataFilter.call(metadata, config: config)
+
+      attrs = {
+        event_type: entry[:event_type],
+        occurred_at: Time.current,
+        request_id: entry[:request_id],
+        ip_address: entry[:ip_address],
+        user_agent: entry[:user_agent],
+        session_id: entry[:session_id],
+        metadata: metadata
+      }
+
+      gid_attrs = {
+        actor_gid: actor&.to_global_id&.to_s,
+        actor_type: actor&.class&.name,
+        target_gid: target&.to_global_id&.to_s,
+        target_type: target&.class&.name,
+        scope_gid: scope&.to_global_id&.to_s,
+        scope_type: scope&.class&.name
+      }
+
+      if batching?
+        Thread.current[:standard_audit_batch] << attrs.merge(gid_attrs)
+        nil
+      elsif config.async
+        StandardAudit::CreateAuditLogJob.perform_later(attrs.merge(gid_attrs).stringify_keys)
+      else
+        log = StandardAudit::AuditLog.new(attrs)
+        log.actor = actor
+        log.target = target
+        log.scope = scope
+        log.save!
+        log
+      end
+    end
+
     def batching?
       Thread.current[:standard_audit_batch].is_a?(Array)
     end
@@ -173,11 +255,11 @@ module StandardAudit
       ids = buffer.size.times.map { SecureRandom.uuid_v7 }.sort
 
       rows = buffer.each_with_index.map do |attrs, i|
-        row = attrs.merge(
+        row = StandardAudit::AuditLog.apply_before_checksum_hooks(attrs.merge(
           id: ids[i],
           created_at: now,
           updated_at: now
-        )
+        ))
         checksum = StandardAudit::AuditLog.compute_checksum_value(
           row.stringify_keys,
           previous_checksum: previous_checksum

data/lib/tasks/standard_audit_tasks.rake

@@ -1,16 +1,44 @@
+module StandardAudit
+  module RakeSupport
+    module_function
+
+    # Resolves the retention window for cleanup/archive: the task argument,
+    # else config.retention_days, else abort. nil retention means "keep
+    # forever", so there is deliberately no hard-coded fallback. Anything that
+    # is not a positive integer aborts — `cleanup[abc]` used to become 0 days,
+    # i.e. delete everything.
+    def resolve_days!(task_name, arg)
+      raw = arg.presence || StandardAudit.config.retention_days
+
+      if raw.nil?
+        abort "standard_audit:#{task_name}: no retention window. Pass days " \
+              "(rake \"standard_audit:#{task_name}[90]\") or set config.retention_days " \
+              "/ STANDARD_AUDIT_RETENTION_DAYS. A nil retention_days means keep forever."
+      end
+
+      days = Integer(raw.to_s.strip, 10, exception: false)
+      unless days&.positive?
+        abort "standard_audit:#{task_name}: days must be a positive integer, got #{raw.inspect}"
+      end
+
+      days
+    end
+  end
+end
+
 namespace :standard_audit do
-  desc "Delete audit logs older than specified days (default: 90)"
+  desc "Delete audit logs older than N days (default: config.retention_days; aborts if neither is set)"
   task :cleanup, [:days] => :environment do |_t, args|
-    days = (args[:days] || StandardAudit.config.retention_days || 90).to_i
+    days = StandardAudit::RakeSupport.resolve_days!("cleanup", args[:days])
     cutoff = days.days.ago
 
     deleted = StandardAudit::AuditLog.where("occurred_at < ?", cutoff).delete_all
     puts "Deleted #{deleted} audit logs older than #{days} days"
   end
 
-  desc "Archive audit logs to JSON file"
+  desc "Archive audit logs older than N days to a JSON file (default: config.retention_days; aborts if neither is set)"
   task :archive, [:days, :output] => :environment do |_t, args|
-    days = (args[:days] || 90).to_i
+    days = StandardAudit::RakeSupport.resolve_days!("archive", args[:days])
     output = args[:output] || "audit_logs_archive_#{Date.current}.json"
     cutoff = days.days.ago
 
@@ -64,6 +92,7 @@ namespace :standard_audit do
     puts "Records verified: #{result[:verified]}"
     puts "Chain valid: #{result[:valid]}"
     puts "Forked links recovered: #{result[:recovered]}"
+    puts "Anonymized (redacted) records: #{result[:redacted]}" if result[:redacted].to_i.positive?
 
     if result[:failures].any?
       puts "\nUnverifiable records detected: #{result[:failures].size}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -97,6 +97,8 @@ files:
 - app/models/standard_audit/application_record.rb
 - app/models/standard_audit/audit_log.rb
 - config/routes.rb
+- lib/generators/standard_audit/add_anonymized_at/add_anonymized_at_generator.rb
+- lib/generators/standard_audit/add_anonymized_at/templates/add_anonymized_at_to_audit_logs.rb.erb
 - lib/generators/standard_audit/add_checksums/add_checksums_generator.rb
 - lib/generators/standard_audit/add_checksums/templates/add_checksum_to_audit_logs.rb.erb
 - lib/generators/standard_audit/add_previous_checksum/add_previous_checksum_generator.rb
@@ -117,6 +119,8 @@ files:
 - lib/standard_audit/record_reference.rb
 - lib/standard_audit/reference_preloading.rb
 - lib/standard_audit/rspec.rb
+- lib/standard_audit/rspec/baseline.rb
+- lib/standard_audit/rspec/matchers.rb
 - lib/standard_audit/rspec/operation.rb
 - lib/standard_audit/sensitive_keys_dry_run.rb
 - lib/standard_audit/subscriber.rb