hailer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9438bee546359ce97506f8c5111ffb1eed0d1fe187a4632385e11f61e37c574a
+  data.tar.gz: 1945fc1ab7fec8409cdea1a9de9e82347d204afbeb98226c864ea27d46713011
+SHA512:
+  metadata.gz: 91f53a1872615cca824ddaf029b073baa144f94dad7163b92fcb2c03ff1e687a24d8e65a4813516ff3a5339ef5d348103965c4719c68a18cae2c9a5aac4bfdca
+  data.tar.gz: 921b031e5486c6b6757e3ccb9d8673d0c3a6f7dd2c8aa4cb4be85b596f93572b167b8cc411ae01d8f33c0af9b72a6069b5af4f08d8257e2968092f7fef724a1d

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Rails 8.1+/Ruby 4.0+ ActionMailer delivery with automatic defaults.
+- Typed provider-neutral feedback client and Rails callback consumer.
+- SES sender, SQS feedback ingestion, durable suppressions, and import tooling.
+- Platform gems carrying the standalone Rust service with a verified launcher.
+- Local CommonShare integration tested without sending real email.

data/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Abdelkader Boudih
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,241 @@
+# Hailer
+
+Rails writes the email. Hailer deals with sending it.
+
+This repository ships two things at version **0.1.0**:
+
+- **`hailer` gem** — an ActionMailer adapter, feedback client, and executable
+  launcher. Platform gems bundle the Rust binary. No Ruby AWS SDK or native extension.
+- **`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
+```
+
+## 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.
+
+```ruby
+# Gemfile (use path: "/path/to/hailer" while developing)
+gem "hailer"
+```
+
+The Railtie registers and selects Hailer automatically. Set the private service
+URL in the Rails process's environment:
+
+```sh
+HAILER_URL=http://127.0.0.1:9293/internal/mail/send
+```
+
+No application initializer is needed. To customize connection settings:
+
+```ruby
+config.action_mailer.hailer_settings = {
+  endpoint: ENV.fetch("HAILER_URL"),
+  open_timeout: 5,
+  read_timeout: 30,
+  write_timeout: 30
+}
+```
+
+`HAILER_URL` is the complete private URL, for example
+`http://127.0.0.1:9293/internal/mail/send`. It is also the default endpoint
+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]`.
+
+## Rust service
+
+Platform gems install the `hailer` executable, ready for Mothership to launch.
+Installing the gem does not start the service or send mail.
+
+The source (`ruby`) gem has the same Rails client and launcher, but no binary.
+For source development or an unsupported platform:
+
+```sh
+cargo install --path . --locked
+export HAILER_BINARY=/absolute/path/to/hailer
+```
+
+Run it as a Mothership HTTP bay. Merge this example into your fleet manifest;
+the bind must stay private and must not be routed on a public listener:
+
+```toml
+[mothership.bind]
+mail = "127.0.0.1:9293"
+
+[[bays.http]]
+name = "hailer"
+command = "hailer"
+workers = 0
+threads = 2
+routes = [{ bind = "mail", pattern = "^/internal/mail/send$" }]
+```
+
+Mothership exports `MS_PID`, `MS_SHIP`, and `MS_SOCKET_DIR`. Hailer binds its
+docking Unix socket; it does **not** run another HTTP server. For containers,
+use a private network listener with network policy instead of a loopback address
+if Rails runs in a different network namespace.
+
+Give the **service**, not the Rails adapter, AWS region and credentials through
+the standard AWS credential chain. Its identity needs `ses:SendEmail`, and the
+SES account/identities must be configured for sending.
+
+## Bounces, complaints, and suppressions
+
+```text
+SES → SNS → dedicated SQS queue → Hailer → durable events + suppressions
+```
+
+Hailer atomically commits each event, deduplication key, and suppression change
+to a local redb database **before** acknowledging SQS. Failed acknowledgements
+can be retried without duplicating stored events. Invalid/untrusted messages
+are left for SQS's dead-letter policy.
+
+- Permanent bounces and complaints suppress recipients.
+- 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.
+- 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.
+
+Copy [hailer.example.toml](hailer.example.toml), set the real queue/topic, and
+pass `--config /path/to/hailer.toml` or `HAILER_CONFIG`. Without `[feedback]`,
+the consumer is disabled, but previously stored suppressions are still enforced.
+`HAILER_STATE_PATH` overrides `state_path`; the default is `data/hailer.redb`.
+Use a persistent, private volume in production.
+
+**One Hailer process owns one state file and one dedicated queue.** Run the
+bay with `workers = 0`; this is not a distributed suppression database.
+Do not run competing consumers with separate state files. Back up the state
+file while Hailer is stopped; event history and deduplication currently have
+no automatic retention/pruning.
+
+Hailer also exposes a provider-neutral, nondestructive event feed:
+
+```http
+POST /internal/mail/events
+Content-Type: application/json
+
+{"after":0,"limit":100}
+```
+
+Route it on the **same private bind**, if application tracking needs it:
+
+```toml
+routes = [{ bind = "mail", pattern = "^/internal/mail/(send|events)$" }]
+```
+
+The gem validates the page and exposes immutable `FeedbackEvent` objects:
+
+```ruby
+page = Hailer::FeedbackClient.new(endpoint: ENV.fetch("HAILER_URL")).poll(after: 0)
+page.events.each { |event| puts [event.event_id, event.kind, event.message_id] }
+```
+
+Configure a Rails business-history handler (a callable or reloadable class name):
+
+```ruby
+Rails.application.config.hailer.feedback_handler = "Platform::MailFeedback"
+```
+
+Then `Hailer::FeedbackConsumer.new.call(after: cursor)` calls that handler for
+each validated event and returns the next cursor only after all callbacks
+succeed. A callback must **raise** on failure. Persist the cursor and domain
+updates in one application database transaction. Retried pages require
+idempotent handlers; no hidden poller, scheduling, or checkpoint database is
+started by the gem. Reading does not acknowledge or erase events.
+
+See [feedback setup and migration](docs/feedback.md) before removing a receiver.
+
+**Security:** the route currently has no application-level authentication.
+`/internal/` is a name, not an access control. Keep the bind private. The client
+does not follow redirects or use environment HTTP proxies.
+
+## Failure semantics
+
+An HTTP 200 means **SES accepted the message**, not that the recipient received
+it. A successful response must include a nonblank `message_id`.
+
+| Failure | Ruby exception |
+| --- | --- |
+| HTTP 400 / 422 | `Hailer::ValidationError` |
+| HTTP 502 | `Hailer::RejectedError` |
+| HTTP 503 | `Hailer::UnavailableError` |
+| Other non-200 status | `Hailer::DeliveryError` |
+| Invalid/oversized response, missing message ID | `Hailer::ProtocolError` |
+| Connection, TLS, or timeout failure | `Hailer::TransportError` |
+| Missing/invalid endpoint or timeout settings | `Hailer::ConfigurationError` |
+
+The gem does not retry. A lost response can happen **after** SES accepted the
+message; retrying may duplicate it. There is no durable **outbound** queue or
+send-idempotency store yet; feedback deduplication does not deduplicate sends.
+Rails jobs can also retry, so configure them deliberately.
+The current service maps all SES SDK send errors to HTTP 502; that status is
+not yet a reliable distinction between permanent and transient AWS failures.
+
+## Status and migration
+
+The delivery contract and Hailer-side feedback processing are implemented. CommonShare's
+existing sender is the compatibility reference, not a runtime dependency.
+See [the contract](docs/delivery-contract.md).
+
+Before switching an existing app:
+
+1. Run Hailer on a private Mothership bind and verify real SES delivery.
+2. Add the gem, set `HAILER_URL`, and remove the app's old delivery-method
+   override so Hailer's default takes effect.
+3. Subscribe a dedicated SQS queue before exporting and importing existing
+   suppressions. Let Hailer catch up and verify the event feed.
+4. Keep existing receivers/interceptors until routing, suppression import,
+   and any provider-neutral app history consumer have been verified.
+5. Only then remove the old sender and AWS-specific feedback handling.
+
+CommonShare's local integration is tested with its real application, database,
+Mothership, packaged Hailer binary, and a loopback SES fixture. Its existing AWS
+receivers remain until the real subscription and suppression cutover is verified.
+No deployed AWS routing has been changed.
+Account diagnostics, validation/behavior plugins,
+distributed state, rate limiting, graceful draining, and reliable send-error
+classification are later work. No plugin API is promised yet.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+cargo test --locked
+cargo fmt --all -- --check
+gem build hailer.gemspec --output /tmp/hailer-0.1.0.gem
+bundle exec rake native:package
+```
+
+The Ruby suite exercises real local HTTP exchanges and a booted Rails app.
+The Rust suite checks the same JSON fixture and the docking exchange with a
+fake provider. Feedback tests cover redelivery, acknowledgement ordering,
+atomic rollback, restart persistence, imports, and suppression enforcement.
+Neither suite sends real mail or requires AWS credentials.
+
+`native:package` builds a locked release and writes
+`pkg/hailer-0.1.0-<platform>.gem`. Each platform gem contains exactly its host
+binary and a version/platform/SHA-256 manifest. The launcher verifies that
+manifest before `exec`, preserving arguments, exit status, and signal handling.
+`HAILER_BINARY` is an explicit, version-checked source-build override; there is
+no download or PATH fallback.
+
+Build on each supported release host before publishing its artifact. Only
+`arm64-darwin` has been built and exercised in this checkout. Linux GNU builds
+must use your intended minimum-glibc build environment; a native build on a
+newer distro is not automatically portable to older distributions. Nothing in
+the packaging task publishes a gem.

