hailer 0.5.0-aarch64-linux-gnu → 0.7.0-aarch64-linux-gnu

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3d322c9dae35216c1921037686ecd3701bcd4e09ee3f38c45d9464172b7e8a4a
4
- data.tar.gz: eb2ba40888b0cb6199adbc39831837f10e88ca43f82e752a1a60d4b9e1a89be5
3
+ metadata.gz: b0c5f231f176cab54e0f26a7de39d33c50dfa7891c6162ac73a2e107a39320e4
4
+ data.tar.gz: a5e763d2ebfb0e81fa28a1a29b09dc61573aa1dd9eba60b482546e36ed837592
5
5
  SHA512:
6
- metadata.gz: eb845f47bba9921af1d50bd460c746122b648baabdbb521280639e0e3a0b2c7abd12fd67abde7962a76f6e94df581b8bc98fb67d3f60b4382af66a791972b045
7
- data.tar.gz: 742bf867675f342890e22f65d7aaabd16d10967ffc78e9a09f52735c0d6dec69da4b279f42e19175c19c905979bcc4872dc536f415261b73b52896522dbf3873
6
+ metadata.gz: d9b18be2573f698c16259da7627147a96dcc18cab60495b5723934b1753033ae08672ace95be5af0d3bc062887b565c382144dc8b2c5140b6c45f73d333d0192
7
+ data.tar.gz: c5ae08edb42cef5031c54e21d76a5b121358f15d2367ee42c13c1dc41c87701ccefb3a773882c2f9e2acf337f8848caab7f1dc2179ea1b358d89f210df0c4763
data/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0
4
+
5
+ - Postmark provider (`provider = "postmark"`, `[postmark] message_stream`, `POSTMARK_SERVER_TOKEN`): Rails MIME parsed into Postmark's JSON, sync and queued sends, correlation as Metadata, `hailer postmark-server` token check. SES-only settings are refused with it.
6
+ - **Breaking for source builds:** providers are cargo features, `ses` and `postmark`; a build needs at least one, and platform gems carry both. A binary without the configured provider refuses to start and names the feature.
7
+ - The AWS SDK is gone: SESv2, SQS and STS go through hailer's own SigV4 client (verified against AWS's signing test suite) with env, shared-file, web identity, container and IMDSv2 credentials. The platform binary drops from 17 MiB to 9 MiB.
8
+ - HTTP clients (Postmark, Emailable, RDAP) moved from reqwest to rama, with rustls on ring; every request sends `user-agent: hailer/<version>`.
9
+ - Dependency requirements loosened to their compatibility boundary and upgraded (behavior-machines-circuit 0.3, base64 0.23, sha2 0.11).
10
+
3
11
  ## Working tree — durable delivery (unreleased)
4
12
 
5
13
  - Opt-in `:hailer_queued` Rails adapter with stable job keys and frozen intake retries.
data/README.md CHANGED
@@ -7,25 +7,40 @@ This repository is two things:
7
7
  - **`hailer` gem** — an ActionMailer adapter, feedback client, and executable
8
8
  launcher. Platform gems bundle the Rust binary. No Ruby AWS SDK or native extension.
9
9
  - **`hailer` crate** — a standalone Rust mail ship, supervised by Mothership.
10
- SESv2 is the first provider.
11
-
12
- ```text
13
- ActionMailer → hailer gem → private Mothership route → hailer binary → SES
10
+ Sends through SESv2 or Postmark.
11
+
12
+ ```mermaid
13
+ flowchart LR
14
+ A[ActionMailer] --> B[hailer gem]
15
+ B --> C[private Mothership route]
16
+ C --> D[hailer binary]
17
+ D --> E[SES]
14
18
  ```
15
19
 
16
20
  An **opt-in durable queued adapter** sits alongside the default synchronous
17
- send path. See [durable delivery](docs/durable-delivery.md) for ownership,
18
- recovery, routing and operator controls.
19
-
20
- ## Rails
21
+ send path (`[queued]` in `hailer.example.toml`).
21
22
 
22
- Requires Ruby 4.0+ and Rails 8.1 or newer within Rails 8.x.
23
- Rails main (8.2 alpha) is also exercised in CommonShare. Older releases are not supported.
23
+ ## Install
24
24
 
25
25
  ```ruby
