hailer 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00f5d9ebd2dd587d6f2824487642a03c4d9bef5c6047d3f898975199b6c89745
-  data.tar.gz: 6580ca42145825de17fa3096eabf5b13d76f863e62a27a6ed86dfe56c4e0e6a7
+  metadata.gz: c8cd926b627c51b8e8c96b95ad79bb68b8fbba9c4ca26ab466f03f41283cc35b
+  data.tar.gz: 7a4344f35eccd875fe2110aa10a35b0767d42c6acf025260c6813c732e644cb8
 SHA512:
-  metadata.gz: 3c50b744278952684d7b5984eab32a927885c591202be50fd734a44adca9661a2119573888fd954d91a5174294616aa8b40aa4207332864c4c9e26baa0968314
-  data.tar.gz: 73455d8ee3c97a0e948c6b9dab75a5f0ea2efdff910417c60f7996d84c197c4c2adc1ffd0ef51de21b3512c55aeab24c00772290f2c244f74e9280b9d191b406
+  metadata.gz: 5b9aeebb39e331fb930cfcce8a7063d28a33fedf2314881bab62e469b4674286e807bffdd14b532d1db47199fcf1eb55f2b3cd0612cb1fcbbea2028430faf055
+  data.tar.gz: 7622c206fdfccefbee24a7c05952500c8e83a4fca3d0a84bbe05da2f3ebdf9eec4db1a37d6398f04639ed240c023ca2442f88295d83bd11f6ea41dd537a7860d

data/README.md

@@ -9,23 +9,38 @@ This repository is two things:
 - **`hailer` crate** — a standalone Rust mail ship, supervised by Mothership.
   SESv2 is the first provider.
 
-```text
-ActionMailer → hailer gem → private Mothership route → hailer binary → SES
+```mermaid
+flowchart LR
+    A[ActionMailer] --> B[hailer gem]
+    B --> C[private Mothership route]
+    C --> D[hailer binary]
+    D --> E[SES]
 ```
 
 An **opt-in durable queued adapter** sits alongside the default synchronous
-send path. See [durable delivery](docs/durable-delivery.md) for ownership,
-recovery, routing and operator controls.
+send path (`[queued]` in `hailer.example.toml`).
 
-## Rails
-
-Requires Ruby 4.0+ and Rails 8.1 or newer within Rails 8.x.
-Rails main (8.2 alpha) is also exercised in CommonShare. Older releases are not supported.
+## Install
 
 ```ruby
+gem "guardship"
+gem "shuttlebay"
 gem "hailer"
 ```
 
+Mothership picks up the bay and starts sending mail. Keep using your
+mailers, interceptors, observers, `deliver_now`, and `deliver_later` -
+nothing else about how Rails sends mail changes.
+
+Everything past this point is reference material: protocol internals,
+TOML knobs, and operator commands for people running or debugging the
+service, not required reading to use it.
+
+## Rails
+
+Requires Ruby 4.0+ and Rails 8.1 or newer within Rails 8.x.
+Rails main (8.2 alpha) is also exercised. Older releases are not supported.
+
 The Railtie registers and selects Hailer automatically. Set the private service
 URL in the Rails process's environment:
 
@@ -50,11 +65,9 @@ when omitted from `hailer_settings`. There is no default host or fallback to SES
 The app can explicitly override the default, for example
 `config.action_mailer.delivery_method = :test` in its test environment.
 
-Keep using your mailers, interceptors, observers, `deliver_now`, and
-`deliver_later`. Rails still owns job scheduling. The adapter sends rendered MIME
-and separate envelope recipients, preserving explicit `smtp_envelope_from` and
-`smtp_envelope_to` overrides. After SES accepts the message, it sets
-`message.header[:ses_message_id]`.
+The adapter sends rendered MIME and separate envelope recipients, preserving
+explicit `smtp_envelope_from` and `smtp_envelope_to` overrides. After SES
+accepts the message, it sets `message.header[:ses_message_id]`.
 
 ## Rust service
 
@@ -120,8 +133,12 @@ shutdown timeout. PostgreSQL 18 is exercised locally and in CI.
 
 ## Bounces, complaints, and suppressions
 
-```text
-SES → SNS → dedicated SQS queue → Hailer → durable events + suppressions
+```mermaid
+flowchart LR
+    A[SES] --> B[SNS]
+    B --> C[dedicated SQS queue]
+    C --> D[Hailer]
+    D --> E[durable events + suppressions]
 ```
 
 Hailer atomically commits each event, deduplication key, and suppression change