data/docs/delivery-contract.md

@@ -0,0 +1,59 @@
+# Delivery contract, v0.1
+
+The gem and service are released from this repository. Keep their versions in
+sync. Platform gems embed the compiled service, but it still runs as a
+separate Mothership-supervised process, never inside Rails.
+
+## Request
+
+`POST /internal/mail/send`, `Content-Type: application/json`.
+
+```json
+{
+  "raw_mime": "From: Alice <alice@example.com>\r\nTo: bob@example.com\r\n\r\nHello\r\n",
+  "to_addresses": ["bob@example.com"],
+  "cc_addresses": [],
+  "bcc_addresses": []
+}
+```
+
+- `raw_mime` is the full `Mail::Message#to_s`, not a rebuilt message.
+- `from_email_address` is omitted unless the SMTP envelope sender was
+  explicitly assigned. SES otherwise reads the MIME From header, including
+  display names.
+- `to_addresses` uses explicitly assigned `smtp_envelope_to`, otherwise `to`.
+- `cc_addresses` and `bcc_addresses` preserve their original recipient groups,
+  including when `smtp_envelope_to` is overridden. This matches the existing
+  CommonShare SESv2 adapter.
+- Absent recipient groups are arrays, never JSON `null`. The service also
+  defaults omitted recipient arrays to empty.
+- The service validates addresses and requires at least one recipient.
+
+Do not expose this endpoint to untrusted callers. Messages and addresses are
+sensitive; do not log raw request bodies.
+
+## Response
+
+SES acceptance: HTTP **200**, `{"message_id":"SES-message-id"}`.
+The adapter copies the ID to the original message's `ses_message_id` header
+after acceptance, so Rails delivery observers can read it.
+
+Failure: HTTP **400**, **422**, **502**, or **503**, `{"error":"description"}`.
+Other paths/methods currently receive **404**. See the README for Ruby error
+classes and the service's current AWS error-classification limitation.
+
+There is no redirect handling, fire-and-forget acceptance, automatic client
+retry, delivery guarantee, or idempotency key. `deliver_later` remains a Rails
+job. A timeout or lost response is an ambiguous outcome.
+
+## Compatibility tests
+
+`test/fixtures/send_request.json` is consumed by the Ruby HTTP client tests and
+Rust deserialization/exchange tests. Ruby tests separately render real
+`Mail::Message` instances, including binary attachments, display names, Bcc,
+and explicit envelope overrides. Rails boot tests check automatic configuration,
+`deliver_now`, `deliver_later` job scheduling, observer timing, failure
+propagation, and explicit `:test` delivery.
+
+Provider acceptance tests use a fake provider, not SES. This establishes the
+in-repository contract, not real AWS or Mothership interoperability.