26
+ gem "guardship"
27
+ gem "shuttlebay"
26
28
  gem "hailer"
27
29
  ```
28
30
 
31
+ Mothership picks up the bay and starts sending mail. Keep using your
32
+ mailers, interceptors, observers, `deliver_now`, and `deliver_later` -
33
+ nothing else about how Rails sends mail changes.
34
+
35
+ Everything past this point is reference material: protocol internals,
36
+ TOML knobs, and operator commands for people running or debugging the
37
+ service, not required reading to use it.
38
+
39
+ ## Rails
40
+
41
+ Requires Ruby 4.0+ and Rails 8.1 or newer within Rails 8.x.
42
+ Rails main (8.2 alpha) is also exercised. Older releases are not supported.
43
+
29
44
  The Railtie registers and selects Hailer automatically. Set the private service
30
45
  URL in the Rails process's environment:
31
46
 
@@ -50,11 +65,9 @@ when omitted from `hailer_settings`. There is no default host or fallback to SES
50
65
  The app can explicitly override the default, for example
51
66
  `config.action_mailer.delivery_method = :test` in its test environment.
52
67
 
53
- Keep using your mailers, interceptors, observers, `deliver_now`, and
54
- `deliver_later`. Rails still owns job scheduling. The adapter sends rendered MIME
55
- and separate envelope recipients, preserving explicit `smtp_envelope_from` and
56
- `smtp_envelope_to` overrides. After SES accepts the message, it sets
57
- `message.header[:ses_message_id]`.
68
+ The adapter sends rendered MIME and separate envelope recipients, preserving
69
+ explicit `smtp_envelope_from` and `smtp_envelope_to` overrides. After SES
70
+ accepts the message, it sets `message.header[:ses_message_id]`.
58
71
 
59
72
  ## Rust service
60
73
 
@@ -65,10 +78,22 @@ The source (`ruby`) gem has the same Rails client and launcher, but no binary.
65
78
  For source development or an unsupported platform:
66
79
 
67
80
  ```sh
68
- cargo install --path . --locked
81
+ cargo install --path . --locked --features ses,postmark
69
82
  export HAILER_BINARY=/absolute/path/to/hailer
