bouncy 0.1.0 → 0.2.0

data/guides/operations.md

@@ -0,0 +1,104 @@
+# Scheduling, monitoring and operations
+
+Bouncy supplies Active Job classes and Rails tasks. It does not install a scheduler, edit recurring-job files or start workers. Configure the same scope, credentials and dependencies in web and job processes.
+
+## Schedule the jobs
+
+Run `Bouncy::SyncJob` hourly and `Bouncy::PruneJob` daily. Both use the `default` queue. While `config.scope` is unset, both return at once with one info line and touch neither AWS nor the database, so a schedule set up before the feature is on does not fill the failed-jobs list; `Bouncy.sync!` itself still raises. Ensure a worker consumes it; enqueuing a job is not evidence that it ran.
+
+For an app already using [Solid Queue recurring tasks](https://github.com/rails/solid_queue#recurring-tasks):
+
+```yaml
+# config/recurring.yml
+production:
+  bouncy_sync:
+    class: Bouncy::SyncJob
+    schedule: every hour
+  bouncy_prune:
+    class: Bouncy::PruneJob
+    schedule: every day at 3am
+```
+
+Merge these entries into your existing production section. Start the scheduler and workers using your app's normal deployment process. Solid Queue is optional. Other schedulers can enqueue the same classes:
+
+```ruby
+Bouncy::SyncJob.perform_later
+Bouncy::PruneJob.perform_later
+```
+
+If you use cron instead, run the work synchronously in the app's configured environment:
+
+```cron
+0 * * * * cd /srv/myapp && RAILS_ENV=production bin/rails bouncy:sync
+0 3 * * * cd /srv/myapp && RAILS_ENV=production bin/rails runner 'Bouncy::PruneJob.perform_now'
+```
+
+Adapt the path and Ruby/environment setup to your deployment. Choose one recurring mechanism. Configure failure alerts and retries through your existing job system; these jobs do not declare a custom retry policy.
+
+A second sync in the same scope fails immediately with `Bouncy::ProviderError` if another owns the lock. Do not overlap scheduled runs unnecessarily. See [database lock requirements](compatibility.md#synchronization).
+
+## Available tasks
+
+Run with `RAILS_ENV=production` in production:
+
+| Command | Effect |
+|---|---|
+| `bin/rails bouncy:doctor` | Read AWS identity/policy/topic attributes and local sync times; print JSON. Does not mutate AWS or test write permission. |
+| `bin/rails bouncy:ses:setup` | Run provider diagnostics and print a setup plan. Never provisions AWS. Any `APPLY` environment variable is rejected, including `APPLY=0`. |
+| `bin/rails bouncy:sync` | Read the full provider list, reconcile local rows and print the sync event details. |
+| `bin/rails bouncy:bootstrap` | Require a fresh, complete, policy-verified mirror, running a sync if necessary; raise on failure. |
+
+Doctor reports `policy_verified`, `policy_reason`, `topic_allowlist`, per-topic readability and publisher-policy review requirements, plus `last_attempt` and `last_success`. Write permission remains unknown until an explicitly authorized operation is exercised. It does not verify public endpoint reachability, subscription activation, notification delivery or job scheduling.
+
+A normal exit from doctor or sync can still describe an unverified policy. Inspect the JSON, not just the exit status. AWS read failures may raise before doctor/setup can print a result. Bootstrap is the strict freshness check for a planned cutover; do not put it on every container restart and make unrelated deployments depend on live AWS availability.
+
+## Monitor the mirror
+
+```ruby
+Bouncy.sync_fresh?
+Bouncy.last_sync&.details
+Bouncy.last_successful_sync&.created_at
+```
+
+A successful authoritative summary has `complete: true`, `enumerated: true`, `policy_verified: true`, and entry/change counts. An enumerated list with unsupported policy has `complete: false` and an explanation in `policy_reason`. A recorded provider error has `complete: false` and `error_class`.
+
+`entries` counts exact provider entries; address counts are normalized. Metadata-only refreshes and unchanged restrictions do not emit per-address change events. Each completed reconciliation still emits a summary. A lock acquisition failure or some configuration/database failures can occur before a summary is recorded; monitor job failures as well as freshness.
+
+Keep the sync interval shorter than `stale_after` (default two hours). If the mirror is stale or a newer sync reports unverified policy, the interceptor stops dropping based on provider/webhook evidence. An app that runs no sync sets `config.require_fresh_sync = false`: every recorded block then drops mail, and nothing clears a webhook block on its own. Independent manual and active soft holds remain effective. The status API can still show historical restrictions; it describes evidence, not the current transport decision.
+
+A host health check can use `Bouncy.sync_fresh?` and rescue recognized database outages to report an unhealthy dependency. Decide in the host whether to expose this as a separate email-health indicator or affect overall readiness. Do not expose address history or provider diagnostics in an unauthenticated health response.
+
+## Hooks and instrumentation
+
+```ruby
+Bouncy.configure do |config|
+  config.after_event = ->(event) { Rails.logger.info("Bouncy event #{event.id}: #{event.kind}") }
+  config.after_block = ->(event) { SupportNotificationJob.perform_later(event.id) }
+  config.after_release = ->(event) { RecoveryNotificationJob.perform_later(event.id) }
+end
+```
+
+Implement the example jobs in the host. Callbacks receive a committed `Bouncy::Event`. `after_event` runs for every newly created event, including sync summaries and interception observations. `after_block` runs when `details["became_blocked"]` is true, not for every repeated bounce. `after_release` runs for explicit `release` events, including local-only releases; it does not run for `sync_released`. Use `after_event` with a kind check if you need to observe reconciliation releases.
+
+These hooks are best effort. Exceptions emit `hook_error.bouncy` with `hook` and `error_class`, and do not undo the event. They run after the commit of the outermost transaction, after Bouncy released every address lock of it, and, for a write inside `Bouncy.hold`, when the hold ends. A rollback drops them. Rails transactional tests keep 0.1's timing. Bouncy marks the fixture transaction of each pool that `ActiveRecord::TestFixtures` enrolls, as listed in its own `@fixture_connection_pools`: at `setup_transactional_fixtures`, and for a pool established later from a `!connection.active_record` subscriber that runs after Rails' own. It clears the marks in `teardown_transactional_fixtures` (Rails 7.2, 8.0 and 8.1). While a marked transaction is the only one open, hooks run when the app's own transaction commits. A database excluded with `skip_transactional_tests_for_database` (Rails 8.1), or a connection pinned in any other way, keeps the outer-commit rule. A process can stop after commit before notification completes. Use idempotent consumers and a host outbox/reconciliation mechanism for guaranteed external work. Jobs should tolerate an event being pruned before execution.
+
+`config.on_notification` is different: it runs synchronously in the receiver, with every SES notification, and its failure is not swallowed. A raise emits `hook_error.bouncy` with `hook: :on_notification`, logs the error class and answers 503, so SNS delivers the notification again. Keep it short and idempotent; see [SES notifications](api.md#ses-notifications).
+
+Other Active Support notifications are `unconfigured.bouncy` (operation attempted while inactive, including `hold`) and `unavailable.bouncy` (interception encounters a recognized database outage). Subscribe using your existing instrumentation:
+
+```ruby
+ActiveSupport::Notifications.subscribe("hook_error.bouncy") do |*args|
+  notification = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.error("Bouncy hook failed: #{notification.payload[:hook]} (#{notification.payload[:error_class]})")
+end
+```
+
+These are not delivery receipts. Avoid logging addresses, raw payloads or arbitrary exception messages.
+
+## Retention and operational history
+
+Schedule pruning; setting retention alone deletes nothing. `PruneJob` deletes events whose local `created_at` is older than the configured duration. Current state, exact provider evidence and inactive release fences remain. See [privacy and erasure](privacy.md).
+
+Use `Bouncy.events.for(address).recent` for occurrence-ordered address history. Operational events such as sync summaries may have no address. `skipped` events include `mode`, `would_drop`, `dropped` and `stale_provider_evidence`: in log mode, they preview the enforcement decision while delivery continues.
+
+The gem does not send test messages or automatically resend after recovery. Exercise the real SES feedback and authorized recovery lifecycle in your own staging setup before relying on dropping in production. Automated SDK/signature tests are not a substitute for validating your credentials, topic and delivery path.

data/guides/privacy.md

@@ -2,7 +2,7 @@
 
 Bouncy stores the normalized address, exact provider identifiers, reasons, event IDs/times, bounded provider diagnostics, support notes and actor references. Those fields can contain personal information. Raw payloads, subjects, bodies and attachments are not stored by this release.
 
-Default event retention is 90 days. Schedule `Bouncy::PruneJob` daily. Retention must cover the maximum accepted event age; old events are retained as diagnostic observations without applying stale policy. Current state and release ordering metadata survive event pruning.
+Default event retention is 90 days, measured from local event creation (`created_at`), not provider occurrence time. Schedule `Bouncy::PruneJob` daily; no pruning happens merely by configuring retention. Retention must cover `maximum_event_age`. Feedback older than that acceptance window can be recorded for diagnostics without applying a new restriction, then ages out under normal pruning. Current state and release ordering metadata survive event pruning.
 
 `Bouncy.forget!(address)` erases local state and events in the configured scope. It does not change the provider list. A subsequent sync or eligible notification can create state again, and erasure also removes local release fences. It is not a complete legal/compliance workflow or a provider recovery action.
 

data/guides/troubleshooting.md

@@ -30,7 +30,7 @@ Release never resends the original email. Regenerate time-sensitive links in an
 - If `Bouncy.status(address).knowledge` is `:unconfigured`, `config.scope` is blank and Bouncy is inactive in that environment.
 - Confirm the SNS HTTPS subscription is active and points at the actual mounted route.
 - Confirm SES routes the needed event types to that topic, and raw SNS message delivery is disabled.
-- Inspect bounded receiver status codes: 401 authorization/signature, 400 malformed input, 413 body limit, 503 retryable infrastructure failure.
+- Inspect bounded receiver status codes: 401 authorization/signature, 400 malformed input, 413 body limit, 503 retryable infrastructure failure, a failed `SubscribeURL` visit or a raise in `config.on_notification`. Each refusal logs `[bouncy] refused an SNS message (<status>): <reason>; topic <ARN>`; a failed confirmation also names the `SubscribeURL` host.
 - Run a complete sync and verify the scheduled job actually runs in production.
 
 An hourly sync cannot reconstruct every lost delivery or soft-bounce event. SNS retries and operational monitoring still matter.

data/lib/bouncy/address_lock.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Bouncy
+  # One lock per address, between the app's senders and Bouncy's own writes.
+  #
+  # A sender takes the shared side with Bouncy.hold, around its own check and its send. Every
+  # Bouncy write to an address (webhook, sync, block!, release!) takes the exclusive side first,
+  # until its transaction ends. A new block therefore commits before the sender's check or after
+  # its send, never between them. Inside a transaction, a hold lasts until that transaction ends.
+  #
+  # PostgreSQL holds transaction-level advisory locks, which it releases itself at the commit
+  # or the rollback. MySQL named locks and SQLite file locks belong to the connection, and three
+  # paths release them at the end of the outermost transaction:
+  #
+  # 1. the transaction.active_record event, which Rails sends right after the COMMIT or the
+  #    ROLLBACK and before any callback, so a host callback that raises cannot keep a lock;
+  # 2. after_commit and after_rollback on the transaction itself, for a transaction that started
+  #    before Bouncy subscribed to that event;
+  # 3. the connection's return to the pool, for anything both paths missed.
+  #
+  # Hooks never run inside a lock: they wait for the commit of the outermost transaction, which
+  # comes after the releases, and the hooks of a write inside a hold wait until the hold ends.
+  module AddressLock
+    FileHold = Struct.new(:guard, :file, :mode, :holders)
+    # Per connection, like the locks themselves: threads that share one connection, as Rails
+    # system tests do, share its holds and the hooks that wait for them.
+    Holds = Struct.new(:depth, :hooks)
+    FILE_LOCKS = ObjectSpace::WeakKeyMap.new
+    DEFERRED = ObjectSpace::WeakKeyMap.new
+    HOLDS = ObjectSpace::WeakKeyMap.new
+    FIXTURES = ObjectSpace::WeakKeyMap.new
+    GUARD = Mutex.new
+
+    module_function
+
+    def hold(email)
+      key = Identity.normalize(email)
+      Record.connection_pool.with_connection do |connection|
+        settle(connection)
+        require_read_committed(connection)
+        release = take(connection, key, exclusive: false)
+        holds = GUARD.synchronize { (HOLDS[connection] ||= Holds.new(0, [])).tap { |state| state.depth += 1 } }
+        begin
+          yield
+        ensure
+          hooks = GUARD.synchronize do
+            holds.depth -= 1
+            holds.depth.zero? ? holds.hooks.slice!(0..) : []
+          end
+          begin
+            until_transaction_end(connection, release)
+          ensure
+            hooks.each(&:call)
+          end
+        end
+      end
+    end
+
+    # Takes the exclusive side until the current transaction commits or rolls back. Store.change
+    # calls it first in its transaction, before it takes any row lock.
+    def claim!(email)
+      key = Identity.normalize(email)
+      Record.connection_pool.with_connection do |connection|
+        until_transaction_end(connection, take(connection, key, exclusive: true))
+      end
+    end
+
+    def holding?(connection = Record.connection_pool.active_connection)
+      connection && GUARD.synchronize { HOLDS[connection]&.depth.to_i.positive? }
+    end
+
+    # Runs a hook once its connection holds no Bouncy lock. A record's commit callbacks can run
+    # while an outer transaction is still open, under transaction(joinable: false); the hook then
+    # moves to that transaction, and so runs after the commit of the outermost one, or never if
+    # it rolls back. Inside a hold it waits for the hold.
+    #
+    # Rails transactional tests keep 0.1's timing: the hook runs at the commit inside the
+    # fixture transaction, which only ever rolls back. FixtureTransactions marks that transaction. With no transaction left open, releases
+    # that Rails did not report are settled first, because Rails runs record commit callbacks,
+    # such as the event's, before the transaction callbacks that would release them.
+    def after_locks(&hook)
+      connection = Record.connection_pool.active_connection
+      return hook.call unless connection
+
+      deferred = connection.transaction_open? && !only_fixture_transaction?(connection)
+      return connection.current_transaction.after_commit { after_locks(&hook) } if deferred
+
+      settle(connection)
+      queued = GUARD.synchronize do
+        holds = HOLDS[connection]
+        holds.hooks << hook if holds&.depth.to_i.positive?
+      end
+      hook.call unless queued
+    end
+
+    # True while the connection's only open transaction is the one Rails transactional fixtures
+    # began on it. FixtureTransactions records that transaction from the fixture lifecycle.
+    def only_fixture_transaction?(connection)
+      fixture = GUARD.synchronize { FIXTURES[connection] }
+      !fixture.nil? && connection.open_transactions == 1 && connection.current_transaction.equal?(fixture)
+    end
+
+    # Prepended into every class that includes ActiveRecord::TestFixtures. Rails 7.2, 8.0 and 8.1
+    # enroll a pool into the fixture transactions in two places: setup_transactional_fixtures,
+    # for the pools already connected, and its own "!connection.active_record" subscriber, for a
+    # pool established or replaced later in the test. Both pin the pool's connection, which
+    # begins the fixture transaction, lease that connection and add the pool to
+    # @fixture_connection_pools. Rails 8.1 leaves out the pools a test excludes with
+    # skip_transactional_tests_for_database. Bouncy marks the transactions of exactly the
+    # pools on that list, at setup and from a subscriber that runs after Rails' own, and clears
+    # the marks at teardown.
+    module FixtureTransactions
+      private
+
+      # A late pool's callback can still be running in another thread when teardown starts, and
+      # unsubscribing does not stop it. One lock per fixture covers the checks and the writes of
+      # every callback and teardown's clear, and teardown closes the registration under it
+      # before it unsubscribes: a callback that reaches the lock afterwards does nothing.
+      def setup_transactional_fixtures
+        super
+        @bouncy_fixture_guard = Mutex.new
+        @bouncy_fixture_closed = false
+        @bouncy_fixture_connections = []
+        mark_fixture_transactions
+        @bouncy_fixture_subscriber = ActiveSupport::Notifications.subscribe("!connection.active_record") { mark_fixture_transactions }
+      end
+
+      def teardown_transactional_fixtures
+        @bouncy_fixture_guard&.synchronize do
+          @bouncy_fixture_closed = true
+          @bouncy_fixture_connections.each { |connection| GUARD.synchronize { FIXTURES.delete(connection) } }
+          @bouncy_fixture_connections.clear
+        end
+        ActiveSupport::Notifications.unsubscribe(@bouncy_fixture_subscriber) if @bouncy_fixture_subscriber
+        @bouncy_fixture_subscriber = nil
+        super
+      end
+
+      def mark_fixture_transactions
+        @bouncy_fixture_guard.synchronize do
+          next if @bouncy_fixture_closed
+
+          Array(@fixture_connection_pools).each do |pool|
+            connection = pool.active_connection
+            next if connection.nil? || !connection.transaction_open? || @bouncy_fixture_connections.include?(connection)
+
+            record_fixture_transaction(connection)
+          end
+        end
+      end
+
+      # Runs under the fixture's lock, after the checks.
+      def record_fixture_transaction(connection)
+        GUARD.synchronize { FIXTURES[connection] = connection.current_transaction }
+        @bouncy_fixture_connections << connection
+      end
+    end
+
+    # Releases what an ended transaction left behind, in case Rails never reported its end.
+    def settle(connection)
+      return if connection.transaction_open?
+
+      release_deferred(connection)
+    end
+
+    # Inside a PostgreSQL transaction, a hold must not run at REPEATABLE READ or SERIALIZABLE:
+    # the lock statement fixes the snapshot before it waits, so a block committed during the wait
+    # stays invisible. Hold the address outside the transaction instead; the lock then lasts for
+    # the whole block, and the transaction's snapshot starts after it.
+    def require_read_committed(connection)
+      return unless connection.adapter_name == "PostgreSQL" && connection.transaction_open?
+
+      isolation = connection.uncached { connection.select_value("SHOW transaction_isolation") }
+      return if ["read committed", "read uncommitted"].include?(isolation)
+
+      raise ConfigurationError, "Bouncy.hold inside a PostgreSQL #{isolation} transaction cannot see a block committed while it waits; " \
+                                "call Bouncy.hold outside the transaction, around it"
+    end
+
+    # Takes the lock now and returns what releases it, or nil when the database releases it.
+    def take(connection, key, exclusive:)
+      case connection.adapter_name
+      when "PostgreSQL" then take_advisory(connection, key, exclusive)
+      when /Mysql|Trilogy/i then take_named(connection, key)
+      when "SQLite" then take_file(connection, exclusive ? File::LOCK_EX : File::LOCK_SH)
+      else raise ConfigurationError, "Bouncy supports PostgreSQL, MySQL and SQLite"
+      end
+    end
+
+    # Inside a transaction: a transaction-level lock, released by PostgreSQL at the commit or
+    # the rollback, also when a failed statement aborted the transaction. Outside one: a session
+    # lock for the block. The key is a signed 64-bit hash of the scope and the address.
+    def take_advisory(connection, key, exclusive)
+      shared = exclusive ? "" : "_shared"
+      if connection.transaction_open?
+        connection.execute("SELECT pg_advisory_xact_lock#{shared}(#{advisory_key(key)})")
+        return
+      end
+
+      connection.execute("SELECT pg_advisory_lock#{shared}(#{advisory_key(key)})")
+      -> { connection.execute("SELECT pg_advisory_unlock#{shared}(#{advisory_key(key)})") }
+    end
+
+    # GET_LOCK waits as long as an InnoDB row lock would. A session can take the same name again;
+    # each take needs its own release. Both statements skip the query cache: a cached GET_LOCK
+    # would answer 1 without locking.
+    def take_named(connection, key)
+      name = connection.quote(Digest::SHA256.hexdigest("bouncy:address:#{connection.pool.db_config.database}:#{Bouncy.scope}:#{key}"))
+      acquired = connection.uncached { connection.select_value("SELECT GET_LOCK(#{name}, @@innodb_lock_wait_timeout)") }
+      raise ActiveRecord::LockWaitTimeout, "Bouncy could not lock an address in time" unless acquired.to_i == 1
+
+      released = false
+      lambda do
+        next if released
+
+        released = true
+        connection.uncached { connection.select_value("SELECT RELEASE_LOCK(#{name})") }
+      rescue ActiveRecord::ActiveRecordError
+        # A broken connection ends its session, and the server releases the session's locks.
+        nil
+      end
+    end
+
+    # One file per database, held per connection the way PostgreSQL and MySQL hold a lock per
+    # session. A connection that already holds the file reuses its handle: a write inside its
+    # own hold upgrades the lock to exclusive instead of waiting for itself. Threads that share
+    # one connection, as Rails tests do, share its lock too.
+    def take_file(connection, mode)
+      held = GUARD.synchronize { FILE_LOCKS[connection] ||= FileHold.new(Mutex.new, nil, nil, 0) }
+      held.guard.synchronize do
+        if held.file.nil?
+          # The handle stays open while the lock is held; the last release closes it.
+          file = File.open(lock_path(connection), File::RDWR | File::CREAT, 0o600) # rubocop:disable Style/FileOpen
+          file.flock(mode)
+          held.file = file
+          held.mode = mode
+        elsif mode == File::LOCK_EX && held.mode == File::LOCK_SH
+          held.file.flock(File::LOCK_EX)
+          held.mode = File::LOCK_EX
+        end
+        held.holders += 1
+      end
+      released = false
+      lambda do
+        held.guard.synchronize do
+          next if released
+
+          released = true
+          held.holders -= 1
+          next if held.holders.positive?
+
+          held.file.close
+          held.file = held.mode = nil
+        end
+      end
+    end
+
+    def lock_path(connection)
+      database = connection.pool.db_config.database
+      return File.join(Dir.tmpdir, "bouncy-#{Process.pid}-addresses.lock") if database == ":memory:"
+
+      "#{File.expand_path(database)}.bouncy-addresses.lock"
+    end
+
+    # Releases now outside a transaction. Inside one, keeps the release for the end of the
+    # outermost transaction; the transaction is materialized first, so Rails reports its end.
+    def until_transaction_end(connection, release)
+      return unless release
+      return release.call unless connection.transaction_open?
+
+      connection.materialize_transactions
+      GUARD.synchronize { (DEFERRED[connection] ||= []) << release }
+      watch(connection)
+    end
+
+    # The second path. A savepoint under a joinable parent hands both callbacks to the parent
+    # when it commits. One that rolls back, or commits under a transaction(joinable: false)
+    # parent, runs its callback while the parent continues, so the watch moves up a level. It
+    # uses the connection's transaction object: the public Record.current_transaction is a null
+    # transaction under transaction(joinable: false), and would run the block at once.
+    def watch(connection)
+      transaction = connection.current_transaction
+      ended = -> { connection.transaction_open? ? watch(connection) : settle(connection) }
+      transaction.after_commit(&ended)
+      transaction.after_rollback(&ended)
+    end
+
+    # Rails pops a committed transaction before it reports the commit, and reports a rollback
+    # before it pops the transaction. :restart reports a savepoint that continues.
+    def transaction_ended(payload)
+      connection = payload[:connection]
+      return unless connection && GUARD.synchronize { DEFERRED.key?(connection) }
+
+      outermost = case payload[:outcome]
+                  when :commit then connection.open_transactions.zero?
+                  when :rollback then connection.open_transactions <= 1
+                  when :incomplete then true
+                  else false
+                  end
+      release_deferred(connection) if outermost
+    end
+
+    def release_deferred(connection)
+      releases = GUARD.synchronize { DEFERRED.delete(connection) }
+      releases&.each(&:call)
+    end
+
+    def advisory_key(key) = Digest::SHA256.digest("bouncy:address\n#{Bouncy.scope}\n#{key}").unpack1("q>")
+  end
+
+  # Subscribed when the gem loads: Rails gives each transaction the subscribers that exist when
+  # the transaction starts, so a later subscription misses it, and the second path covers that.
+  ActiveSupport::Notifications.subscribe("transaction.active_record") { |*, payload| AddressLock.transaction_ended(payload) }
+
+  ActiveSupport.on_load(:active_record_fixtures) { prepend AddressLock::FixtureTransactions }
+
+  # The third path: a connection goes back to the pool with nothing of Bouncy's still locked.
+  ActiveRecord::ConnectionAdapters::AbstractAdapter.set_callback(:checkin, :after) { AddressLock.release_deferred(self) }
+end

data/lib/bouncy/body_limit.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Rack middleware that cuts the body of a request to the receiver before Rails reads it.
+  #
+  # Rails reads a whole chunked body to learn its length, and parses a JSON or form body for
+  # its request log, before the route runs. The receiver's own limit then comes too late.
+  # SNS posts 256 KB at most. A longer body gets 413 after limit + 1 bytes are read; a shorter
+  # one goes on with a plain Content-Length.
+  #
+  # The limit applies to the paths the router sends to the receiver: the path itself, with
+  # repeated slashes squeezed, an optional trailing slash and an optional format suffix
+  # ("//bouncy/webhooks/ses/", "/bouncy/webhooks/ses.json"). It is compared with PATH_INFO and
+  # with SCRIPT_NAME + PATH_INFO, so it also holds when the app is mounted under a prefix. An
+  # adjacent route such as "/bouncy/webhooks/ses-admin" is not limited.
+  #
+  #   # config/application.rb
+  #   config.middleware.insert_before 0, Bouncy::BodyLimit, path: "/bouncy/webhooks/ses"
+  class BodyLimit
+    DEFAULT_LIMIT = 300.kilobytes
+
+    def initialize(app, path: "/bouncy/webhooks/ses", limit: DEFAULT_LIMIT)
+      @app = app
+      normalized = path.to_s.squeeze("/").chomp("/")
+      raise ArgumentError, "path must be the receiver's absolute path" unless normalized.start_with?("/") && normalized.size > 1
+      raise ArgumentError, "limit must be a positive number of bytes" unless limit.is_a?(Integer) && limit.positive?
+
+      @limit = limit
+      @route = %r{\A#{Regexp.escape(normalized)}(?:\.[^/.]+)?/?\z}
+    end
+
+    def call(environment)
+      return @app.call(environment) unless receiver?(environment)
+
+      input = environment["rack.input"]
+      input.rewind if input.respond_to?(:rewind)
+      body = input&.read(@limit + 1).to_s
+      return too_large if body.bytesize > @limit
+
+      environment["rack.input"] = StringIO.new(body)
+      environment["CONTENT_LENGTH"] = body.bytesize.to_s
+      environment.delete("HTTP_TRANSFER_ENCODING")
+      @app.call(environment)
+    end
+
+    private
+
+    def receiver?(environment)
+      path = environment["PATH_INFO"].to_s
+      [path, environment["SCRIPT_NAME"].to_s + path].any? { |candidate| candidate.squeeze("/").match?(@route) }
+    end
+
+    def too_large = [413, { "content-type" => "text/plain", "cache-control" => "no-store" }, [Rack::Utils::HTTP_STATUS_CODES.fetch(413)]]
+  end
+end

data/lib/bouncy/configuration.rb

@@ -7,8 +7,17 @@ module Bouncy
       # caches Amazon's signing certificate, so a host can test its mounted receiver offline.
       # Topic authorization and certificate-URL checks still run, which is the point: a test
       # seam that skipped them would hide exactly the hole they exist to close.
+      #
+      # configuration_set names the SES configuration set that the interceptor stamps on every
+      # message (X-SES-CONFIGURATION-SET), so SES publishes that mail's events to the set's topic.
+      # The set also joins the sending-policy check. A blank name stamps nothing.
+      #
+      # subscription_confirmation picks how the receiver confirms an SNS subscription: :api calls
+      # sns:ConfirmSubscription with the signed token; :subscribe_url visits the signed
+      # SubscribeURL instead, for credentials without that grant.
       attr_accessor :region, :credentials, :topic_arns, :client, :sns_client, :sts_client, :sns_message_verifier,
-                    :identities, :configuration_sets, :all_sending_paths_listed
+                    :identities, :configuration_sets, :all_sending_paths_listed, :configuration_set,
+                    :subscription_confirmation
 
       def initialize
         @topic_arns = []
@@ -18,6 +27,7 @@ module Bouncy
         # check needs every sending identity and configuration set listed. This flag is the
         # installer's statement that the lists above are complete.
         @all_sending_paths_listed = false
+        @subscription_confirmation = :api
       end
     end
 
@@ -26,10 +36,24 @@ module Bouncy
     # stop the sending. Leave the threshold nil to keep soft bounces record-only.
     SOFT_BOUNCE_OCCURRENCE_LIMIT = 50
 
+    # require_fresh_sync: true enforces provider and webhook evidence only while a complete sync
+    # is fresh. false enforces it always, for an app that runs no sync job: on an SES account
+    # that other apps share, their suppressions stay out of this app's tables.
+    #
+    # on_notification is called with every SES notification, after its state commits and before
+    # the receiver answers. Unlike the after_* hooks it may raise: the receiver then answers 503,
+    # and SNS delivers the notification again.
+    #
+    # webhook_blocking picks which notifications block an address. :cautious blocks General and
+    # NoEmail bounces and complaints that name one recipient, and leaves the rest to the sync,
+    # which reads the account list. :strict blocks every Permanent bounce, whatever its subtype,
+    # and every recipient a complaint names. It defaults to :cautious while a sync runs and to
+    # :strict when require_fresh_sync is false, because then nothing reads the account list.
+    attr_writer :webhook_blocking
     attr_accessor :provider, :scope, :interception, :record_deliveries,
                   :retention, :maximum_event_age, :stale_after, :after_block, :after_release,
                   :after_event, :adapter, :soft_bounce_threshold, :soft_bounce_window,
-                  :soft_bounce_block_for
+                  :soft_bounce_block_for, :require_fresh_sync, :on_notification
     attr_reader :ses
 
     def initialize
@@ -42,8 +66,10 @@ module Bouncy
       @soft_bounce_threshold = nil
       @soft_bounce_window = 30.days
       @soft_bounce_block_for = 30.days
+      @require_fresh_sync = true
       @ses = Ses.new
       @after_block = @after_release = @after_event = ->(_event) {}
+      @on_notification = ->(_notification) {}
     end
 
     # Occurrence times retained per address so the window can roll. Bounded either way: a
@@ -56,6 +82,8 @@ module Bouncy
 
     def soft_bounce_escalation? = soft_bounce_threshold.to_i.positive?
 
+    def webhook_blocking = @webhook_blocking || (require_fresh_sync == false ? :strict : :cautious)
+
     def configured? = !scope.to_s.strip.empty?
 
     def validate!
@@ -63,6 +91,14 @@ module Bouncy
       raise ConfigurationError, "scope must be at most 191 characters" if scope.to_s.length > 191
       raise ConfigurationError, "Only the SES provider is supported" unless provider == :ses || adapter
       raise ConfigurationError, "interception must be :log, :drop or :off" unless %i[log drop off].include?(interception)
+      raise ConfigurationError, "require_fresh_sync must be true or false" unless [true, false].include?(require_fresh_sync)
+      raise ConfigurationError, "webhook_blocking must be :cautious or :strict" unless %i[cautious strict].include?(webhook_blocking)
+      unless %i[api subscribe_url].include?(ses.subscription_confirmation)
+        raise ConfigurationError, "ses.subscription_confirmation must be :api or :subscribe_url"
+      end
+      unless ses.configuration_set.nil? || ses.configuration_set.is_a?(String)
+        raise ConfigurationError, "ses.configuration_set must be the name of an SES configuration set, or nil"
+      end
       unless maximum_event_age.positive? && retention >= maximum_event_age
         raise ConfigurationError, "retention must cover maximum_event_age, and both must be positive"
       end

data/lib/bouncy/event.rb

@@ -13,10 +13,15 @@ module Bouncy
 
     private
 
+    # Writes release their address locks at the commit of the outermost transaction, and the
+    # hooks wait for that commit and for the end of any Bouncy.hold, so no hook runs while
+    # Bouncy holds an address.
     def notify_host
-      Bouncy.notify(:after_event, self)
-      Bouncy.notify(:after_block, self) if details["became_blocked"]
-      Bouncy.notify(:after_release, self) if kind == "release"
+      AddressLock.after_locks do
+        Bouncy.notify(:after_event, self)
+        Bouncy.notify(:after_block, self) if details["became_blocked"]
+        Bouncy.notify(:after_release, self) if kind == "release"
+      end
     end
   end
 end

data/lib/bouncy/ingestor.rb

@@ -44,9 +44,11 @@ module Bouncy
       details = attributes.fetch(:details).merge("ignored_for_policy" => [too_old, fenced, out_of_order].any?)
       if row && !details["ignored_for_policy"]
         was_blocked = row.blocked?
-        # A complaint blocks locally only when the provider named exactly one recipient (SesParser
-        # marks it "confirmed"); candidates wait for the provider's own list at the next sync.
-        if attributes[:kind] == "hard_bounce" || (attributes[:kind] == "complaint" && details["certainty"] == "confirmed")
+        # Under :cautious a complaint blocks locally only when the provider named exactly one
+        # recipient (SesParser marks it "confirmed"); candidates wait for the provider's own list
+        # at the next sync. Under :strict every named recipient blocks.
+        complaint = attributes[:kind] == "complaint" && (details["certainty"] == "confirmed" || Bouncy.configuration.webhook_blocking == :strict)
+        if attributes[:kind] == "hard_bounce" || complaint
           row.event_blocked_at = time
           row.event_reason = attributes[:kind]
           row.last_event_at = [row.last_event_at, time].compact.max