data/docs/feedback.md

@@ -0,0 +1,160 @@
+# Feedback and the CommonShare cutover
+
+## Ownership
+
+Hailer owns SES/SNS parsing, SQS consumption, deduplication, suppression storage,
+and filtering before delivery. It has **no public SNS webhook**.
+
+Applications can consume normalized events to update business records. They
+do not need to know about SNS subscriptions or SES notification schemas.
+CommonShare's local generic history consumer has been wired and tested. Its
+webhook receivers have **not** been removed: deployed AWS subscriptions and
+the final suppression migration must still be verified before that is safe.
+
+## AWS prerequisites
+
+1. Configure SES identity notifications or configuration-set event publishing
+   to an SNS topic. At minimum, publish Bounce and Complaint; add Delivery and
+   other event types if application history needs them.
+2. Subscribe a **dedicated SQS queue** with `RawMessageDelivery=false`. Hailer
+   requires the SNS envelope and checks its `TopicArn` against the configured
+   topic. Both SES's `notificationType` and `eventType` payloads are supported.
+3. Restrict the queue policy to the intended SNS topic. Do not grant application
+   roles `sqs:SendMessage` on this queue: an authorized sender could forge an
+   SNS-looking envelope. Topic checking is not signature verification.
+4. Configure a dead-letter queue, a finite receive count, suitable retention,
+   and alarms for oldest-message age, backlog, and dead-letter messages.
+5. Give Hailer's role `sqs:ReceiveMessage` and `sqs:DeleteMessage` on that queue,
+   in addition to `ses:SendEmail`. For a customer-managed encrypted queue,
+   grant the necessary KMS decrypt permissions too.
+6. Set the queue URL, SNS topic ARN, and persistent state path in
+   `hailer.toml` (see `hailer.example.toml`). Region/credentials come from the
+   shared standard AWS credential chain, not the Rails adapter.
+
+SES identity feedback works automatically for those identities. If using an
+SES configuration set, make sure the sent message actually selects it, for
+example with SES's `X-SES-CONFIGURATION-SET` MIME header. Merely creating an SNS
+subscription does not enable SES event publishing.
+
+Hailer long-polls in batches of 10 with a 60-second visibility timeout. It
+commits first, then deletes each SQS receipt. Failed parsing, state writes,
+or deletes leave the message available for retry. Poison/unknown event types
+are not silently discarded: use and monitor the DLQ.
+
+## Suppression policy
+
+New Permanent bounces and complaints suppress recipients. Transient and
+Undetermined bounces are stored as events but do not permanently block mail.
+`not-spam` feedback does not add a suppression and does not automatically
+clear an existing one. There is no automatic unsuppression API yet.
+
+Matching trims/downcases the address and strips the local part's `+alias`,
+matching CommonShare's existing suppression policy. This is not a universal
+email-equivalence rule; it is an explicit migration policy. Only matching keys
+are normalized: allowed delivery addresses and the MIME message are unchanged.
+
+Imported suppressions are retained, including any old records that were
+originally created for transient bounces. Imports are atomic, repeatable, and
+cannot downgrade a complaint to a bounce. New feedback also cannot downgrade
+a complaint. The current service has one local state owner; separate replicas
+must not share a queue while maintaining separate state.
+
+## Import existing suppressions
+
+Subscribe SQS **before** the final export so new feedback accumulates while
+you migrate. Keep CommonShare's existing receiver active.
+
+Export with read-only application code to a protected file (the data is PII):
+
+```sh
+umask 077
+SUPPRESSION_EXPORT=/secure/suppressions.json bin/rails runner '
+  records = Platform::EmailSuppression.select(
+    :email_address, :reason, :suppressed_at, :originating_message_id, :metadata
+  )
+  File.write(ENV.fetch("SUPPRESSION_EXPORT"), records.map(&:attributes).to_json)
+'
+```
+
+The file is a JSON array. Each record needs `email_address`, `reason` (`bounce`
+or `complaint`), and an RFC 3339 `suppressed_at`. Message ID/metadata are optional.
+Extra ActiveRecord fields are ignored. See `test/fixtures/suppressions.json`.
+
+Stop Hailer before the import; redb permits one process to open its state file:
+
+```sh
+hailer --config /etc/hailer.toml import-suppressions --file /secure/suppressions.json
+```
+
+This command needs neither Mothership nor AWS credentials. An invalid address,
+reason, or timestamp rejects the whole batch without partially importing.
+Restart Hailer against the **same durable state path**, consume the backlog,
+and verify known suppressed recipients cannot reach SES. Protect and delete
+temporary exports according to your data-retention policy.
+
+## Provider-neutral event feed
+
+`POST /internal/mail/events` on Hailer's private Mothership bind:
+
+```json
+{"after":0,"limit":100}
+```
+
+`limit` is 1–100. A page looks like:
+
+```json
+{
+  "events": [{
+    "sequence": 1,
+    "event": {
+      "event_id": "arn:aws:sns:us-east-1:123456789012:mail-feedback:sns-id",
+      "kind": "bounced",
+      "provider": "ses",
+      "provider_message_id": "ses-id",
+      "message_id": "<original-rails-message-id@example.com>",
+      "occurred_at": "2026-10-20T12:00:00Z",
+      "recipients": ["recipient@example.com"],
+      "suppression": "bounce"
+    }
+  }],
+  "next_cursor": 1
+}
+```
+
+Kinds: `sent`, `delivered`, `bounced`, `complained`, `rejected`,
+`rendering_failed`, `delayed`, `opened`, `clicked`.
+
+The sequence is **ingestion order**, not event time. Delivery events can arrive
+late or out of order. Consumers should use `event_id` for deduplication, handle
+`occurred_at` deliberately, and persist their cursor with their domain changes.
+Retrying a page is safe only if the application handler is idempotent. There
+is no global acknowledgement or destructive read; each consumer owns its cursor.
+
+Use `message_id` to correlate the original RFC 5322 Message-ID; fall back to
+`provider_message_id` if your app stores the SES ID. `message_id` may be null
+when SES omitted headers. The feed contains recipient PII: keep it private.
+`Hailer::FeedbackClient#poll(after:, limit:)` validates the entire page before
+exposing typed events. `Hailer::FeedbackConsumer#call` dispatches them through
+`config.hailer.feedback_handler` and returns a cursor only after every callback
+succeeds. A missing handler fails before polling. Applications still own
+scheduling, idempotency, business-record updates, and durable cursor storage.
+
+## Safe removal checklist
+
+Before deleting CommonShare's AWS-specific email handling:
+
+- Verify a real SES mailbox-simulator bounce and complaint reach Hailer's queue.
+- Verify suppression persists across a service restart and blocks later sends.
+- Import the final old suppression snapshot with no gap in queue coverage.
+- Verify a generic event consumer updates `OutgoingEmail` without SES/SNS parsing.
+- Change the sender to Hailer and verify normal, CC/BCC, attachment, and
+  explicit-envelope delivery.
+- Unsubscribe the old **email-specific** HTTP subscriptions, then remove the
+  SES controllers/routes, parsing jobs/operations, and Ruby bounce interceptor.
+- Check other SNS consumers (including `sns_insights`) before removing shared
+  controllers, models, gems, admin history, or confirmation code.
+- Keep historical database records unless a separate retention migration is
+  approved. Removing a receiver is not a reason to drop historical tables.
+
+No AWS infrastructure was changed. CommonShare's local integration is on its
+own feature branch; its existing SES/SNS receivers are retained for cutover.