70
83
  ```
71
84
 
85
+ Each provider is a cargo feature, and a build needs at least one. Platform
86
+ gems carry both. On glibc Linux the build needs libclang (`libclang-dev`):
87
+ rama generates its libresolv bindings with bindgen.
88
+
89
+ | Feature | Adds |
90
+ | --- | --- |
91
+ | `ses` | SES sending, SQS feedback, suppression sync, rate discovery, `ses-*` and `sync-suppressions` commands (hailer's own SigV4 client, no AWS SDK) |
92
+ | `postmark` | MIME parsing for Postmark's JSON API, `postmark-server` command |
93
+
94
+ A binary without the configured provider refuses to start and names the
95
+ feature to rebuild with.
96
+
72
97
  Run it as a Mothership HTTP bay. Merge this example into your fleet manifest;
73
98
  the bind must stay private and must not be routed on a public listener:
74
99
 
@@ -89,9 +114,43 @@ docking Unix socket; it does **not** run another HTTP server. For containers,
89
114
  use a private network listener with network policy instead of a loopback address
90
115
  if Rails runs in a different network namespace.
91
116
 
92
- Give the **service**, not the Rails adapter, AWS region and credentials through
93
- the standard AWS credential chain. Its identity needs `ses:SendEmail`, and the
94
- SES account/identities must be configured for sending.
117
+ Give the **service**, not the Rails adapter, AWS region and credentials. Hailer
118
+ looks where the AWS SDKs do, in this order: `AWS_ACCESS_KEY_ID` /
119
+ `AWS_SECRET_ACCESS_KEY` (+ `AWS_SESSION_TOKEN`); the shared `~/.aws/credentials`
120
+ and `~/.aws/config` files (`AWS_PROFILE`, static keys); an EKS web identity
121
+ (`AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN`); an ECS or EKS Pod Identity
122
+ container role; the EC2 instance role over IMDSv2. A profile that needs SSO,
123
+ `credential_process` or role chaining is refused with the key it uses. The
124
+ region comes from `AWS_REGION`, `AWS_DEFAULT_REGION`, the profile, or IMDS.
125
+ Its identity needs `ses:SendEmail`, and the SES account/identities must be
126
+ configured for sending.
127
+
128
+ ### Postmark
129
+
130
+ ```toml
131
+ provider = "postmark"
132
+
133
+ [postmark]
134
+ message_stream = "outbound" # the default
135
+ ```
136
+
137
+ Set `POSTMARK_SERVER_TOKEN` in the service's environment, never in
138
+ `hailer.toml`. `hailer postmark-server` checks the token and names its server.
139
+
140
+ Postmark's API takes JSON, not raw MIME, so Hailer parses the Rails message
141
+ and Postmark rebuilds it. Recipients, subject, text/HTML bodies, attachments
142
+ (inline images by `cid:`), Reply-To, `Message-ID` and other custom headers
143
+ carry over; the MIME structure itself does not. Recipients come from the
144
+ envelope, as with SES. An explicit `smtp_envelope_from` only stands in for a
145
+ missing From header: Postmark owns the bounce address.
146
+
147
+ The SES-only settings (`ses_configuration_set`, `[feedback]`,
148
+ `[suppression_sync]`, `rate_limit.discover_from_aws`) are refused with
149
+ `provider = "postmark"`. Postmark bounces and suppressions are not read yet,
150
+ so a queued unknown outcome waits for `hailer resolve-message`. Postmark
151
+ refuses a message (406, suppressed) only when every recipient is inactive in
152
+ its suppression list; otherwise it accepts and skips the inactive ones, which
153
+ Hailer logs as a warning with the count, never the addresses.
95
154
 
96
155
  ### PostgreSQL
97
156
 
@@ -120,8 +179,12 @@ shutdown timeout. PostgreSQL 18 is exercised locally and in CI.
120
179
 
121
180
  ## Bounces, complaints, and suppressions
122
181
 
123
- ```text
124
- SES → SNS → dedicated SQS queue → Hailer → durable events + suppressions
182
+ ```mermaid
183
+ flowchart LR
184
+ A[SES] --> B[SNS]
185
+ B --> C[dedicated SQS queue]
186
+ C --> D[Hailer]
187
+ D --> E[durable events + suppressions]
125
188
  ```
126
189
 
127
190
  Hailer atomically commits each event, deduplication key, and suppression change
@@ -133,7 +196,7 @@ are left for SQS's dead-letter policy.
133
196
  - Transient/undetermined bounces are recorded without permanent suppression.
134
197
  - An explicit `not-spam` complaint does not create a new suppression.
135
198
  - Suppression checks cover the actual To/Cc/Bcc envelope, including overrides.
136
- Matching preserves CommonShare's case/plus-alias policy.
199
+ Matching is case-insensitive and ignores `+alias` tags.
137
200
  - Mixed messages keep allowed recipients and their original addresses; MIME
138
201
  is unchanged. If every recipient is suppressed, Hailer returns HTTP 422
139
202
  without calling SES. A suppression lookup failure fails closed with HTTP 503.
@@ -223,11 +286,16 @@ the section disables scheduled sync, not existing suppression enforcement.
223
286
  ### Control plane
224
287
 