@@ -133,7 +150,7 @@ are left for SQS's dead-letter policy.
 - Transient/undetermined bounces are recorded without permanent suppression.
 - An explicit `not-spam` complaint does not create a new suppression.
 - Suppression checks cover the actual To/Cc/Bcc envelope, including overrides.
-  Matching preserves CommonShare's case/plus-alias policy.
+  Matching is case-insensitive and ignores `+alias` tags.
 - Mixed messages keep allowed recipients and their original addresses; MIME
   is unchanged. If every recipient is suppressed, Hailer returns HTTP 422
   without calling SES. A suppression lookup failure fails closed with HTTP 503.
@@ -223,11 +240,16 @@ the section disables scheduled sync, not existing suppression enforcement.
 ### Control plane
 
 The behavior circuit evaluates **pure admission decisions**: input validity,
-service/storage readiness, suppression, and local rate admission. PostgreSQL,
+service/storage readiness, suppression, and rate admission. PostgreSQL,
 AWS calls, clocks, and token reservations remain owned by the async host.
 The SES circuit breaker counts transient/ambiguous failures, not bad addresses
 or permanent request rejections. An optional `[rate_limit]` budgets envelope
-recipients **per process**, not per account; it does not discover SES quotas.
+recipients through a single shared Postgres-backed token bucket - every
+replica draws down the same account-wide budget, not an independent
+per-process one. `discover_from_aws = true` replaces the configured rate
+with the SES account's real `SendQuota.MaxSendRate`, re-checked
+periodically; a rate-state read/write failure fails closed (denies
+admission) rather than risk exceeding the real AWS quota blind.
 
 Private `GET /internal/mail/health` returns sanitized component states and
 counters. `GET /internal/mail/ready` returns 503 during initial sync or storage
@@ -258,8 +280,13 @@ turn off.
 
 ## Domain blocklist
 
-```text
-SendRequest -> impossible-address check -> domain blocklist (free, local) -> suppression (free, local) -> verification (paid, external) -> SES
+```mermaid
+flowchart LR
+    A[SendRequest] --> B[impossible-address check]
+    B --> C["domain blocklist<br/>(free, local)"]
+    C --> D["suppression<br/>(free, local)"]
+    D --> E["verification<br/>(paid, external)"]
+    E --> F[SES]
 ```
 
 Always active - an empty `hailer.domain_blocks` table is a no-op, there is
@@ -280,8 +307,11 @@ cannot be removed this way, by design.
 
 ## Address verification
 
-```text
-SendRequest -> suppression check (cheap, local) -> address verification (paid, external) -> SES
+```mermaid
+flowchart LR
+    A[SendRequest] --> B["suppression check<br/>(cheap, local)"]
+    B --> C["address verification<br/>(paid, external)"]
+    C --> D[SES]
 ```
 
 Opt-in pre-send deliverability check, off by default. Enable with
@@ -408,19 +438,6 @@ each test creates and drops its own database. Never point this variable at a
 customer or Rails production database. Neither suite sends real mail or requires
 AWS credentials.
 