data/exe/hailer

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'hailer/binary'
+
+begin
+  exec Hailer::Binary.path, *ARGV
+rescue Hailer::Error => error
+  warn error.message
+  exit 1
+end

data/hailer.example.toml

@@ -0,0 +1,8 @@
+# Keep this file and its state volume private. One Hailer process owns this file.
+state_path = "/var/lib/hailer/state.redb"
+threads = 2
+
+[feedback]
+# Dedicated queue; subscribe the SNS topic with RawMessageDelivery=false.
+queue_url = "https://sqs.us-east-1.amazonaws.com/123456789012/hailer-feedback"
+topic_arn = "arn:aws:sns:us-east-1:123456789012:mail-feedback"

data/lib/hailer/binary.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'open3'
+require_relative 'errors'
+require_relative 'version'
+
+module Hailer
+  # Used by the executable without booting Rails. Never download a binary or
+  # select an unrelated executable from PATH.
+  module Binary
+    ROOT = File.expand_path('../..', __dir__)
+
+    module_function
+
+    def platform(local = Gem::Platform.local)
+      case local.os
+      when 'darwin'
+        cpu = %w[arm64 aarch64].include?(local.cpu) ? 'arm64' : local.cpu
+        "#{cpu}-darwin"
+      when 'linux'
+        cpu = %w[arm64 aarch64].include?(local.cpu) ? 'aarch64' : local.cpu
+        "#{cpu}-linux-#{local.version == 'musl' ? 'musl' : 'gnu'}"
+      else
+        raise BinaryError, "unsupported Hailer platform: #{local}"
+      end
+    end
+
+    def path(env: ENV, root: ROOT)
+      if env.key?('HAILER_BINARY')
+        candidate = File.expand_path(env.fetch('HAILER_BINARY'))
+        executable!(candidate)
+        output, status = Open3.capture2e(candidate, '--version')
+        unless status.success? && output.strip == "hailer #{VERSION}"
+          raise BinaryError, "HAILER_BINARY must be Hailer #{VERSION}"
+        end
+        return candidate
+      end
+
+      directory = File.join(root, 'vendor', platform)
+      candidate = File.join(directory, 'bin', 'hailer')
+      executable!(candidate)
+      manifest = JSON.parse(File.read(File.join(directory, 'manifest.json')))
+      unless manifest['version'] == VERSION && manifest['platform'] == platform &&
+             manifest['sha256'] == Digest::SHA256.file(candidate).hexdigest
+        raise BinaryError, 'bundled Hailer executable does not match its release manifest'
+      end
+      candidate
+    rescue Errno::ENOENT, JSON::ParserError
+      raise BinaryError, 'missing or invalid Hailer binary manifest; reinstall the platform gem'
+    end
+
+    def executable!(candidate)
+      return if File.file?(candidate) && File.executable?(candidate)
+
+      raise BinaryError, "no executable Hailer binary at #{candidate}; install the platform gem or set HAILER_BINARY"
+    end
+  end
+end