225
288
  The behavior circuit evaluates **pure admission decisions**: input validity,
226
- service/storage readiness, suppression, and local rate admission. PostgreSQL,
289
+ service/storage readiness, suppression, and rate admission. PostgreSQL,
227
290
  AWS calls, clocks, and token reservations remain owned by the async host.
228
291
  The SES circuit breaker counts transient/ambiguous failures, not bad addresses
229
292
  or permanent request rejections. An optional `[rate_limit]` budgets envelope
230
- recipients **per process**, not per account; it does not discover SES quotas.
293
+ recipients through a single shared Postgres-backed token bucket - every
294
+ replica draws down the same account-wide budget, not an independent
295
+ per-process one. `discover_from_aws = true` replaces the configured rate
296
+ with the SES account's real `SendQuota.MaxSendRate`, re-checked
297
+ periodically; a rate-state read/write failure fails closed (denies
298
+ admission) rather than risk exceeding the real AWS quota blind.
231
299
 
232
300
  Private `GET /internal/mail/health` returns sanitized component states and
233
301
  counters. `GET /internal/mail/ready` returns 503 during initial sync or storage
@@ -258,8 +326,13 @@ turn off.
258
326
 
259
327
  ## Domain blocklist
260
328
 
261
- ```text
262
- SendRequest -> impossible-address check -> domain blocklist (free, local) -> suppression (free, local) -> verification (paid, external) -> SES
329
+ ```mermaid
330
+ flowchart LR
331
+ A[SendRequest] --> B[impossible-address check]
332
+ B --> C["domain blocklist<br/>(free, local)"]
333
+ C --> D["suppression<br/>(free, local)"]
334
+ D --> E["verification<br/>(paid, external)"]
335
+ E --> F[SES]
263
336
  ```
264
337
 
265
338
  Always active - an empty `hailer.domain_blocks` table is a no-op, there is
@@ -280,8 +353,11 @@ cannot be removed this way, by design.
280
353
 
281
354
  ## Address verification
282
355
 
283
- ```text
284
- SendRequest -> suppression check (cheap, local) -> address verification (paid, external) -> SES
356
+ ```mermaid
357
+ flowchart LR
358
+ A[SendRequest] --> B["suppression check<br/>(cheap, local)"]
359
+ B --> C["address verification<br/>(paid, external)"]
360
+ C --> D[SES]
285
361
  ```
286
362
 
287
363
  Opt-in pre-send deliverability check, off by default. Enable with
@@ -380,6 +456,9 @@ The SES SDK makes **one send attempt**. AWS throttling/transient failures return
380
456
  503, permanent service rejections 502, and disconnects/timeouts/missing message
381
457
  IDs carry the explicit unknown-outcome code. None of these responses authorizes
382
458
  an automatic retry of an ambiguous send.
459
+ Postmark sends are single-attempt too: throttling, a refused token and 5xx
460
+ return 503, other refusals 502, and lost or unreadable answers the
461
+ unknown-outcome code.
383
462
 
384
463
  ## Status
385
464
 
@@ -395,7 +474,7 @@ missing code.
395
474
  ```sh
396
475
  bundle install
397
476
  bundle exec rake
398
- HAILER_TEST_DATABASE_URL=postgres://test_user:password@127.0.0.1/hailer_test cargo test --locked
477
+ HAILER_TEST_DATABASE_URL=postgres://test_user:password@127.0.0.1/hailer_test cargo test --locked --features ses,postmark
399
478
  cargo fmt --all -- --check
400
479
  ```
401
480
 
@@ -408,19 +487,6 @@ each test creates and drops its own database. Never point this variable at a
408
487
  customer or Rails production database. Neither suite sends real mail or requires
409
488
  AWS credentials.
410
489
 
