bouncy 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3caefdf93f208340d8314a9d2f6f7736079471f539651818f202591daf9840f
-  data.tar.gz: e6704bc8c6b3a1adc0961bd13eb34070ce797960037b18efc0f5d9dd5095b86a
+  metadata.gz: 454c9ceb5482a94e7885dd6d648b9716e05d24c6ffe6d11cae8e4957297be373
+  data.tar.gz: 36c35cc2d4b7b39d63722dd04cdb36a773cd0814dca1b7f8fd12be463ac55222
 SHA512:
-  metadata.gz: b61276efe0533445572e0cef61645ff54783d69ee68b334225c3f989fda2534e0e36dbcc6dd08711f169e6ddfdb1c421ce47e0f1f297e4097760f9601c368dbe
-  data.tar.gz: 53d8d0c1c56f8391c1ea3d29bee91bf10f262b2d71490c128cddfde1f81cbd26bfa255a17a6b061ec30ba82f4b150066a8e451219a8fa6d3ea0b1f268657639b
+  metadata.gz: 8ab0266ad476a1b157171125d6062c3eda54b02b078aaaa244e6e22dee750c7ec19512cd36bec481270a8debe5b578b6502d3267bc01375450ec07990c33398e
+  data.tar.gz: '088f91735a153cdf3c6f9c922dbc775641743d375b11733f98438403d50ff0afbfa064e136486a416ccbcad97dc7e5e9887b134a229eb3caa860112f8f4151bc'

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-10-26
+
+One fix that an app on the fleet found with the PostGIS adapter. There is no new migration.
+
+### Fixed
+
+- Bouncy knows a database by its Active Record adapter class, so an adapter that subclasses a Rails adapter gets the locks of that database whatever name it reports, because the PostGIS adapter (`activerecord-postgis-adapter`) is a `PostgreSQLAdapter` whose `adapter_name` is `"PostGIS"`, and Bouncy matched the name `"PostgreSQL"` exactly: it raised "Bouncy supports PostgreSQL, MySQL and SQLite", the receiver answered 503 to every signed SNS message, and `Bouncy.hold`, `Bouncy.sync!` and every other write raised. The name is still the fallback for an adapter that only renames itself. One helper, `Bouncy::Database`, now makes this choice for every lock and read.
+- The install migration gives a PostGIS database JSONB columns and native UUID keys, as it gives PostgreSQL, because it looked for `"postgres"` in the adapter name and made JSON columns and 36-character string keys there. Tables made that way keep working and need no change.
+
+## [0.2.1] - 2026-10-25
+
+Three gaps that the first app to move its own suppression table to Bouncy found. There is no new migration.
+
+### Added
+
+- `Bouncy.import!(email, reason:, at:, note: nil, actor: nil)` records a block that another system recorded, with its reason (`:hard_bounce`, `:complaint` or `:manual`) and its time, as one `imported` event; it calls no hook, writes nothing when it repeats, never weakens a block in force and changes nothing after a later release, because an app that carried its old suppressions had to call the internal `Bouncy::Ingestor`, which treats each call as new webhook feedback. `Bouncy::Ingestor` keeps its 0.2.0 call shape and is now marked internal.
+- `Status#blocked_at` is the time the block in force began (for an import, its `at:` time) and `nil` when the address is not blocked, because an app that shows "not deliverable since" had to read the suppression row itself; a block that follows an expired soft hold now starts at its own time, not at the soft hold's.
+
+### Changed
+
+- The 90-day freshness rule (`config.maximum_event_age`) applies to webhook feedback only, not to imports or manual holds, because it exists to stop a late notification from blocking, while a block that another system kept for a year is still a block: an import dated a year ago drops mail, and a webhook bounce dated a year ago still does not.
+
 ## [0.2.0] - 2026-10-25
 
 Eight features that apps need to replace a hand-rolled SES integration with Bouncy. There is no new migration: the address lock uses database locks, not a column.

data/README.md