data/lib/hailer/client.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hailer
+  Response = Data.define(:message_id)
+
+  class Client
+    def initialize(**settings)
+      @transport = Transport.new(**settings)
+    end
+
+    def deliver(payload)
+      document = @transport.post('/internal/mail/send', payload)
+      message_id = document['message_id']
+      unless message_id.is_a?(String) && !message_id.strip.empty?
+        raise ProtocolError, 'Hailer accepted the request without a message_id'
+      end
+      Response.new(message_id: message_id)
+    end
+  end
+end

data/lib/hailer/delivery_method.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'mail'
+
+module Hailer
+  class DeliveryMethod
+    attr_reader :settings
+
+    def initialize(options = {})
+      @settings = { endpoint: ENV['HAILER_URL'], **Transport::DEFAULTS }.merge(options)
+    end
+
+    def deliver!(message)
+      payload = {
+        raw_mime: message.to_s,
+        to_addresses: Array(explicit_envelope?(message, :to) ? message.smtp_envelope_to : message.to),
+        cc_addresses: Array(message.cc),
+        bcc_addresses: Array(message.bcc)
+      }
+      # The default smtp_envelope_from drops display names. Let SES read the
+      # MIME From header unless the caller explicitly overrode the envelope.
+      if explicit_envelope?(message, :from)
+        payload[:from_email_address] = message.smtp_envelope_from
+      end
+
+      Client.new(**settings).deliver(payload).tap do |response|
+        message.header[:ses_message_id] = response.message_id
+      end
+    end
+
+    private
+
+    # Match the existing SESv2 adapter's distinction between Mail's computed
+    # defaults and explicitly assigned SMTP envelope addresses.
+    def explicit_envelope?(message, field)
+      message.instance_variable_get(:"@smtp_envelope_#{field}")
+    end
+  end
+end