-For the opt-in CommonShare compatibility smoke, create a disposable Hailer
-database, then run from that application's checkout:
-
-```sh
-RAILS_ENV=test HAILER_SMOKE_BINARY=/path/to/hailer/target/debug/hailer \
-  HAILER_DATABASE_URL=postgres://test_user:password@127.0.0.1/hailer_smoke \
-  bundle exec rails runner /path/to/hailer/test/commonshare_smoke.rb
-```
-
-It refuses a non-test app database, points the AWS SDK at a loopback fixture,
-and rolls back application-history changes. It does not change the app's
-dependency lockfile or send external mail.
-
 `HAILER_BINARY` is an explicit, version-checked source-build override; there is
 no download or PATH fallback.
 

data/hailer.example.toml

@@ -12,10 +12,16 @@ shutdown_timeout_seconds = 30
 [suppression_sync]
 interval_seconds = 3600
 
-# Optional PER-PROCESS budget, not an account-wide SES quota.
+# Optional. Shared across every replica (one Postgres-backed token bucket,
+# not a per-process budget) - a second replica cannot double the admitted rate.
 # [rate_limit]
 # recipients_per_second = 10.0
 # burst = 50
+# Replace recipients_per_second with the SES account's real
+# SendQuota.MaxSendRate, re-checked periodically. recipients_per_second/burst
+# above become just the seed used until the first successful discovery.
+# discover_from_aws = true
+# discovery_interval_seconds = 900
 
 # Durable intake requires explicit logical payload budgets.
 # [queued]

data/lib/hailer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hailer
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hailer
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -123,6 +123,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: padded_cell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -149,7 +163,6 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- docs/durable-delivery.md
 - exe/hailer
 - hailer.example.toml
 - lib/hailer.rb

data/docs/durable-delivery.md