@@ -41,7 +41,7 @@ Check out my other 💎 Ruby gems: [`nondisposable`](https://github.com/rameerez
 ## Requirements
 
 - Ruby **3.3+** and Rails **7.2.3.2+**, below Rails 9. Tested on Ruby 3.3/3.4/4.0 and Rails 7.2/8.0/8.1.
-- **PostgreSQL, MySQL or SQLite**, with bigint or UUID primary keys.
+- **PostgreSQL** (including the PostGIS adapter), **MySQL** or **SQLite**, with bigint or UUID primary keys.
 - **Amazon SES**, one account and region. SES SMTP is supported; suppression management needs AWS API credentials.
 
 Start in observation mode and verify your sending setup before enabling dropping. See [compatibility and validation](guides/compatibility.md) for the tested matrix and remaining validation limits.
@@ -131,6 +131,7 @@ status.knowledge        # :observed, :no_known_block, :unavailable, :unconfigure
 status.provider_listed?  # Exact provider identifiers are present locally
 status.policy_reason    # Why a listed address's sending policy is unverified
 status.stale?           # Address observation is missing or older than stale_after
+status.blocked_at       # When the block in force began, or nil when not blocked
 
 Bouncy.blocked
 Bouncy.events.for("ada@example.com").recent.limit(20)
@@ -196,6 +197,16 @@ Bouncy.release!(address, note: "Verified recovery", actor: "support:42")
 
 Default release removes exact provider variants and verifies absence before clearing local state. Errors leave evidence available for review. Releasing an SES restriction can affect sister apps in that account and region; authorize the action in your app. Release does not resend mail or restore consent after a complaint. See [recovery and partial failures](guides/recovery.md).
 
+### Carry blocks from another system
+
+An app that moves its own suppression table to Bouncy carries each block with its reason and the time the old table recorded it:
+
+```ruby
+Bouncy.import!(address, reason: :hard_bounce, at: old_row.suppressed_at, note: "Carried from the old table", actor: "carry-task")
+```
+
+`reason` is `:hard_bounce`, `:complaint` or `:manual`. A bounce or a complaint is the same evidence as a webhook block, and a manual block is a manual hold. `at` can be of any age: the 90-day window for late webhook feedback does not apply. The import calls no hook, writes nothing when it repeats, never weakens a block in force, and changes nothing when the address was released after `at`, so a carry task is safe to run again. See [migrating](guides/migrating.md).
+
 Use any admin UI. Bouncy has **no Madmin dependency, generator or adapter**. The [admin recipe](guides/admin.md) covers host-owned recovery actions, badges and notifications.
 
 ### Handle repeated mailbox-full bounces

data/guides/api.md

@@ -20,6 +20,7 @@ Bouncy.blocked?("ada@example.com") # Same as status.blocked?
 | `record` | Underlying `Bouncy::Suppression`, or `nil`, for host-owned admin links. |
 | `provider_listed?` | Exact provider entries exist in the local mirror, even if policy verification has not made them enforceable. |
 | `provider_updated_at` | Latest update time among those provider entries, or `nil`. |
+| `blocked_at` | Time the block in force began: when the address became blocked locally, or the `at:` time of the `Bouncy.import!` that blocked it. Stays while further evidence arrives; a block after an expired soft hold starts anew. `nil` when not blocked. |
 | `observed_at` | Provider check time if present, otherwise the last address event time, or `nil`. |
 | `stale?` | True for unavailable/unconfigured knowledge, missing observation time or an observation older than `stale_after`. This is address freshness; use `Bouncy.sync_fresh?` for mirror health. |
 | `policy_unverified?` | A locally listed address whose latest scoped sync did not report verified sending policy. |
@@ -81,6 +82,7 @@ The override applies to status and predicates as well as scopes. Your app must p
 | `Bouncy.blocked` | Scoped ActiveRecord relation of currently restricted suppression rows. |
 | `Bouncy.events` | Scoped event relation; chain `.for(address).recent.limit(50)`. |
 | `Bouncy.block!(address, note:, actor: nil)` | Add a local manual hold; a nonblank note is required. Returns the suppression row. Does not call SES. |
+| `Bouncy.import!(address, reason:, at:, note: nil, actor: nil)` | Record a block that another system recorded at `at`, with `reason` `:hard_bounce`, `:complaint` or `:manual`. Returns the suppression row. Does not call SES. See [imports](#imports). |
 | `Bouncy.release!(address, note: nil, actor: nil, at: :provider)` | Provider-aware release by default, requiring a note and verified provider snapshot. Returns the row; may raise on partial remote success. |
 | `Bouncy.release!(address, at: :local)` | Clear manual and soft holds and their soft-bounce history; fence delayed pre-release soft feedback and preserve provider/webhook blocks. No provider request. A note is optional. |
 | `Bouncy.forget!(address)` | Delete local state and events, including release metadata; no provider mutation. A later sync can reimport the address. |
@@ -94,6 +96,23 @@ The override applies to status and predicates as well as scopes. Your app must p
 | `Bouncy.unblocked { ... }` | Temporarily bypass interception for synchronous delivery in this execution context. Does not travel with queued jobs. |
 | `Bouncy.hold(address) { ... }` | Hold the address while the block runs, and inside a transaction until it ends, so no Bouncy write to it commits between the app's own check and its send. Returns the block's value. See [a sender that checks and sends](delivery.md#a-sender-that-checks-and-sends-in-one-step). |
 
+## Imports
+
+`Bouncy.import!` carries a block from another system, such as the suppression table an app kept before Bouncy. `Bouncy.block!` stays a support action: it holds the address now, needs a note and calls `after_block`. An import records what another system already knew:
+
+```ruby
+Bouncy.import!("ada@example.com", reason: :complaint, at: Time.utc(2025, 3, 1), note: "Carried from the old table", actor: "carry-task")
+```
+
+- A `:hard_bounce` or `:complaint` becomes the same evidence as a webhook block. It drops mail under the same rule (a fresh sync, or `require_fresh_sync = false`), and a sync clears it under the same [absence rule](amazon-ses.md#failure-and-ordering) as webhook evidence. A `:manual` block becomes a manual hold, which applies whatever the sync state and only a release clears.
+- `at` is the time the other system recorded the block, a `Time` or `DateTime` of any age: `maximum_event_age` applies to webhook feedback only. A time more than five minutes ahead raises `ArgumentError`. It becomes `Status#blocked_at` unless the address was blocked earlier.
+- It writes one `imported` event (source `import`, occurred at `at`) and calls no hook: not `after_event`, `after_block` or `on_notification`. It is not new evidence.
+- The same address, reason and time again writes nothing. So does an import that the address already holds.
+- It never weakens a block in force. A complaint outranks a hard bounce, an earlier hold keeps its time and note, and provider evidence and soft holds stay as they are.
+- A release at or after `at` fences it: the import records an `imported` event with `ignored_for_policy` and changes nothing. A newer block applies.
+
+`Bouncy::Ingestor` and `Bouncy::Observation` are internal: they record webhook feedback. Their 0.2.0 call shape still works in 0.2.x, but carry blocks with `Bouncy.import!`.
+
 ## SES notifications
 
 `config.on_notification` receives a `Bouncy::Notification` for every SES notification on an authorized topic, Send and Delivery included:
@@ -126,4 +145,4 @@ All gem errors inherit from `Bouncy::Error`:
 | `AuthenticationError` | SNS authorization/signature failure. |
 | `MalformedMessage` | Invalid SNS input. |
 
-Missing support notes, unsupported release destinations and `Bouncy.hold` without a block raise `ArgumentError`. An address lock that waits too long raises `ActiveRecord::LockWaitTimeout`. Rails/database errors not recognized as connection outages are not silently swallowed. A successful local database transaction does not make remote provider operations atomic. Never display a recovery success message from a rescue branch.
+Missing support notes, unsupported release destinations, an import reason or time that is not supported, and `Bouncy.hold` without a block raise `ArgumentError`. An address lock that waits too long raises `ActiveRecord::LockWaitTimeout`. Rails/database errors not recognized as connection outages are not silently swallowed. A successful local database transaction does not make remote provider operations atomic. Never display a recovery success message from a rescue branch.

data/guides/compatibility.md

@@ -6,6 +6,12 @@ The v0.1.0 release run on September 9, 2026 passed all 54 combinations using Rub
 
 The v0.2.0 local run on October 25, 2026 passed all 54 combinations with the same Ruby, Rails, PostgreSQL and MySQL versions and SQLite 3.54.1, and the same 18 again with Rails 8.0.2, the oldest 8.0 release the transactional-fixture support was checked on: 201 tests on SQLite (one skipped there: a second pool cannot share an in-memory database), 220 on PostgreSQL and 219 on MySQL with Rails 8.1, one fewer with Rails 7.2 and 8.0, and at least 96.5% line and 91.5% branch coverage. It adds the address-lock tests with real connections on PostgreSQL and MySQL. No live SES run was part of it.
 
+The v0.2.2 local run on October 26, 2026 used Ruby 3.3.5 and Rails 8.1 only: 236 tests on SQLite (one skipped, as before), 256 on PostgreSQL and 255 on MySQL, all passing. It adds tests for adapters that subclass a Rails adapter under another name, with the suite's own connection renamed `"PostGIS"` on PostgreSQL. No live SES run and no run on the PostGIS adapter itself was part of it.
+
+## Database adapters
+
+Bouncy knows a database by its Active Record adapter class. An adapter that subclasses `PostgreSQLAdapter`, `AbstractMysqlAdapter` or `SQLite3Adapter` belongs to that database whatever `adapter_name` it reports. The PostGIS adapter (`activerecord-postgis-adapter`) reports `"PostGIS"` and gets everything PostgreSQL gets: advisory locks, the isolation check, JSONB and native UUIDs. An adapter that is no such subclass is known by its name: one that contains `postg`, `mysql`, `trilogy` or `sqlite`. Any other adapter raises `Bouncy::ConfigurationError` at its first lock. The suite runs MySQL through `mysql2` only; the Trilogy adapter shares `AbstractMysqlAdapter` with it and is recognised by its class and its name, but no suite run uses it.
+
 The runtime JSON gem is constrained below version 3 because the supported Rails releases still pass a positional options hash to `JSON.parse`. Optional AWS SDKs load lazily and are host dependencies. There is no database or AWS lookup during boot.
 
 ## Migrations
@@ -25,11 +31,11 @@ Without a setting, Rails chooses its standard primary key. Explicit bigint/integ
 
 | Database | JSON storage | JSON defaults | UUID storage |
 |---|---|---|---|
-| PostgreSQL | JSONB | Database and model defaults | Native UUID |
+| PostgreSQL, PostGIS included | JSONB | Database and model defaults | Native UUID |
 | MySQL 8.4 | JSON | Model defaults; no literal SQL JSON default | 36-character string |
 | SQLite | JSON | Database and model defaults | 36-character string |
 
-The gem's JSON attributes inherit the database's native type. Every new record gets an independent hash/array default. No adapter probe or attribute-schema query is performed at boot. Unsupported database adapters raise before reconciliation.
+The gem's JSON attributes inherit the database's native type. Every new record gets an independent hash/array default. No adapter probe or attribute-schema query is performed at boot. Unsupported database adapters raise before reconciliation. Before 0.2.2 the migration made JSON columns and 36-character string keys on PostGIS; those tables keep working.
 
 MySQL identity columns explicitly use `utf8mb4_bin`. Case/accent-insensitive equality must not collapse addresses beyond Bouncy's trimmed lowercase policy. Scope and address limits keep compound indexes within supported database key limits. Use an application-normalized host column for model scopes.
 

data/guides/configuration.md

@@ -28,7 +28,7 @@ Replace the examples with your actual deployment. Set `all_sending_paths_listed`
 | `webhook_blocking` | `:cautious` with `require_fresh_sync`, `:strict` without | Which notifications block. `:cautious` blocks General/NoEmail bounces and complaints naming one recipient; the sync covers the rest. `:strict` blocks every Permanent bounce and every recipient a complaint names. See [bounce handling](bounce-handling.md#ses-event-classification). |
 | `record_deliveries` | `false` | Record normalized per-recipient SES Delivery events when enabled and routed to the topic. Server acceptance is not inbox placement. |
 | `retention` | `90.days` | Delete events older than this by local creation time when the prune job runs. Does not delete state rows. |
-| `maximum_event_age` | `90.days` | Feedback older than this cannot apply a new restriction. Retention must be at least this long; both must be positive. |
+| `maximum_event_age` | `90.days` | Webhook feedback older than this cannot apply a new restriction. `Bouncy.import!` and `Bouncy.block!` do not use it. Retention must be at least this long; both must be positive. |
 | `soft_bounce_threshold` | `nil` | Record-only by default. An integer from 1 to 50 enables escalation for repeated `MailboxFull` bounces. |
 | `soft_bounce_window` | `30.days` | Positive rolling window of eligible occurrence times. |
 | `soft_bounce_block_for` | `30.days` | Positive duration of the temporary local hold triggered by escalation. |

data/guides/delivery.md

@@ -32,7 +32,7 @@ Order.transaction do
 end
 ```
 
-`Bouncy.hold` takes a shared lock for the address. Every Bouncy write to that address (webhook, sync, `block!`, `release!`) takes it exclusively first, before any row lock, until its own transaction ends. A new block therefore commits before the check or after the send. Inside a transaction the hold lasts until that transaction ends, so the outcome commits before the block. Take your own row locks before the hold, as above.
+`Bouncy.hold` takes a shared lock for the address. Every Bouncy write to that address (webhook, sync, `block!`, `import!`, `release!`) takes it exclusively first, before any row lock, until its own transaction ends. A new block therefore commits before the check or after the send. Inside a transaction the hold lasts until that transaction ends, so the outcome commits before the block. Take your own row locks before the hold, as above.
 
 | Database | Lock | Two senders to one address |
 |---|---|---|

data/guides/migrating.md

@@ -3,12 +3,13 @@
 Migration and cutover belong in the implementing app. Bouncy's install migration creates its own two tables; it does not inspect application models or silently replace an existing webhook/interceptor.
 
 1. Inventory every existing writer: webhook controllers, jobs, support actions, interceptors and console operations. Record the source account, region, reason mapping, timestamps and existing soft-hold policy.
-2. Install the additive schema. Write a host data migration using migration-local ActiveRecord classes or explicit SQL pinned to that schema. Never call live Bouncy/host models, callbacks, jobs or AWS from a historical migration.
-3. Preserve manual holds independently. Map complaints as complaints and hard bounces as hard bounces. Account-list refusal is evidence of an existing restriction. Soft trackers are history; active legacy soft holds require an explicit preserved policy, not an accidental new threshold engine. Preserve original expiries for timed soft holds. Preserve indefinite holds as explicit manual holds with a migration note; do not invent a 30-day expiry. New escalation applies only to mailbox-specific evidence. Document that change if the old rule included content failures.
-4. Use stable source IDs to make imported events idempotent. Preserve known provider feedback IDs using Bouncy's recipient-level dedupe identity so retried historical feedback does not count again. Preserve distinct occurrences, exact provider addresses when available, and relevant event times. Missing historical case variants are resolved by complete provider enumeration before recovery.
-5. Rehearse the import against isolated synthetic fixtures. Compare every predicate, support action and customer-facing status that depended on the old table. Rehearse bootstrap as part of this isolated cutover sequence.
-6. Quiesce old writers for cutover, or implement and test dual-write delivery with deterministic identity. Perform the final import, switch the receiver/readers, then run `bouncy:bootstrap` before starting mail workers. It raises unless the mirror is fresh, complete and policy-verified. Ensure feedback received during the switch is retried or durably captured. Do not replace readers while another process continues writing exclusively to the old table.
-7. Rehearse rollback, including restrictions and releases created after cutover. Keeping an old table is not a rollback plan if it missed later changes. Keep old schema until the agreed window ends. Do not delete imported rows in a schema rollback: they may now contain newer state. Fail conflicting imports and stop writers before copying in either direction.
+2. Install the additive schema. Never call live Bouncy/host models, callbacks, jobs or AWS from a historical migration. Carry the blocks from a task instead (step 3); a migration that reads the old table uses migration-local ActiveRecord classes or explicit SQL pinned to its schema.
+3. Preserve manual holds independently. Map complaints as complaints and hard bounces as hard bounces. Carry each block with `Bouncy.import!(address, reason:, at:, note:, actor:)`, with `reason` `:hard_bounce`, `:complaint` or `:manual` and `at` the time the old table recorded it. Do not call `Bouncy::Ingestor`: it records webhook feedback, and feedback older than `maximum_event_age` blocks nothing. An import applies at any age and calls no hook. Run it from a task that you can run again, not from a historical migration: a repeat writes nothing, and an address released after `at` stays released. Account-list refusal is evidence of an existing restriction. Soft trackers are history; active legacy soft holds require an explicit preserved policy, not an accidental new threshold engine. Preserve original expiries for timed soft holds. Preserve indefinite holds as explicit manual holds with a migration note; do not invent a 30-day expiry. New escalation applies only to mailbox-specific evidence. Document that change if the old rule included content failures.
+4. `Bouncy.import!` identifies a block by four values: the normalized address (trimmed and lowercased), the configured scope, the reason, and `at` truncated to microseconds. A call that repeats all four writes nothing, so the old table needs no source ID of its own: read `at` from it unchanged, and a second run of the task writes nothing. A different reason or time is a different block, and the same values in another scope are an independent block. An import takes no provider feedback ID and counts no occurrences: carry the blocks in force, not each historical event. Pass the address as the old table spells it; for a bounce or a complaint, Bouncy keeps that spelling for the sync's provider lookups. Missing historical case variants are resolved by complete provider enumeration before recovery.
+5. Historical webhook feedback is a separate matter, and an import makes a replay unnecessary: it carries what that feedback decided. Bouncy has no public call to replay old notifications. Do not feed them to `Bouncy::Ingestor`: it is internal, and it records feedback older than `maximum_event_age` without blocking. Feedback that arrives during the switch reaches the receiver, which deduplicates each recipient by the provider's feedback ID, so SNS retries count once.
+6. Rehearse the import against isolated synthetic fixtures. Compare every predicate, support action and customer-facing status that depended on the old table. Rehearse bootstrap as part of this isolated cutover sequence.
+7. Quiesce old writers for cutover, or implement and test dual-write delivery with deterministic identity. Perform the final import, switch the receiver/readers, then run `bouncy:bootstrap` before starting mail workers. It raises unless the mirror is fresh, complete and policy-verified. Ensure feedback received during the switch is retried or durably captured. Do not replace readers while another process continues writing exclusively to the old table.
+8. Rehearse rollback, including restrictions and releases created after cutover. Keeping an old table is not a rollback plan if it missed later changes. Keep old schema until the agreed window ends. Do not delete imported rows in a schema rollback: they may now contain newer state. Fail conflicting imports and stop writers before copying in either direction.
 
 Use the app's existing public webhook URL where possible. Test routing alongside unrelated webhooks, and preserve the existing interception mode deliberately. Host admin resources call Bouncy's recovery API; stock row deletion cannot stand in for provider release.
 

data/guides/operations.md

@@ -78,7 +78,7 @@ Bouncy.configure do |config|
 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.
+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, except `imported` events: `Bouncy.import!` calls no hook. `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.
 

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, 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.
+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`. Webhook feedback older than that acceptance window can be recorded for diagnostics without applying a new restriction, then ages out under normal pruning. A block carried with `Bouncy.import!` is not feedback and applies at any age. 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/recovery.md

@@ -10,7 +10,7 @@ Bouncy obtains a complete supported-scope snapshot, finds the exact provider var
 
 A partial provider operation raises `Bouncy::ReleaseFailed`. Inspect `error.outcomes` or the `release_failed` event: some variants may have been removed while another failed. Local provider evidence remains blocked until a successful recovery/reconciliation. Remote calls cannot be rolled back with your database transaction.
 
-Inactive rows retain a release-time fence. Older feedback and stale snapshots cannot simply reapply the released evidence. A genuinely newer failure can block the address again. Provider changes after a completed observation remain possible; this is not a permanent deliverability guarantee.
+Inactive rows retain a release-time fence. Older feedback, stale snapshots and imports dated before the release cannot simply reapply the released evidence. A genuinely newer failure can block the address again. Provider changes after a completed observation remain possible; this is not a permanent deliverability guarantee.
 
 ## Local holds
 

data/lib/bouncy/address_lock.rb

@@ -170,7 +170,7 @@ module Bouncy
     # 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?
+      return unless Database.family(connection) == :postgresql && connection.transaction_open?
 
       isolation = connection.uncached { connection.select_value("SHOW transaction_isolation") }
       return if ["read committed", "read uncommitted"].include?(isolation)
@@ -181,11 +181,10 @@ module Bouncy
 
     # 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"
+      case Database.family!(connection)
+      when :postgresql then take_advisory(connection, key, exclusive)
+      when :mysql then take_named(connection, key)
+      when :sqlite then take_file(connection, exclusive ? File::LOCK_EX : File::LOCK_SH)
       end
     end
 

data/lib/bouncy/database.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Names the database family of a connection, which decides the lock Bouncy takes. A subclass
+  # of a Rails adapter belongs to the family of its parent class: the PostGIS adapter is a
+  # PostgreSQLAdapter whose adapter_name is "PostGIS", and the Trilogy and Mysql2 adapters share
+  # AbstractMysqlAdapter. The adapter_name is the fallback for an adapter that only renames
+  # itself. Each class is looked up only once its adapter is loaded, so no driver gem loads.
+  module Database
+    FAMILIES = {
+      postgresql: ["PostgreSQLAdapter", /postg/i],
+      mysql: ["AbstractMysqlAdapter", /mysql|trilogy/i],
+      sqlite: ["SQLite3Adapter", /sqlite/i]
+    }.freeze
+
+    module_function
+
+    # :postgresql, :mysql, :sqlite, or nil for any other database.
+    def family(connection)
+      FAMILIES.find { |_, (adapter, _)| subclass?(connection, adapter) }&.first ||
+        FAMILIES.find { |_, (_, name)| connection.adapter_name.match?(name) }&.first
+    end
+
+    def family!(connection)
+      family(connection) || raise(ConfigurationError, "Bouncy supports PostgreSQL, MySQL and SQLite")
+    end
+
+    def subclass?(connection, adapter)
+      ActiveRecord::ConnectionAdapters.const_defined?(adapter, false) &&
+        connection.is_a?(ActiveRecord::ConnectionAdapters.const_get(adapter, false))
+    end
+  end
+end

data/lib/bouncy/event.rb

@@ -9,7 +9,8 @@ module Bouncy
     scope :for, ->(email) { where(email: Identity.normalize(email)) }
     scope :recent, -> { order(occurred_at: :desc, id: :desc) }
 
-    after_create_commit :notify_host
+    # An import is not new evidence, so it calls no hook.
+    after_create_commit :notify_host, unless: -> { kind == "imported" }
 
     private
 

data/lib/bouncy/importer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Bouncy
+  # Records a block that another system recorded first, for Bouncy.import!.
+  #
+  # A bounce or a complaint becomes the same evidence that a webhook records, and a manual block
+  # becomes a manual hold. The time is the time the other system recorded the block. It is kept
+  # as given, however old: config.maximum_event_age is for webhook feedback that arrives late,
+  # and an old block that another system kept still stops mail.
+  #
+  # An import is not new evidence, so it calls no hook. It is idempotent: the same address,
+  # reason and time a second time writes nothing. It never removes or weakens a block that is
+  # in force, and a release recorded at or after its time fences it.
+  class Importer
+    REASONS = %w[hard_bounce complaint manual].freeze
+    FUTURE_SKEW = 5.minutes
+    # The attributes that an import can change. A difference in them is a change to record.
+    CHANGES = %w[manual_blocked_at manual_note event_blocked_at event_reason last_event_at blocked_at details].freeze
+
+    def call(email, reason:, at:, note:, actor:)
+      reason = reason.to_s
+      raise ArgumentError, "reason must be :hard_bounce, :complaint or :manual" unless REASONS.include?(reason)
+
+      time = time_of(at)
+      exact = email.to_s.strip
+      key = Identity.normalize(email)
+      dedupe_key = Digest::SHA256.hexdigest(JSON.generate(["import", Bouncy.scope, key, reason, time.iso8601(6)]))
+      Store.change(key) do |row|
+        next row if Bouncy.events.exists?(dedupe_key: dedupe_key)
+
+        record(row, reason, time, dedupe_key, exact: exact, note: note.to_s.strip.truncate(1000).presence,
+                                              actor: actor.to_s.truncate(200))
+      end
+    end
+
+    private
+
+    def record(row, reason, time, dedupe_key, exact:, note:, actor:)
+      was_blocked = row.blocked?
+      released_at = fence(row, reason)
+      fenced = !released_at.nil? && time <= released_at
+      unless fenced
+        before = row.attributes.slice(*CHANGES).deep_dup
+        reason == "manual" ? hold(row, time, note) : feedback(row, reason, time, exact)
+        row.blocked_at = [row.blocked_at, time].compact.min
+        return row if row.attributes.slice(*CHANGES) == before
+
+        row.summarize!
+      end
+      Store.event!("imported", email: row.email, source: "import", occurred_at: time, dedupe_key: dedupe_key, details: {
+                     "reason" => reason, "note" => note, "actor" => actor,
+                     "ignored_for_policy" => fenced, "became_blocked" => !was_blocked && row.blocked?
+                   })
+      row
+    end
+
+    # A release clears manual holds and records "soft_released_before". A provider release, or a
+    # sync that no longer finds webhook evidence, clears it and records released_before. An
+    # imported block at or before that time is older than the release, so it changes nothing.
+    def fence(row, reason)
+      return row.released_before unless reason == "manual"
+
+      Time.iso8601(row.details["soft_released_before"].to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # Keeps an earlier hold and its support note.
+    def hold(row, time, note)
+      return if row.manual_blocked_at && row.manual_blocked_at <= time
+
+      row.manual_note = note unless row.manual_blocked_at
+      row.manual_blocked_at = time
+    end
+
+    # Webhook evidence keeps the time of its newest block and the stronger reason: a complaint
+    # outranks a hard bounce, so an imported hard bounce never replaces a complaint.
+    def feedback(row, reason, time, exact)
+      previous = row.event_reason if row.event_blocked_at
+      return if previous == reason && row.event_blocked_at >= time
+      return if previous == "complaint" && row.event_blocked_at >= time
+
+      row.event_reason = previous == "complaint" ? "complaint" : reason
+      row.event_blocked_at = [row.event_blocked_at, time].compact.max
+      row.last_event_at = [row.last_event_at, time].compact.max
+      row.details = row.details.except("absence_count").reverse_merge("exact_email" => exact)
+    end
+
+    # Microsecond precision, as every supported database stores it, so a second import of the
+    # same time compares and deduplicates as equal.
+    def time_of(value)
+      raise ArgumentError, "at must be a Time" unless value.is_a?(Time) || value.is_a?(DateTime)
+
+      time = value.to_time.utc.floor(6)
+      raise ArgumentError, "at must not be in the future" if time > FUTURE_SKEW.from_now
+
+      time
+    end
+  end
+end

data/lib/bouncy/ingestor.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module Bouncy
+  # Internal: one webhook observation for Ingestor. See Ingestor.
   Observation = Data.define(:email, :kind, :provider_event_id, :message_id, :occurred_at, :details, :provider_reason, :status_code, :diagnostic)
 
+  # Internal: the receiver's step for one webhook observation. It is not a public API. Use
+  # Bouncy.import! to record a block from another system. The call shape of Ingestor#call and
+  # Observation stays the same in 0.2.x, because apps on 0.2.0 call them to carry blocks.
+  #
+  # config.maximum_event_age applies here only. It keeps a late webhook notification from
+  # blocking. Bouncy.import! and Bouncy.block! do not apply it.
   class Ingestor
     def call(observation)
       email = observation.email && Identity.normalize(observation.email)

data/lib/bouncy/scope_lock.rb

@@ -11,8 +11,8 @@ module Bouncy
     def synchronize
       Record.connection_pool.with_connection do |connection|
         key = Digest::SHA256.hexdigest(Bouncy.scope)[0, 15].to_i(16)
-        case connection.adapter_name
-        when "PostgreSQL"
+        case Database.family!(connection)
+        when :postgresql
           # Uncached: a cached answer would report the lock without taking it.
           acquired = connection.uncached { connection.select_value("SELECT pg_try_advisory_lock(#{key})") }
           raise ProviderError, "Another sync holds this scope lock" unless [true, "t"].include?(acquired)
@@ -22,7 +22,7 @@ module Bouncy
           ensure
             connection.execute("SELECT pg_advisory_unlock(#{key})")
           end
-        when /Mysql|Trilogy/i
+        when :mysql
           name = Digest::SHA256.hexdigest("bouncy:#{connection.pool.db_config.database}:#{Bouncy.scope}")
           acquired = connection.uncached { connection.select_value("SELECT GET_LOCK('#{name}', 0)") }
           raise ProviderError, "Another sync holds this scope lock" unless acquired == 1
@@ -32,7 +32,7 @@ module Bouncy
           ensure
             connection.execute("SELECT RELEASE_LOCK('#{name}')")
           end
-        when "SQLite"
+        when :sqlite
           database = connection.pool.db_config.database
           path = database == ":memory:" ? File.join(Dir.tmpdir, "bouncy-#{Process.pid}-#{key}.lock") : "#{File.expand_path(database)}.bouncy-#{key}.lock"
           File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
@@ -44,8 +44,6 @@ module Bouncy
               file.flock(File::LOCK_UN)
             end
           end
-        else
-          raise ConfigurationError, "Bouncy supports PostgreSQL, MySQL and SQLite"
         end
       end
     end

data/lib/bouncy/status.rb

@@ -29,6 +29,9 @@ module Bouncy
     def blocked? = @row ? @row.blocked? : false
     def reasons = @row ? @row.reasons : []
     def reason = (%i[complaint hard_bounce provider_list manual soft_bounces] & reasons).first
+    # The time the block in force began: when the address became blocked here, or the at: time
+    # of the Bouncy.import! that blocked it. nil when the address is not blocked.
+    def blocked_at = blocked? ? @row.blocked_at : nil
     def observed_at = @row&.provider_checked_at || @row&.last_event_at
     def provider_updated_at = @row&.provider_entries&.filter_map { |entry| Time.iso8601(entry.fetch("provider_updated_at")) }&.max
     def last_event = @row && Bouncy.events.for(@row.email).recent.first

data/lib/bouncy/store.rb

@@ -17,7 +17,11 @@ module Bouncy
           row = Suppression.find_or_create_by!(scope: Bouncy.scope, email: key) do |record|
             record.provider = Bouncy.configuration.provider.to_s
           end
-          row.with_lock { yield row }
+          row.with_lock do
+            # A soft hold that ran out leaves its start in blocked_at. The next block starts anew.
+            row.blocked_at = nil unless row.blocked?
+            yield row
+          end
         end
       rescue ActiveRecord::RecordNotUnique, ActiveRecord::StaleObjectError, ActiveRecord::Deadlocked
         attempts += 1

data/lib/bouncy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bouncy
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/bouncy.rb

@@ -48,7 +48,7 @@ module Bouncy
     # True when config.scope is set. An unconfigured Bouncy is inactive: it intercepts nothing,
     # reports no restrictions and returns empty relations, so a host can install the gem before
     # its environment variables exist without breaking mail delivery. Explicit operations
-    # (sync!, block!, release!, forget!) still raise ConfigurationError.
+    # (sync!, block!, import!, release!, forget!) still raise ConfigurationError.
     def configured? = configuration.configured?
 
     def unconfigured!(operation)
@@ -132,6 +132,14 @@ module Bouncy
       end
     end
 
+    # Records a block that another system recorded at the time at, for an app that moves its own
+    # suppression table to Bouncy. reason is :hard_bounce, :complaint or :manual. A bounce or a
+    # complaint is the same evidence as a webhook block; a manual block is a manual hold. The
+    # time can be of any age. The import calls no hook, writes nothing when it repeats, never
+    # weakens a block in force, and changes nothing when a release came at or after its time.
+    # Returns the suppression row. Does not call the provider.
+    def import!(email, reason:, at:, note: nil, actor: nil) = Importer.new.call(email, reason: reason, at: at, note: note, actor: actor)
+
     def forget!(email)
       current_scope = scope
       key = Identity.normalize(email)
@@ -165,7 +173,7 @@ module Bouncy
     # committed state: a REPEATABLE READ snapshot from before the hold cannot hide a newer block
     # or release. PostgreSQL at READ COMMITTED reads the latest state with every statement.
     def current_state(relation)
-      return relation unless AddressLock.holding? && Record.connection_pool.with_connection(&:adapter_name).match?(/Mysql|Trilogy/i)
+      return relation unless AddressLock.holding? && Record.connection_pool.with_connection { |connection| Database.family(connection) } == :mysql
 
       relation.lock("LOCK IN SHARE MODE")
     end
@@ -193,6 +201,7 @@ end
 
 require_relative "bouncy/configuration"
 require_relative "bouncy/identity"
+require_relative "bouncy/database"
 require_relative "bouncy/record"
 require_relative "bouncy/suppression"
 require_relative "bouncy/event"
@@ -205,6 +214,7 @@ require_relative "bouncy/providers/ses"
 require_relative "bouncy/providers/ses_parser"
 require_relative "bouncy/notification"
 require_relative "bouncy/ingestor"
+require_relative "bouncy/importer"
 require_relative "bouncy/recovery"
 require_relative "bouncy/scope_lock"
 require_relative "bouncy/reconciler"

data/lib/generators/bouncy/templates/create_bouncy_tables.rb.erb

@@ -87,11 +87,25 @@ class CreateBouncyTables < ActiveRecord::Migration<%= migration_version %>
     mysql? ? { collation: "utf8mb4_bin" } : {}
   end
 
-  def postgresql?
-    connection.adapter_name.downcase.include?("postgres")
+  def postgresql? = adapter_family == :postgresql
+  def mysql? = adapter_family == :mysql
+
+  # Mirrors Bouncy::Database.family. It is inlined because the migration must not depend on
+  # Bouncy's code when it runs. Every adapter class comes before any name: a subclass of a Rails
+  # adapter keeps the family of its parent class whatever it reports, as the PostGIS adapter
+  # reports "PostGIS". The name is the fallback for an adapter that only renames itself.
+  def adapter_family
+    families = {
+      postgresql: ["PostgreSQLAdapter", /postg/i],
+      mysql: ["AbstractMysqlAdapter", /mysql|trilogy/i],
+      sqlite: ["SQLite3Adapter", /sqlite/i]
+    }
+    families.find { |_, (adapter, _)| adapter_subclass?(adapter) }&.first ||
+      families.find { |_, (_, name)| connection.adapter_name.match?(name) }&.first
   end
 
-  def mysql?
-    connection.adapter_name.downcase.match?(/mysql|trilogy/)
+  def adapter_subclass?(adapter)
+    ActiveRecord::ConnectionAdapters.const_defined?(adapter, false) &&
+      connection.is_a?(ActiveRecord::ConnectionAdapters.const_get(adapter, false))
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bouncy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - rameerez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -79,9 +79,11 @@ files:
 - lib/bouncy/address_lock.rb
 - lib/bouncy/body_limit.rb
 - lib/bouncy/configuration.rb
+- lib/bouncy/database.rb
 - lib/bouncy/engine.rb
 - lib/bouncy/event.rb
 - lib/bouncy/identity.rb
+- lib/bouncy/importer.rb
 - lib/bouncy/ingestor.rb
 - lib/bouncy/interceptor.rb
 - lib/bouncy/model.rb