data/lib/hailer/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hailer
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ProtocolError < Error; end
+  class BinaryError < Error; end
+
+  # The request may already have reached SES. Retrying can send a duplicate.
+  class TransportError < Error; end
+
+  class DeliveryError < Error
+    attr_reader :status
+
+    def initialize(message, status:)
+      @status = status
+      super(message)
+    end
+  end
+
+  class ValidationError < DeliveryError; end
+  class RejectedError < DeliveryError; end
+  class UnavailableError < DeliveryError; end
+end

data/lib/hailer/feedback_client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Hailer
+  FeedbackEvent = Data.define(
+    :sequence, :event_id, :kind, :provider, :provider_message_id,
+    :message_id, :occurred_at, :recipients, :suppression
+  )
+  FeedbackPage = Data.define(:events, :next_cursor)
+
+  class FeedbackClient
+    KINDS = %w[sent delivered bounced complained rejected rendering_failed delayed opened clicked].freeze
+    MAX_RESPONSE_BYTES = 2 * 1024 * 1024
+
+    def initialize(**settings)
+      @transport = Transport.new(**settings)
+    end
+
+    def poll(after:, limit: 100)
+      unless after.is_a?(Integer) && after >= 0 && limit.is_a?(Integer) && (1..100).cover?(limit)
+        raise ConfigurationError, 'feedback requires a nonnegative cursor and limit in 1..100'
+      end
+      document = @transport.post('/internal/mail/events', { after: after, limit: limit },
+                                 max_response_bytes: MAX_RESPONSE_BYTES)
+      entries = document['events']
+      cursor = document['next_cursor']
+      unless entries.is_a?(Array) && entries.size <= limit && cursor.is_a?(Integer) && cursor >= after
+        raise ProtocolError, 'invalid Hailer feedback page'
+      end
+      previous = after
+      events = entries.map do |entry|
+        event = decode_event(entry)
+        raise ProtocolError, 'feedback sequences must increase past the requested cursor' unless event.sequence > previous
+
+        previous = event.sequence
+        event
+      end
+      raise ProtocolError, 'feedback cursor does not match its page' unless cursor == previous
+
+      FeedbackPage.new(events: events.freeze, next_cursor: cursor)
+    end
+
+    private
+
+    def decode_event(entry)
+      raise ProtocolError, 'invalid feedback entry' unless entry.is_a?(Hash) && entry['sequence'].is_a?(Integer)
+
+      event = entry['event']
+      unless event.is_a?(Hash) && KINDS.include?(event['kind']) &&
+             %w[event_id provider provider_message_id occurred_at].all? { |key| text?(event[key]) } &&
+             (event['message_id'].nil? || text?(event['message_id'])) &&
+             [nil, 'bounce', 'complaint'].include?(event['suppression']) &&
+             event['recipients'].is_a?(Array) && !event['recipients'].empty? &&
+             event['recipients'].all? { |address| text?(address) }
+        raise ProtocolError, 'invalid normalized Hailer event'
+      end
+      FeedbackEvent.new(
+        sequence: entry['sequence'], event_id: event['event_id'].freeze,
+        kind: event['kind'].freeze, provider: event['provider'].freeze,
+        provider_message_id: event['provider_message_id'].freeze,
+        message_id: event['message_id']&.freeze, occurred_at: Time.iso8601(event['occurred_at']).freeze,
+        recipients: event['recipients'].map(&:freeze).freeze, suppression: event['suppression']&.freeze
+      )
+    rescue ArgumentError
+      raise ProtocolError, 'invalid feedback event timestamp'
+    end
+
+    def text?(value) = value.is_a?(String) && !value.strip.empty?
+  end
+end