411
- For the opt-in CommonShare compatibility smoke, create a disposable Hailer
412
- database, then run from that application's checkout:
413
-
414
- ```sh
415
- RAILS_ENV=test HAILER_SMOKE_BINARY=/path/to/hailer/target/debug/hailer \
416
- HAILER_DATABASE_URL=postgres://test_user:password@127.0.0.1/hailer_smoke \
417
- bundle exec rails runner /path/to/hailer/test/commonshare_smoke.rb
418
- ```
419
-
420
- It refuses a non-test app database, points the AWS SDK at a loopback fixture,
421
- and rolls back application-history changes. It does not change the app's
422
- dependency lockfile or send external mail.
423
-
424
490
  `HAILER_BINARY` is an explicit, version-checked source-build override; there is
425
491
  no download or PATH fallback.
426
492
 
data/hailer.example.toml CHANGED
@@ -3,6 +3,12 @@ threads = 2
3
3
  database_pool_size = 5
4
4
  shutdown_timeout_seconds = 30
5
5
 
6
+ # "ses" (default) or "postmark". Postmark reads POSTMARK_SERVER_TOKEN from the
7
+ # environment and refuses the SES-only settings below.
8
+ # provider = "postmark"
9
+ # [postmark]
10
+ # message_stream = "outbound"
11
+
6
12
  # Optional SES event-publishing configuration set. Its events must include mail
7
13
  # tags and reach the dedicated SNS/SQS feedback route to resolve unknown sends.
8
14
  # Otherwise configure an appropriate default set on the sending identity.
@@ -12,10 +18,16 @@ shutdown_timeout_seconds = 30
12
18
  [suppression_sync]
13
19
  interval_seconds = 3600
14
20
 
15
- # Optional PER-PROCESS budget, not an account-wide SES quota.
21
+ # Optional. Shared across every replica (one Postgres-backed token bucket,
22
+ # not a per-process budget) - a second replica cannot double the admitted rate.
16
23
  # [rate_limit]
17
24
  # recipients_per_second = 10.0
18
25
  # burst = 50
26
+ # Replace recipients_per_second with the SES account's real
27
+ # SendQuota.MaxSendRate, re-checked periodically. recipients_per_second/burst
28
+ # above become just the seed used until the first successful discovery.
29
+ # discover_from_aws = true
30
+ # discovery_interval_seconds = 900
19
31
 
20
32
  # Durable intake requires explicit logical payload budgets.
21
33
  # [queued]
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Hailer
4
- VERSION = '0.5.0'
4
+ VERSION = '0.7.0'
5
5
  end
Binary file
@@ -1,6 +1,6 @@
1
1
  {
2
- "version": "0.5.0",
2
+ "version": "0.7.0",
3
3
  "platform": "aarch64-linux-gnu",
4
4
  "target": "aarch64-unknown-linux-gnu",
5
- "sha256": "411a4aa34c3e0f1ac480b04cfb97c2fe27a3738f013cfdffced33990f5bad90e"
5
+ "sha256": "73c0ebbde805684f713a7419623d6238b633b2f5d6b63ed13d12845982344f2d"
6
6
  }
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: hailer
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.7.0
5
5
  platform: aarch64-linux-gnu
6
6
  authors:
7
7
  - Abdelkader Boudih
@@ -123,6 +123,20 @@ dependencies:
123
123
  - - "~>"
124
124
  - !ruby/object:Gem::Version
125
125
  version: '6.0'
126
+ - !ruby/object:Gem::Dependency
127
+ name: padded_cell
128
+ requirement: !ruby/object:Gem::Requirement
129
+ requirements:
130
+ - - ">="
131
+ - !ruby/object:Gem::Version
132
+ version: '0'
133
+ type: :development
134
+ prerelease: false
135
+ version_requirements: !ruby/object:Gem::Requirement
136
+ requirements:
137
+ - - ">="
138
+ - !ruby/object:Gem::Version
139
+ version: '0'
126
140
  - !ruby/object:Gem::Dependency
127
141
  name: rake
128
142
  requirement: !ruby/object:Gem::Requirement