@@ -1,214 +0,0 @@
-# Durable delivery
-
-The queued Ruby interface, PostgreSQL spool and supervised dispatcher are
-implemented and shipped (0.3.0+). It is opt-in: absent `[queued]` config,
-Hailer stays on the synchronous send path and none of this runs.
-
-## Opt-in Rails configuration
-
-Keep `HAILER_URL` pointing to the existing private `/internal/mail/send` endpoint.
-The queued client uses the same validated origin with `/internal/mail/messages`.
-
-```ruby
-# config/environments/production.rb
-config.action_mailer.delivery_method = :hailer_queued
-```
-
-The initializer registers the adapter and selects `Hailer::MailDeliveryJob` for
-this opt-in configuration. The default remains the synchronous `:hailer`
-adapter, whose HTTP requests never retry.
-
-For a per-mailer opt-in, select both:
-
-```ruby
-self.delivery_method = :hailer_queued
-self.delivery_job = Hailer::MailDeliveryJob
-```
-
-An explicitly configured application delivery job is not replaced. It must
-inherit `Hailer::MailDeliveryJob` or include `Hailer::DeliveryJobContext` to
-obtain stable submission keys across job retries. This uses public ActiveJob
-callbacks, not Rails monkey patches.
-
-## Identities and retries
-
-- Standard queued jobs use job ID plus delivery ordinal. Different jobs are
-  different intents unless the application supplies a business key.
-- Direct `deliver_now` calls generate a fresh key per invocation.
-- Supply a business key through `delivery_method_options` when separate calls
-  represent the same intended message:
-
-  ```ruby
-  mail(
-    to: recipient,
-    subject: 'Invoice',
-    delivery_method_options: { submission_key: "invoice:#{invoice.id}:issued" }
-  )
-  ```
-
-- Supply an optional ISO 8601 `expires_at` through those same options. The
-  service contract defaults to 24 hours and allows shorter deadlines.
-- A queued intake call serializes its command once. Up to three HTTP attempts
-  reuse those exact bytes, key and deadline after transport loss or retryable
-  admission errors (429/503). Set `intake_attempts: 1` to disable these retries.
-- Validation, submission conflicts, malformed responses and provider-unknown
-  errors do not retry.
-- Rails re-renders mail when a job is performed again. If the bytes or envelope
-  change under an accepted key, the service must return a conflict; the adapter
-  raises `Hailer::SubmissionConflictError`. Job keys alone do not provide
-  transparent exactly-once business delivery.
-
-Submission keys are command metadata, not MIME headers.
-
-## Private status and lifecycle feed
-
-```ruby
-client = Hailer::LifecycleClient.new # same HAILER_URL origin
-status = client.status(hailer_message_id)
-page = client.poll(after: saved_cursor, limit: 100)
-```
-
-Status distinguishes the original RFC Message-ID, Hailer ID and provider ID,
-and never returns MIME. `status.attempts` and `status.recipient_outcomes` contain
-the latest 100 records each, in chronological order. Their corresponding
-`*_truncated` flags report older records; use the lifecycle feed for complete
-observations. An accepted message can still have an uncertain historical
-attempt after an operator-authorized retry. Lifecycle events have their own cursor space; do not
-reuse an existing `FeedbackClient` cursor. Persist `page.next_cursor` only after
-processing the page successfully. Re-reading a cursor does not delete events.
-
-The service's `[queued]` configuration requires explicit `max_bytes` and
-`max_messages`. Bytes measure canonical logical command payload, not PostgreSQL
-table/index/WAL/backups or a physical disk quota. All replicas of a deployment
-must use the same budgets. Admission is transactional; a replay does not consume
-another slot, and accepted messages are never evicted to admit new ones.
-
-## Acceptance is not delivery
-
-HTTP 202 means the service durably owns the message. The adapter exposes its ID
-through `message.header[:hailer_message_id]` before Rails observers run. It does
-not fabricate `ses_message_id`; provider acceptance and recipient delivery
-are later observations.
-
-Application observers must distinguish durable ownership from provider
-acceptance: persist the Hailer ID and an owned/queued state, then consume
-lifecycle facts separately. CommonShare's existing observer still writes
-`status: "sent"` and only the SES ID for every delivered callback. The isolated
-queued smoke verifies transport compatibility, not that observer's readiness
-for production opt-in. Keep its synchronous configuration until this application
-cutover work is done.
-
-Unknown provider outcomes are held without an automatic resend. Seven-day
-unknown-body retention (measured from durable intake) does not extend the
-24-hour send-start deadline. Body purge retains receipts and uncertainty.
-Only positive evidence of no acceptance permits automatic retry, with jittered
-backoff capped at 600 seconds and at most 255 automatic attempts per intent.
-Expiry stops new attempts; it never proves a previous attempt was unsent.
-
-Live bodies are purged after confirmed acceptance, terminal rejection or
-suppression, cancellation, or safe queued expiry. Purge releases logical
-capacity, not PostgreSQL allocated disk, backups or copies already in-flight.
-
-## Feedback and private routing
-
-Set root `ses_configuration_set = "hailer-feedback"` in Hailer's TOML, or use
-an equivalent default configuration set on the SES sending identity. Configure
-SES event publishing through the dedicated SNS/SQS feedback route, preserving
-`mail.tags.hailer_message_id` and `mail.tags.hailer_attempt_id`. These unique tags
-allow feedback to resolve an unknown SDK response. A provider ID already
-captured from an accepted response also correlates later untagged feedback.
-Without tags and without a captured provider ID, feedback cannot resolve
-uncertainty. Hailer never guesses from recipient, timestamps or RFC Message-ID.
-Feedback received before an untagged provider ID is captured is not retroactively
-correlated; retain the tags for reliable recovery.
-
-Mothership must route the new private paths as well as the old synchronous
-ones. A suitable bind pattern is:
-
-```toml
-routes = [{ bind = "mail", pattern = "^/internal/mail/(send|events|health|ready|intake-ready|dispatch-ready|messages|messages/events|messages/[0-9a-f-]{36})$" }]
-```
-
-Keep this bind private. Intake readiness depends on durable writable capacity,
-not SES health. `/internal/mail/dispatch-ready` separately reports worker,
-bootstrap and control eligibility. Neither readiness response guarantees that
-a later send will succeed.
-
-## Operator control
-
-Run against the intended database using the same `HAILER_DATABASE_URL`:
-
-```sh
-hailer message-status --id MESSAGE_UUID
-hailer cancel-message --id MESSAGE_UUID --reason "intent withdrawn"
-hailer resolve-message --id MESSAGE_UUID --outcome accepted \
-  --provider-message-id VERIFIED_SES_ID --reason "verified provider evidence"
-hailer resolve-message --id MESSAGE_UUID --outcome not-accepted \
-  --reason "verified no provider acceptance"
-hailer resolve-message --id MESSAGE_UUID --outcome retry \
-  --acknowledge-duplicate-risk --reason "investigated; accept duplicate risk"
-```
-
-Cancellation is only possible before dispatch and cannot unsend mail.
-Resolution defaults to the current held-unknown attempt. Use `--attempt-id
-ATTEMPT_UUID` to resolve an older unknown journal entry without overwriting a
-later attempt. Retry is allowed only for the current held intent, with an
-available body, an unexpired deadline, no acceptance latch and explicit
-duplicate-risk acknowledgement. A new attempt never erases the old uncertainty.
-All decisions require an audit reason. After expiry or body purge, sending
-requires a new intent/key.
-
-## Quarantine
-
-Opt-in, queued pipeline only - a synchronous `:hailer` send has no way to
-hold a message for later review, so a non-ASCII domain or a newly
-registered one makes the synchronous adapter reject outright. The queued
-adapter holds instead:
-
-```toml
-[domain_intel]
-provider = "rdap"
-new_domain_threshold_days = 30
-```
-
-A recipient domain that is not plain ASCII (a malformed/unencoded IDN, or a
-homograph-spoofing attempt - legitimate IDNs are transmitted as ASCII
-punycode) is always checked, regardless of this block. `[domain_intel]`
-additionally checks the domain's RDAP registration date; newer than the
-threshold holds the message as `quarantined` instead of admitting it as
-`queued`. The whole message is quarantined, not just the flagged recipient -
-this is an operator review gate on intent, not a per-recipient filter like
-suppression or the domain blocklist (`hailer ban-domain`). RDAP's bootstrap
-registry is public; no credential is needed.
-
-```sh
-hailer release-quarantine --id MESSAGE_UUID --reason "reviewed, legitimate"
-hailer cancel-message --id MESSAGE_UUID --reason "rejected on review"
-```
-
-Releasing resets `next_attempt_at` to now, so the message re-enters the
-normal dispatch queue immediately. `cancel-message` also accepts a
-quarantined message. An unactioned quarantine still expires on the same
-deadline as a normal `queued` message.
-
-## Local application verification
-
-`test/commonshare_smoke.rb` runs inside CommonShare's test environment with a
-real Mothership bay and loopback SES, never real AWS credentials. Use a fresh
-loopback PostgreSQL database named `hailer_smoke_*` for each queued run.
-The script intentionally reuses one business key to check replay after purge.
-
-```sh
-RAILS_ENV=test DISABLE_BOOTSNAP=1 \
-HAILER_SMOKE_QUEUED=1 \
-HAILER_SMOKE_BINARY=/absolute/path/to/current/hailer \
-HAILER_DATABASE_URL=postgres://...@127.0.0.1:5432/hailer_smoke_queued \
-bundle exec rails runner /absolute/path/to/hailer/test/commonshare_smoke.rb
-```
-
-An isolated temporary `BUNDLE_GEMFILE` can select the working-tree gem or locally
-installed verification gem without editing CommonShare's Gemfile or lock.
-Set `HAILER_SMOKE_EXPECTED_PLATFORM=arm64-darwin` to assert native-gem selection.
-Omit `HAILER_SMOKE_QUEUED` for the unchanged synchronous contract. The test holds
-the provider response until Rails has its receipt, then checks the journal,
-correlation tags, envelope/attachment, body purge, replay, conflict and feeds.