data/lib/hailer/feedback_consumer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Hailer
+  # The caller persists the returned cursor with its domain changes. An
+  # exception returns no cursor; retrying the page requires idempotent handlers.
+  class FeedbackConsumer
+    def initialize(client: nil, handler: nil)
+      @client = client || FeedbackClient.new(**ActionMailer::Base.hailer_settings)
+      @handler = handler || Rails.application.config.hailer.feedback_handler
+    end
+
+    def call(after:, limit: 100)
+      # Resolve a configured class name on every poll, respecting Rails reloads.
+      handler = @handler.is_a?(String) ? @handler.constantize : @handler
+      raise ConfigurationError, 'configure config.hailer.feedback_handler with a callable handler' unless handler.respond_to?(:call)
+
+      page = @client.poll(after: after, limit: limit)
+      page.events.each { |event| handler.call(event) }
+      page.next_cursor
+    end
+  end
+end

data/lib/hailer/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'action_mailer/railtie'
+
+module Hailer
+  class Railtie < ::Rails::Railtie
+    # A default, not an after-boot override: an app's test environment can
+    # still choose :test without contacting the service.
+    config.action_mailer.delivery_method = :hailer
+    config.hailer = ActiveSupport::OrderedOptions.new
+    config.hailer.feedback_handler = nil
+
+    initializer 'hailer.action_mailer', before: 'action_mailer.set_configs' do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :hailer, Hailer::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/hailer/transport.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Hailer
+  # No persistent connection across forks, redirects, HTTP_PROXY, or retries.
+  class Transport
+    DEFAULTS = { open_timeout: 5, read_timeout: 30, write_timeout: 30 }.freeze
+    MAX_RESPONSE_BYTES = 65_536
+    HTTP_ERRORS = {
+      400 => ValidationError, 422 => ValidationError,
+      502 => RejectedError, 503 => UnavailableError
+    }.freeze
+
+    def initialize(endpoint: ENV['HAILER_URL'], **timeouts)
+      @uri = URI.parse(endpoint.to_s)
+      unless @uri.is_a?(URI::HTTP) && @uri.host && !@uri.host.empty? &&
+             !@uri.userinfo && !@uri.query && !@uri.fragment &&
+             @uri.path == '/internal/mail/send'
+        raise ConfigurationError, 'set HAILER_URL or endpoint to an HTTP(S) URL ending in /internal/mail/send'
+      end
+      @timeouts = DEFAULTS.merge(timeouts)
+      raise ConfigurationError, 'unknown Hailer timeout setting' unless (@timeouts.keys - DEFAULTS.keys).empty?
+
+      unless @timeouts.values.all? { |value| value.is_a?(Numeric) && value.finite? && value.positive? }
+        raise ConfigurationError, 'Hailer timeouts must be positive, finite numbers'
+      end
+    rescue URI::InvalidURIError
+      raise ConfigurationError, 'invalid Hailer endpoint URL'
+    end
+
+    def post(path, payload, max_response_bytes: MAX_RESPONSE_BYTES)
+      request = Net::HTTP::Post.new(path)
+      request.content_type = 'application/json'
+      request['Accept'] = 'application/json'
+      request.body = JSON.generate(payload)
+      http = Net::HTTP.new(@uri.hostname, @uri.port, nil)
+      http.use_ssl = @uri.scheme == 'https'
+      http.max_retries = 0
+      @timeouts.each { |name, value| http.public_send(:"#{name}=", value) }
+      status, body = exchange(http, request, max_response_bytes)
+      decode_response(status, body)
+    rescue Timeout::Error, IOError, EOFError, SystemCallError, SocketError,
+           OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError => error
+      raise TransportError, "Hailer transport failed (#{error.class}); delivery outcome may be unknown"
+    end
+
+    private
+
+    def exchange(http, request, limit)
+      status = nil
+      body = +''
+      http.start do |connection|
+        connection.request(request) do |response|
+          status = response.code.to_i
+          response.read_body do |chunk|
+            raise ProtocolError, 'Hailer response exceeds the response size limit' if body.bytesize + chunk.bytesize > limit
+
+            body << chunk
+          end
+        end
+      end
+      [status, body]
+    end
+
+    def decode_response(status, body)
+      document = JSON.parse(body)
+      raise ProtocolError, 'Hailer response must be a JSON object' unless document.is_a?(Hash)
+
+      unless status == 200
+        message = document['error']
+        message = "Hailer returned HTTP #{status}" unless message.is_a?(String) && !message.empty?
+        raise HTTP_ERRORS.fetch(status, DeliveryError).new(message, status: status)
+      end
+      document
+    rescue JSON::ParserError
+      raise ProtocolError, "Hailer returned invalid JSON (HTTP #{status})"
+    end
+  end
+end