@@ -149,7 +163,6 @@ files:
149
163
  - CHANGELOG.md
150
164
  - LICENSE.txt
151
165
  - README.md
152
- - docs/durable-delivery.md
153
166
  - exe/hailer
154
167
  - hailer.example.toml
155
168
  - lib/hailer.rb
@@ -1,214 +0,0 @@
1
- # Durable delivery
2
-
3
- The queued Ruby interface, PostgreSQL spool and supervised dispatcher are
4
- implemented and shipped (0.3.0+). It is opt-in: absent `[queued]` config,
5
- Hailer stays on the synchronous send path and none of this runs.
6
-
7
- ## Opt-in Rails configuration
8
-
9
- Keep `HAILER_URL` pointing to the existing private `/internal/mail/send` endpoint.
10
- The queued client uses the same validated origin with `/internal/mail/messages`.
11
-
12
- ```ruby
13
- # config/environments/production.rb
14
- config.action_mailer.delivery_method = :hailer_queued
15
- ```
16
-
17
- The initializer registers the adapter and selects `Hailer::MailDeliveryJob` for
18
- this opt-in configuration. The default remains the synchronous `:hailer`
19
- adapter, whose HTTP requests never retry.
20
-
21
- For a per-mailer opt-in, select both:
22
-
23
- ```ruby
24
- self.delivery_method = :hailer_queued
25
- self.delivery_job = Hailer::MailDeliveryJob
26
- ```
27
-
28
- An explicitly configured application delivery job is not replaced. It must
29
- inherit `Hailer::MailDeliveryJob` or include `Hailer::DeliveryJobContext` to
30
- obtain stable submission keys across job retries. This uses public ActiveJob
31
- callbacks, not Rails monkey patches.
32
-
33
- ## Identities and retries
34
-
35
- - Standard queued jobs use job ID plus delivery ordinal. Different jobs are
36
- different intents unless the application supplies a business key.
37
- - Direct `deliver_now` calls generate a fresh key per invocation.
38
- - Supply a business key through `delivery_method_options` when separate calls
39
- represent the same intended message:
40
-
41
- ```ruby
42
- mail(
43
- to: recipient,
44
- subject: 'Invoice',
45
- delivery_method_options: { submission_key: "invoice:#{invoice.id}:issued" }
46
- )
47
- ```
48
-
49
- - Supply an optional ISO 8601 `expires_at` through those same options. The
50
- service contract defaults to 24 hours and allows shorter deadlines.
51
- - A queued intake call serializes its command once. Up to three HTTP attempts
52
- reuse those exact bytes, key and deadline after transport loss or retryable
53
- admission errors (429/503). Set `intake_attempts: 1` to disable these retries.
54
- - Validation, submission conflicts, malformed responses and provider-unknown
55
- errors do not retry.
56
- - Rails re-renders mail when a job is performed again. If the bytes or envelope
57
- change under an accepted key, the service must return a conflict; the adapter
58
- raises `Hailer::SubmissionConflictError`. Job keys alone do not provide
59
- transparent exactly-once business delivery.
60
-
61
- Submission keys are command metadata, not MIME headers.
62
-
63
- ## Private status and lifecycle feed
64
-
65
- ```ruby
66
- client = Hailer::LifecycleClient.new # same HAILER_URL origin
67
- status = client.status(hailer_message_id)
68
- page = client.poll(after: saved_cursor, limit: 100)
69
- ```
70
-
71
- Status distinguishes the original RFC Message-ID, Hailer ID and provider ID,
72
- and never returns MIME. `status.attempts` and `status.recipient_outcomes` contain
73
- the latest 100 records each, in chronological order. Their corresponding
74
- `*_truncated` flags report older records; use the lifecycle feed for complete
75
- observations. An accepted message can still have an uncertain historical
76
- attempt after an operator-authorized retry. Lifecycle events have their own cursor space; do not
77
- reuse an existing `FeedbackClient` cursor. Persist `page.next_cursor` only after
78
- processing the page successfully. Re-reading a cursor does not delete events.
79
-
80
- The service's `[queued]` configuration requires explicit `max_bytes` and
81
- `max_messages`. Bytes measure canonical logical command payload, not PostgreSQL
82
- table/index/WAL/backups or a physical disk quota. All replicas of a deployment
83
- must use the same budgets. Admission is transactional; a replay does not consume
84
- another slot, and accepted messages are never evicted to admit new ones.
85
-
86
- ## Acceptance is not delivery
87
-
88
- HTTP 202 means the service durably owns the message. The adapter exposes its ID
89
- through `message.header[:hailer_message_id]` before Rails observers run. It does
90
- not fabricate `ses_message_id`; provider acceptance and recipient delivery
91
- are later observations.
92
-
93
- Application observers must distinguish durable ownership from provider
94
- acceptance: persist the Hailer ID and an owned/queued state, then consume
95
- lifecycle facts separately. CommonShare's existing observer still writes
96
- `status: "sent"` and only the SES ID for every delivered callback. The isolated
97
- queued smoke verifies transport compatibility, not that observer's readiness
98
- for production opt-in. Keep its synchronous configuration until this application
99
- cutover work is done.
100
-
101
- Unknown provider outcomes are held without an automatic resend. Seven-day
102
- unknown-body retention (measured from durable intake) does not extend the
103
- 24-hour send-start deadline. Body purge retains receipts and uncertainty.
104
- Only positive evidence of no acceptance permits automatic retry, with jittered
105
- backoff capped at 600 seconds and at most 255 automatic attempts per intent.
106
- Expiry stops new attempts; it never proves a previous attempt was unsent.
107
-
108
- Live bodies are purged after confirmed acceptance, terminal rejection or
109
- suppression, cancellation, or safe queued expiry. Purge releases logical
110
- capacity, not PostgreSQL allocated disk, backups or copies already in-flight.
111
-
112
- ## Feedback and private routing
113
-
114
- Set root `ses_configuration_set = "hailer-feedback"` in Hailer's TOML, or use
115
- an equivalent default configuration set on the SES sending identity. Configure
116
- SES event publishing through the dedicated SNS/SQS feedback route, preserving
117
- `mail.tags.hailer_message_id` and `mail.tags.hailer_attempt_id`. These unique tags
118
- allow feedback to resolve an unknown SDK response. A provider ID already
119
- captured from an accepted response also correlates later untagged feedback.
120
- Without tags and without a captured provider ID, feedback cannot resolve
121
- uncertainty. Hailer never guesses from recipient, timestamps or RFC Message-ID.
122
- Feedback received before an untagged provider ID is captured is not retroactively
123
- correlated; retain the tags for reliable recovery.
124
-
125
- Mothership must route the new private paths as well as the old synchronous
126
- ones. A suitable bind pattern is:
127
-
128
- ```toml
129
- routes = [{ bind = "mail", pattern = "^/internal/mail/(send|events|health|ready|intake-ready|dispatch-ready|messages|messages/events|messages/[0-9a-f-]{36})$" }]
130
- ```
131
-
132
- Keep this bind private. Intake readiness depends on durable writable capacity,
133
- not SES health. `/internal/mail/dispatch-ready` separately reports worker,
134
- bootstrap and control eligibility. Neither readiness response guarantees that
135
- a later send will succeed.
136
-
137
- ## Operator control
138
-
139
- Run against the intended database using the same `HAILER_DATABASE_URL`:
140
-
141
- ```sh
142
- hailer message-status --id MESSAGE_UUID
143
- hailer cancel-message --id MESSAGE_UUID --reason "intent withdrawn"
144
- hailer resolve-message --id MESSAGE_UUID --outcome accepted \
145
- --provider-message-id VERIFIED_SES_ID --reason "verified provider evidence"
146
- hailer resolve-message --id MESSAGE_UUID --outcome not-accepted \
147
- --reason "verified no provider acceptance"
148
- hailer resolve-message --id MESSAGE_UUID --outcome retry \
149
- --acknowledge-duplicate-risk --reason "investigated; accept duplicate risk"
150
- ```
151
-
152
- Cancellation is only possible before dispatch and cannot unsend mail.
153
- Resolution defaults to the current held-unknown attempt. Use `--attempt-id
154
- ATTEMPT_UUID` to resolve an older unknown journal entry without overwriting a
155
- later attempt. Retry is allowed only for the current held intent, with an
156
- available body, an unexpired deadline, no acceptance latch and explicit
157
- duplicate-risk acknowledgement. A new attempt never erases the old uncertainty.
158
- All decisions require an audit reason. After expiry or body purge, sending
159
- requires a new intent/key.
160
-
161
- ## Quarantine
162
-
163
- Opt-in, queued pipeline only - a synchronous `:hailer` send has no way to
164
- hold a message for later review, so a non-ASCII domain or a newly
165
- registered one makes the synchronous adapter reject outright. The queued
166
- adapter holds instead:
167
-
168
- ```toml
169
- [domain_intel]
170
- provider = "rdap"
171
- new_domain_threshold_days = 30
172
- ```
173
-
174
- A recipient domain that is not plain ASCII (a malformed/unencoded IDN, or a
175
- homograph-spoofing attempt - legitimate IDNs are transmitted as ASCII
176
- punycode) is always checked, regardless of this block. `[domain_intel]`
177
- additionally checks the domain's RDAP registration date; newer than the
178
- threshold holds the message as `quarantined` instead of admitting it as
179
- `queued`. The whole message is quarantined, not just the flagged recipient -
180
- this is an operator review gate on intent, not a per-recipient filter like
181
- suppression or the domain blocklist (`hailer ban-domain`). RDAP's bootstrap
182
- registry is public; no credential is needed.
183
-
184
- ```sh
185
- hailer release-quarantine --id MESSAGE_UUID --reason "reviewed, legitimate"
186
- hailer cancel-message --id MESSAGE_UUID --reason "rejected on review"
187
- ```
188
-
189
- Releasing resets `next_attempt_at` to now, so the message re-enters the
190
- normal dispatch queue immediately. `cancel-message` also accepts a
191
- quarantined message. An unactioned quarantine still expires on the same
192
- deadline as a normal `queued` message.
193
-
194
- ## Local application verification
195
-
196
- `test/commonshare_smoke.rb` runs inside CommonShare's test environment with a
197
- real Mothership bay and loopback SES, never real AWS credentials. Use a fresh
198
- loopback PostgreSQL database named `hailer_smoke_*` for each queued run.
199
- The script intentionally reuses one business key to check replay after purge.
200
-
201
- ```sh
202
- RAILS_ENV=test DISABLE_BOOTSNAP=1 \
203
- HAILER_SMOKE_QUEUED=1 \
204
- HAILER_SMOKE_BINARY=/absolute/path/to/current/hailer \
205
- HAILER_DATABASE_URL=postgres://...@127.0.0.1:5432/hailer_smoke_queued \
206
- bundle exec rails runner /absolute/path/to/hailer/test/commonshare_smoke.rb
207
- ```
208
-
209
- An isolated temporary `BUNDLE_GEMFILE` can select the working-tree gem or locally
210
- installed verification gem without editing CommonShare's Gemfile or lock.
211
- Set `HAILER_SMOKE_EXPECTED_PLATFORM=arm64-darwin` to assert native-gem selection.
212
- Omit `HAILER_SMOKE_QUEUED` for the unchanged synchronous contract. The test holds
213
- the provider response until Rails has its receipt, then checks the journal,
214
- correlation tags, envelope/attachment, body purge, replay, conflict and feeds.