data/lib/hailer/version.rb

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

data/lib/hailer.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'hailer/version'
+require_relative 'hailer/errors'
+require_relative 'hailer/transport'
+require_relative 'hailer/client'
+require_relative 'hailer/delivery_method'
+require_relative 'hailer/feedback_client'
+require_relative 'hailer/feedback_consumer'
+require_relative 'hailer/railtie'

metadata

@@ -0,0 +1,190 @@
+--- !ruby/object:Gem::Specification
+name: hailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A thin ActionMailer adapter for the standalone Hailer Rust service. Rails
+  renders the message; Hailer owns SES delivery.
+email:
+- oss@seuros.com
+executables:
+- hailer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/delivery-contract.md
+- docs/feedback.md
+- exe/hailer
+- hailer.example.toml
+- lib/hailer.rb
+- lib/hailer/binary.rb
+- lib/hailer/client.rb
+- lib/hailer/delivery_method.rb
+- lib/hailer/errors.rb
+- lib/hailer/feedback_client.rb
+- lib/hailer/feedback_consumer.rb
+- lib/hailer/railtie.rb
+- lib/hailer/transport.rb
+- lib/hailer/version.rb
+homepage: https://github.com/seuros/hailer
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/seuros/hailer
+  changelog_uri: https://github.com/seuros/hailer/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: ActionMailer delivery through the Hailer mail ship
+test_files: []