standard_circuit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac355e3881c42900c272ba14d433216f4d8e6019e003e4b5bd52f84545c11c79
-  data.tar.gz: ffdb732b389d5b752deef02d6cdc82fd148af38e3e861d046876cce329e50d36
+  metadata.gz: 60bd3d9dbd17cad5bdf8062be096c8f7b1d8baa00f167e25f1ea96581a078cca
+  data.tar.gz: 5abdcf7eb5bf00b65bc0b724d3ced093f71f6ee1cb59a8d594c6a8d3944998e1
 SHA512:
-  metadata.gz: e2ffa97cfc68660ca8e32bd606df2251700f619f728969ce0e27ed485b6887eb6d8ecd6f1b641a0cea9d22c4842c3a5041a25b00bac97a84c37ea00ca78adf48
-  data.tar.gz: 8f245331cafaeb355b33e0ddd515bb23824713826d908544533959cd1f2dcb6c21d0160887370dadeef566a495d0474f66603095c0e1d93d1275f67c35f9f27d
+  metadata.gz: f88dc067ff12e4651a0f6f5317d55f22f5a9b78507d0bc31bf7fc737fa2dc3a7efa09853b64bb89f3fb608660eb4da79b126921d90a87e7ad9396bcb81cb317b
+  data.tar.gz: 1ed24fba0bdd0e373dfbe4cc4a18cc9e22675db527c109b151395ba2681d403ea64dbf0a12672b53250edfd8886aa66be1cedd42a36099833c23562a828b89c0

data/CHANGELOG.md

@@ -2,8 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-24
+
+A developer-experience release that moves code copy-pasted across the five consumer apps into the gem. Everything is additive: behaviour is unchanged unless you opt in, and deprecated APIs keep working until 0.5.
+
+### Added
+- **`ErrorTaxonomies::Postmark` / `AdapterErrors::Postmark`.** `server_errors` is `[Postmark::HttpServerError, Postmark::TimeoutError]` and `caller_errors` is `[Postmark::ApiInputError, Postmark::InvalidApiKeyError]`. Both return `[]` when the postmark gem isn't loaded. `ErrorTaxonomies.default_skipped_for` now also covers Postmark, because `ApiInputError` and `InvalidApiKeyError` subclass the tracked `HttpServerError`. A circuit that tracks `HttpServerError` and has no `skipped_errors:` now skips them by default, the same way AWS caller errors are skipped since 0.3.1. None of the consumers is affected: all three Postmark circuits pass `skipped_errors:` explicitly.
+- **`Config#register_preset(:postmark | :s3, name:, **overrides)`.** It replaces the identical `:postmark` registrations in jumpdrive-web, fundbright-web and luminality-web, and the identical `register_prefix(:s3, ...)` in luminality-web, sidekick-web and nutripod-web. Each preset requires its SDK first (`postmark`, `aws-sdk-s3`) and raises `ArgumentError` if the SDK is missing. This matters when `aws-sdk-s3` is declared `require: false`: in that case `ErrorTaxonomies::Aws.tracked` evaluated at configure time contains only network errors. There is deliberately no `:stripe` preset, because the apps' Stripe registrations differ.
+- **Opt-in `config.mailer_retry`** (`true`, or `{ wait:, attempts:, jitter: }` over the defaults `90 / 5 / 0.15`; off by default). It installs `retry_on StandardCircuit::Mailer::CircuitOpenError` on `ActionMailer::MailDeliveryJob`. The install is idempotent and reload-safe, and it stands down if a `CircuitOpenError` handler is already present. On exhaustion it writes an error log line, sends a Sentry `:error` event and emits a new `standard_circuit.mailer.retries_exhausted` event, all carrying recipient domains only. It replaces `config/initializers/mail_delivery_retry.rb` in jumpdrive-web, sidekick-web and nutripod-web (their provider-specific retries and discards stay in the apps), and the `CircuitOpenError` `retry_on` in fundbright-web's `ApplicationMailDeliveryJob`. The Sentry fingerprint is new, so the first exhaustion after switching opens a new issue.
+- `StandardCircuit.deprecator`, registered as `Rails.application.deprecators[:standard_circuit]`.
+- `Config#add_notifier(notifier, key:)`: an optional `key:` for registering several instances of one notifier class (see Changed).
+- README sections: presets, mail delivery and `mailer_retry`, calling `configure` more than once, supported test API (`force_open`, `force_closed`, `reset_force!`, `reset!`, `standard_circuit/rspec`), and deprecations. Each feature has a "replace your host code with" snippet.
+
+### Changed
+- **`StandardCircuit::HealthController` is autoloaded by the engine.** It moved to `app/controllers/standard_circuit/health_controller.rb`, so drawing `get "/health", to: "standard_circuit/health#show"` is all a host needs. The boot probe spec now covers autoload, eager load and both legacy `require` placements. The install generator's `--with-health-endpoint` no longer writes `config/initializers/standard_circuit_health.rb`, which only ever contained the require; it prints the route hint.
+- **Repeated `configure` calls no longer stack notifiers.** Every consumer calls `configure` from `to_prepare`, which re-runs on every code reload. `add_notifier` now replaces an existing entry with the same identity in place: the same explicit `key:`, otherwise the same class name, or for procs and methods the same source location. The newest instance wins. `extra_notifiers` is deliberately not reset on each `configure`, because apps split configuration across several calls and a reset would silently drop notifiers added earlier.
+- **gemspec declares `actionmailer` and `actionpack` (`>= 8.0`).** `require "standard_circuit"` has always loaded both, but only `railties` was declared, and railties doesn't pull in actionmailer. `activestorage` stays undeclared because the S3 service is only ever loaded by ActiveStorage's own configurator. The SDKs stay optional. The gem package now includes `app/**`.
+
+### Deprecated
+Each item below still works and warns through `StandardCircuit.deprecator`. All are removed in 0.5.
+- `require "standard_circuit/health_controller"`: remove it, the controller is autoloaded. Carried in `config/routes.rb` by jumpdrive-web, fundbright-web and nutripod-web.
+- `StandardCircuit.health_snapshot` and `StandardCircuit.health_overall`: use `StandardCircuit.health_report[:circuits]` / `[:status]`. No consumer calls them.
+- `StandardCircuit::AdapterErrors::Faraday.caller_errors`: `Faraday::ClientError` is never tracked, so skipping it is a no-op. No consumer calls it. (`Aws.caller_errors` is kept because `default_skipped_for` uses it.)
+- `StandardCircuit::ActiveStorage::S3Service`: use `ActiveStorage::Service::StandardCircuitS3Service`, or `service: StandardCircuitS3` in storage.yml. No consumer references it.
+
+## [0.3.1] - 2026-09-24
+
+Two behaviour changes — both are bug fixes, but both change numbers or breaker behaviour you may be alerting on.
+
+### Fixed
+- **Circuit-open requests were counted twice in `<metric_prefix>.request`.** `Runner` already emits `<metric_prefix>.request{status: circuit_open}` when a call is rejected by a tripped or forced-open circuit; `ControllerSupport#handle_circuit_open` then emitted the same metric again when the `Stoplight::Error::RedLight` reached a controller. The controller-side emission (and the private `emit_circuit_open_metric` helper) is removed; fallback dispatch is unchanged. **Behaviour change:** `circuit_open` request counts for rejections that reach a controller drop by half, back to the true value — dashboards and alert thresholds tuned against the doubled number should be revisited.
+- **S3 caller errors tripped the S3 breaker.** `ErrorTaxonomies::Aws.tracked` includes `Aws::Errors::ServiceError`, which is the superclass of `Aws::S3::Errors::AccessDenied` and `NoSuchKey` as well as of the dynamically generated 5xx errors, so a burst of missing-key lookups or permission errors opened the circuit. New `ErrorTaxonomies.default_skipped_for(tracked)` returns the AWS caller errors whenever the tracked list covers them, and `register` / `register_prefix` now use it as the default `skipped_errors`. **Behaviour change:** AWS circuits registered without `skipped_errors:` no longer count `AccessDenied` / `NoSuchKey` toward the threshold; 5xx (`ServiceUnavailable` etc.) and `Seahorse::Client::NetworkingError` still trip. An explicit `skipped_errors:` — including `[]` — always wins, and circuits for other adapters keep defaulting to `[]`.
+
+### Added
+- Specs for `NetworkErrors` and the Stripe / AWS / Faraday / SMTP `AdapterErrors` modules.
+- README section on error taxonomies and the AWS `skipped_errors` default; the initializer template notes it too.
+
+### Documentation
+- **Consumer list corrected in `CLAUDE.md`: this gem has five consumers, not four.** `sidekick-web` was missing. The same entry also claimed the `workspace-os` → `jumpdrive-web` directory rename "was deferred" and pointed at `~/Workspace/rarebit-one/workspace-os`; that rename completed 2026-07-14 and the old husk is gone, so an agent following the note was looking in a directory that no longer exists. Verified against the canonical matrix in the workspace's `rollout-gem/SKILL.md`, which the new advisory `check-gem-family-drift.sh` now diffs this list against on every sweep.
+
 ## [0.3.0] - 2026-07-30
 
 ### Added

data/README.md

@@ -5,10 +5,10 @@ Circuit breaker primitives for Rails apps, built on [stoplight](https://github.c
 Wraps the upstream `stoplight` gem with:
 
 - Opinionated default error taxonomy (network errors track; caller/config errors do not)
-- SDK-specific adapter error bundles (Stripe, AWS, Faraday, SMTP)
+- SDK-specific adapter error bundles (Stripe, AWS, Faraday, SMTP, Postmark) and circuit presets (`:postmark`, `:s3`)
 - Rails event emission (`standard_circuit.circuit.{opened,closed,degraded,fallback_invoked,registered}`) with built-in Logger, Sentry, and Sentry::Metrics subscribers
 - ActiveStorage S3 adapter with per-bucket circuit keying
-- Generic ActionMailer delivery-method wrapper (supports both instance and symbol `underlying:` forms)
+- Generic ActionMailer delivery-method wrapper (supports both instance and symbol `underlying:` forms) with opt-in `mailer_retry` for `deliver_later` jobs
 - Controller concern for standardized 503 responses on `Stoplight::Error::RedLight`
 - Test helpers (`force_open`, `force_closed`, `reset_force!`) with RSpec auto-cleanup
 
@@ -27,10 +27,8 @@ bundle add standard_circuit
 rails g standard_circuit:install
 ```
 
-Pass `--with-health-endpoint` to also generate
-`config/initializers/standard_circuit_health.rb` (which requires the opt-in
-health controller); the generator prints the matching route line for you to
-add to `config/routes.rb`.
+Pass `--with-health-endpoint` to also print the route line for the health
+endpoint, for you to add to `config/routes.rb`.
 
 The generator is idempotent — re-running skips an existing initializer
 unless you pass `--force`.
@@ -58,6 +56,58 @@ StandardCircuit.run(:stripe) do
 end
 ```
 
+## Error taxonomies
+
+`tracked_errors` decide what counts toward tripping a circuit; `skipped_errors` are re-raised without counting (and win over `tracked_errors` when a class matches both). `StandardCircuit::ErrorTaxonomies::<Adapter>.tracked` combines `NetworkErrors.defaults` with the adapter's server-side errors for `Stripe`, `Smtp`, `Aws`, `Faraday`, and `Postmark`; `StandardCircuit::AdapterErrors::<Adapter>.caller_errors` lists the adapter's caller-side (4xx-style) errors.
+
+When `skipped_errors:` is omitted it defaults to `[]` — except when the tracked list covers the AWS or Postmark caller errors. (Postmark's `ApiInputError` and `InvalidApiKeyError` subclass `Postmark::HttpServerError`, so a circuit tracking `ErrorTaxonomies::Postmark.tracked` without `skipped_errors:` defaults to skipping them.) AWS 5xx responses are dynamically generated `Aws::Errors::ServiceError` subclasses, so `ErrorTaxonomies::Aws.tracked` has to track `ServiceError` itself, which is also the superclass of `Aws::S3::Errors::AccessDenied` and `NoSuchKey`. So for such circuits `skipped_errors` defaults to `AdapterErrors::Aws.caller_errors` (via `ErrorTaxonomies.default_skipped_for`), and a burst of missing-key lookups or permission errors no longer trips the S3 breaker:
+
+```ruby
+StandardCircuit.configure do |c|
+  # skipped_errors defaults to [Aws::S3::Errors::NoSuchKey, Aws::S3::Errors::AccessDenied]
+  c.register_prefix(:s3, tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked)
+
+  # An explicit skipped_errors — even [] — always wins over the default.
+  # c.register(:s3_strict, tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked, skipped_errors: [])
+end
+```
+
+## Presets
+
+Some integrations were registered identically, line for line, in several apps. `c.register_preset` registers them with the shared settings; any `register` option you pass alongside wins, and `name:` renames the circuit.
+
+| Preset | Registers | Settings |
+|--------|-----------|----------|
+| `:postmark` | `register(:postmark, ...)` | threshold 3, cool-off 60s, `:standard`, `ErrorTaxonomies::Postmark.tracked`, skips `AdapterErrors::Postmark.caller_errors` |
+| `:s3` | `register_prefix(:s3, ...)` — matches the `s3_<bucket>` circuits `StandardCircuitS3` opens | threshold 3, cool-off 30s, `:standard`, `ErrorTaxonomies::Aws.tracked`, skips `NoSuchKey` / `AccessDenied` |
+
+Each preset requires its SDK (`postmark`, `aws-sdk-s3`) before building the error lists and raises `ArgumentError` if the gem is missing. That matters for `gem "aws-sdk-s3", require: false`: `ErrorTaxonomies::Aws.tracked` returns only network errors when the SDK hasn't been loaded yet at configure time, which quietly leaves S3 5xx responses untracked.
+
+Replace your host code with:
+
+```ruby
+# Before — config/initializers/standard_circuit.rb
+c.register(:postmark,
+  threshold: 3,
+  cool_off_time: 60,
+  criticality: :standard,
+  tracked_errors: StandardCircuit::NetworkErrors.defaults +
+                  [ Postmark::HttpServerError, Postmark::TimeoutError ],
+  skipped_errors: [ Postmark::ApiInputError, Postmark::InvalidApiKeyError ])
+
+c.register_prefix(:s3,
+  threshold: 3,
+  cool_off_time: 30,
+  criticality: :standard,
+  tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked)
+
+# After
+c.register_preset(:postmark)
+c.register_preset(:s3)
+```
+
+There is deliberately no `:stripe` preset — the apps that wrap Stripe disagree on threshold, criticality, and skips, so `ErrorTaxonomies::Stripe.tracked` stays the shared piece.
+
 ## Circuit state storage (`data_store`)
 
 Circuit state (failure counts, colors, locks) lives in a Stoplight data store. StandardCircuit defaults to `Stoplight::DataStore::Memory.new`, which is **per-process**: each Puma worker, Sidekiq/SolidQueue worker, and console gets its own independent view of every circuit.
@@ -140,6 +190,85 @@ StandardCircuit.configure do |c|
 end
 ```
 
+## Mail delivery
+
+The `:standard_circuit` delivery method wraps any registered ActionMailer delivery method in a circuit and raises `StandardCircuit::Mailer::CircuitOpenError` (instead of attempting the send) while that circuit is open:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :standard_circuit
+config.action_mailer.standard_circuit_settings = {
+  underlying: :postmark,
+  underlying_settings: { api_token: ENV.fetch("POSTMARK_API_TOKEN") },
+  circuit: :postmark
+}
+```
+
+### Retrying `deliver_later` while the circuit is open (`mailer_retry`)
+
+Without a retry, a `deliver_later` job that runs during an outage fails once and the email is lost. Opt in and the gem installs `retry_on CircuitOpenError` on `ActionMailer::MailDeliveryJob`:
+
+```ruby
+StandardCircuit.configure do |c|
+  c.mailer_retry = true                        # wait: 90, attempts: 5, jitter: 0.15
+  # c.mailer_retry = { wait: 120, attempts: 8 } # partial overrides; wait: takes anything retry_on does
+end
+```
+
+- **Off by default.** Nothing is installed unless you set it.
+- **Keep `wait` longer than the mail circuit's `cool_off_time`** (the `:postmark` preset uses 60s), or retries land on a circuit that is still open.
+- **Reload-safe and idempotent.** Calling `configure` from `to_prepare` on every reload installs the handler once. If a `retry_on CircuitOpenError` is already on the job (for example your old initializer, during migration), the gem leaves it alone. The first install wins, so changing the options later needs a restart.
+- **Subclasses inherit it.** A custom `self.delivery_job = MyJob < ActionMailer::MailDeliveryJob` gets the handler, and a `retry_on CircuitOpenError` declared on the subclass takes precedence.
+- **On exhaustion** it writes one `error` log line, sends a Sentry `:error` event (when `sentry_enabled` and Sentry is initialized, fingerprinted by mailer and action), and emits `standard_circuit.mailer.retries_exhausted`. Every payload holds only `mailer_class`, `mail_action`, `recipient_domains`, `job_id` and `executions`: recipient **domains**, never addresses or subjects.
+- Only `CircuitOpenError` is retried. Errors from the provider while the circuit is closed, such as a SendGrid 429 or a Postmark 422, keep their existing behaviour. Add your own `retry_on` / `discard_on` for those.
+
+Replace your host code with:
+
+```ruby
+# Before — config/initializers/mail_delivery_retry.rb (~40–60 lines)
+Rails.application.config.to_prepare do
+  next if ActionMailer::MailDeliveryJob.rescue_handlers.any? { |h| h.first == StandardCircuit::Mailer::CircuitOpenError.name }
+
+  ActionMailer::MailDeliveryJob.retry_on(StandardCircuit::Mailer::CircuitOpenError,
+    wait: 90.seconds, attempts: 5, jitter: 0.15) do |job, error|
+    # ...recipient-domain extraction, Rails.logger.error, Sentry.capture_message...
+  end
+end
+
+# After — inside your existing StandardCircuit.configure block
+c.mailer_retry = true
+# or, keeping ENV tunables:
+c.mailer_retry = {
+  wait: ENV.fetch("SENDGRID_CIRCUIT_RETRY_WAIT", 90).to_i,
+  attempts: ENV.fetch("SENDGRID_CIRCUIT_RETRY_ATTEMPTS", 5).to_i
+}
+```
+
+The Sentry fingerprint changes to `["standard_circuit-mailer-retries-exhausted", mailer, action]`, so the first exhaustion after switching opens a new Sentry issue rather than regrouping into your old one.
+
+### Calling `configure` more than once
+
+`configure` is safe to call repeatedly. Apps register circuits from `to_prepare` because it's the first point where autoloaded error classes are available, and `to_prepare` re-runs on every code reload. Each call re-applies the config and rebuilds the subscribers. `add_notifier` is idempotent: adding "the same" notifier again replaces the earlier entry in place and does not stack a duplicate. Two notifiers are the same when they share an explicit `key:`, or else the same class name (a reloaded class is a new object with the same name), or for lambdas and methods the same source location. The newest instance wins. To register two instances of one class, give them distinct keys:
+
+```ruby
+c.add_notifier(WebhookNotifier.new(ops_url), key: :ops)
+c.add_notifier(WebhookNotifier.new(audit_url), key: :audit)
+```
+
+Replace your host code with:
+
+```ruby
+# Before — hand-rolled guard against stacking a notifier on every reload
+unless c.extra_notifiers.any? { |n| n.class.name == "CircuitAuditNotifier" }
+  c.add_notifier(CircuitAuditNotifier.new)
+end
+
+# After
+c.add_notifier(CircuitAuditNotifier.new)
+```
+
+Circuit registrations (`register` / `register_prefix` / `register_preset`) were already idempotent: the same name overwrites.
+
 ## Streaming and non-controller contexts
 
 `ControllerSupport.circuit_open_fallback` only works for non-streaming responses — once a `Live` controller has flushed any output, Rails can't render an error template over the wire. For a streaming controller, catch `Stoplight::Error::RedLight` *inside* the streaming proc and write a degraded payload before the stream closes:
@@ -174,19 +303,28 @@ Same pattern applies in background jobs (where `circuit_open_fallback` doesn't h
 
 ## Health endpoint
 
-StandardCircuit ships an opt-in controller that renders `StandardCircuit.health_report` as JSON. It returns 503 when the rolled-up status is `:critical` (so orchestrators pull the instance out of rotation) and 200 otherwise.
+StandardCircuit ships a controller that renders `StandardCircuit.health_report` as JSON. It returns 503 when the rolled-up status is `:critical` (so orchestrators pull the instance out of rotation) and 200 otherwise.
 
-It's opt-in — not auto-required — so apps that don't want a health route don't pay for it.
+The controller lives in the engine's `app/controllers`, so it is autoloaded. The route is the only opt-in, and apps that don't draw it never load the controller.
 
 ```ruby
 # config/routes.rb
-require "standard_circuit/health_controller"
-
 Rails.application.routes.draw do
   get "/health", to: "standard_circuit/health#show"
 end
 ```
 
+Replace your host code with:
+
+```ruby
+# Before — top of config/routes.rb (or config/initializers/standard_circuit_health.rb)
+require "standard_circuit/health_controller"
+
+# After — delete the line (and the initializer, if that's all it contained).
+```
+
+The old `require` still works in 0.4 but emits a deprecation through `Rails.application.deprecators[:standard_circuit]`. It will be removed in 0.5.
+
 The controller inherits from `ActionController::API` to sidestep app-level filters (authentication, bootstrap redirects, etc.) so probes can call it anonymously.
 
 **If your app also mounts `StandardHealth::Engine` at `/health`, draw the aggregate route first:**
@@ -198,6 +336,32 @@ mount StandardHealth::Engine => "/health", as: :standard_health
 
 `StandardHealth::Engine` registers sub-paths only (`/alive`, `/ready`, `/diagnostics/env`) — it never serves the aggregate tier itself. An app that mounts the engine and assumes `/health` is covered silently has no aggregate tier at all, with no boot error and no failing route spec to reveal it. The ordering is load-bearing; draw the aggregate route explicitly, first.
 
+## Test API
+
+These are supported public API for host test suites, not internals:
+
+| Method | What it does |
+|--------|--------------|
+| `StandardCircuit.force_open(name) { ... }` | Treat `name` as open for the block (or until `reset_force!` without a block): `run` raises `Stoplight::Error::RedLight`, or returns the fallback. Emits the same `run.completed` / `fallback_invoked` events as a real open circuit. |
+| `StandardCircuit.force_closed(name) { ... }` | Bypass the circuit for the block — `run` just yields. No events. |
+| `StandardCircuit.reset_force!` | Clear every forced state. |
+| `StandardCircuit.reset!` | Clear the light cache and forced states, and swap in a fresh `Memory` data store (left alone when the store is Redis). |
+| `require "standard_circuit/rspec"` | Adds a `before(:each)` that runs `reset!` and tears down subscribers. Circuit registrations are kept. |
+
+All of these are **process-local**. They are test and console tools, not an operational kill switch (see `data_store` above).
+
+## Deprecations
+
+0.4 deprecates the following. Each still works and warns through `Rails.application.deprecators[:standard_circuit]`, so your app's `config.active_support.deprecation` setting applies. They will be removed in 0.5.
+
+| Deprecated | Use instead |
+|------------|-------------|
+| `require "standard_circuit/health_controller"` | nothing — the controller is autoloaded |
+| `StandardCircuit.health_snapshot` | `StandardCircuit.health_report[:circuits]` |
+| `StandardCircuit.health_overall` | `StandardCircuit.health_report[:status]` |
+| `StandardCircuit::AdapterErrors::Faraday.caller_errors` | drop it — `Faraday::ClientError` is never tracked, so skipping it is a no-op |
+| `StandardCircuit::ActiveStorage::S3Service` | `ActiveStorage::Service::StandardCircuitS3Service` / `service: StandardCircuitS3` |
+
 ## License
 
 MIT

data/app/controllers/standard_circuit/health_controller.rb

@@ -0,0 +1,28 @@
+module StandardCircuit
+  # Health-check controller. Renders +StandardCircuit.health_report+ as JSON
+  # and returns 503 when the rolled-up status is +:critical+ so upstream
+  # orchestrators pull the instance out of rotation. :degraded and :ok both
+  # return 200 — the app can still serve most traffic.
+  #
+  # Autoloaded by the engine (it lives under app/controllers), so a host only
+  # draws the route — no `require` needed:
+  #
+  #   # config/routes.rb
+  #   Rails.application.routes.draw do
+  #     get "/health", to: "standard_circuit/health#show"
+  #   end
+  #
+  # The pre-0.4 `require "standard_circuit/health_controller"` still works but
+  # is deprecated (see lib/standard_circuit/health_controller.rb).
+  #
+  # Inherits from +ActionController::API+ to sidestep any ApplicationController
+  # filters (authentication, bootstrap redirects, etc.) — health probes must be
+  # callable anonymously from load balancers and uptime monitors.
+  class HealthController < ::ActionController::API
+    def show
+      report = StandardCircuit.health_report
+      http_status = report[:status] == :critical ? :service_unavailable : :ok
+      render json: report, status: http_status
+    end
+  end
+end

data/lib/generators/standard_circuit/install/install_generator.rb

@@ -7,10 +7,10 @@ module StandardCircuit
     # By default, writes config/initializers/standard_circuit.rb with
     # commented-out examples covering the public Config DSL.
     #
-    # When +--with-health-endpoint+ is passed, also writes
-    # config/initializers/standard_circuit_health.rb (which requires the
-    # opt-in HealthController) and prints the route line the host should
-    # add to config/routes.rb to expose the endpoint.
+    # When +--with-health-endpoint+ is passed, also prints the route line the
+    # host should add to config/routes.rb to expose the endpoint. (Before 0.4
+    # it also wrote config/initializers/standard_circuit_health.rb to require
+    # the controller; the engine now autoloads it, so no file is needed.)
     #
     # Idempotent: re-running on an existing initializer logs and skips. Pass
     # +--force+ to overwrite.
@@ -23,17 +23,16 @@ module StandardCircuit
         covering circuit registration, prefix registration, and notifier
         wiring.
 
-        Pass --with-health-endpoint to also write
-        config/initializers/standard_circuit_health.rb (which requires the
-        opt-in HealthController) and print the route line to add to
-        config/routes.rb.
+        Pass --with-health-endpoint to also print the route line to add to
+        config/routes.rb. The health controller is autoloaded by the engine,
+        so the route is all you need.
 
         The generator is idempotent — already-installed initializers are
         skipped with a clear message. Pass --force to overwrite.
       DESC
 
       class_option :with_health_endpoint, type: :boolean, default: false,
-        desc: "Also create config/initializers/standard_circuit_health.rb and print the route hint"
+        desc: "Also print the config/routes.rb line for the health endpoint"
 
       def create_initializer_file
         path = "config/initializers/standard_circuit.rb"
@@ -45,25 +44,15 @@ module StandardCircuit
         template "initializer.rb.tt", path
       end
 
-      def create_health_initializer_file
-        return unless options[:with_health_endpoint]
-
-        path = "config/initializers/standard_circuit_health.rb"
-        if File.exist?(File.join(destination_root, path)) && !options[:force]
-          say_status("skip", "#{path} already present, skipping (use --force to overwrite)", :yellow)
-        else
-          template "health_initializer.rb.tt", path
-        end
-      end
-
       def print_health_route_hint
         return unless options[:with_health_endpoint]
 
         say ""
         say "=" * 79
-        say "StandardCircuit health endpoint installed."
+        say "StandardCircuit health endpoint"
         say ""
-        say "Add the following to config/routes.rb to expose the endpoint:"
+        say "Add the following to config/routes.rb to expose the endpoint (the"
+        say "controller is autoloaded by the engine — no require needed):"
         say ""
         say '  get "/health", to: "standard_circuit/health#show"'
         say ""

data/lib/generators/standard_circuit/install/templates/initializer.rb.tt

@@ -37,6 +37,14 @@ StandardCircuit.configure do |config|
   # Default: nil
   # config.logger = Rails.logger
 
+  # Retry ActionMailer::MailDeliveryJob on
+  # StandardCircuit::Mailer::CircuitOpenError while the mail circuit is open.
+  # Keep `wait` longer than the mail circuit's cool_off_time. On exhaustion:
+  # error log + Sentry :error (recipient domains only).
+  #   true -> { wait: 90, attempts: 5, jitter: 0.15 }
+  # Default: nil (off)
+  # config.mailer_retry = true
+
   # Stoplight data store. Default: in-memory (per-process). Use a shared
   # store (e.g. Stoplight::DataStore::Redis) when you want circuit state
   # shared across processes/hosts.
@@ -54,7 +62,10 @@ StandardCircuit.configure do |config|
   #   tracked_errors  — error classes that count toward the threshold
   #                     (default: StandardCircuit::NetworkErrors.defaults)
   #   skipped_errors  — error classes that bypass the circuit (re-raised
-  #                     without counting — typically caller/validation errors)
+  #                     without counting — typically caller/validation errors;
+  #                     default: [], or the AWS / Postmark caller errors
+  #                     when tracked_errors covers them — see
+  #                     StandardCircuit::ErrorTaxonomies.default_skipped_for)
   #   criticality     — :critical | :standard | :optional
   #                     (affects health rollup; default: :standard)
 
@@ -69,12 +80,20 @@ StandardCircuit.configure do |config|
   #   tracked_errors: StandardCircuit::ErrorTaxonomies::Smtp.tracked,
   #   criticality: :standard)
 
+  # Presets for integrations with shared settings (any option passed wins):
+  #   :postmark — register(:postmark, ...) with the Postmark taxonomy + skips
+  #   :s3       — register_prefix(:s3, ...) for `service: StandardCircuitS3`
+  # config.register_preset(:postmark)
+  # config.register_preset(:s3)
+
   # ---------------------------------------------------------------------------
   # Prefix registration
   # ---------------------------------------------------------------------------
   # Use `register_prefix` to dynamically name circuits matching a pattern.
   # The first matching prefix wins; the circuit name is "<prefix>_<suffix>".
 
+  # AWS caller errors (NoSuchKey, AccessDenied) are skipped by default here,
+  # so missing keys and permission errors don't trip the S3 breaker.
   # config.register_prefix(:s3,
   #   threshold: 10,
   #   tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked,
@@ -91,11 +110,14 @@ StandardCircuit.configure do |config|
   # contract as the built-in subscribers.
 
   # config.add_notifier(->(name, payload) { MyTracer.record(name, payload) })
+  # Idempotent across repeated configure calls (e.g. from to_prepare):
+  # re-adding the same notifier replaces it rather than stacking a duplicate.
 
   # ---------------------------------------------------------------------------
   # Health endpoint (see --with-health-endpoint)
   # ---------------------------------------------------------------------------
   # The aggregate route is `get "/health", to: "standard_circuit/health#show"`.
+  # The controller is autoloaded by the engine — no require needed.
   # If your app also mounts StandardHealth::Engine at "/health", draw the
   # aggregate route BEFORE the mount. That engine registers sub-paths only
   # ("/alive", "/ready", "/diagnostics/env") and never serves the aggregate tier

data/lib/standard_circuit/active_storage/s3_service.rb

@@ -35,7 +35,15 @@ module ActiveStorage
 end
 
 module StandardCircuit
+  # @deprecated The StandardCircuit::ActiveStorage::S3Service alias is unused —
+  # storage.yml resolves `service: StandardCircuitS3` to
+  # ActiveStorage::Service::StandardCircuitS3Service — and is removed in 0.5.
   module ActiveStorage
-    S3Service = ::ActiveStorage::Service::StandardCircuitS3Service
+    include ::ActiveSupport::Deprecation::DeprecatedConstantAccessor
+
+    deprecate_constant "S3Service", "::ActiveStorage::Service::StandardCircuitS3Service",
+      deprecator: StandardCircuit.deprecator,
+      message: "StandardCircuit::ActiveStorage::S3Service is deprecated and will be removed in 0.5; " \
+               "use ActiveStorage::Service::StandardCircuitS3Service (or `service: StandardCircuitS3` in storage.yml)."
   end
 end

data/lib/standard_circuit/adapter_errors/faraday.rb

@@ -10,7 +10,15 @@ module StandardCircuit
           errors.select { |klass| klass.is_a?(Class) }
         end
 
+        # @deprecated Removed in 0.5. Faraday::ClientError (4xx) is not in
+        # +server_errors+, so it never counts toward a Faraday circuit —
+        # listing it in +skipped_errors+ is a no-op. Unused by every consumer.
         def caller_errors
+          StandardCircuit.deprecator.warn(
+            "StandardCircuit::AdapterErrors::Faraday.caller_errors is deprecated and will be removed in 0.5: " \
+            "Faraday::ClientError is never tracked by ErrorTaxonomies::Faraday.tracked, so skipping it is a no-op. " \
+            "Drop it from skipped_errors."
+          )
           return [] unless defined?(::Faraday::ClientError)
 
           [ ::Faraday::ClientError ]

data/lib/standard_circuit/adapter_errors/postmark.rb

@@ -0,0 +1,31 @@
+module StandardCircuit
+  module AdapterErrors
+    # Postmark (the `postmark` gem, usually via `postmark-rails`).
+    #
+    # Guarded like the other adapters: every method returns `[]` when the
+    # postmark gem isn't loaded, so this file is safe to require in apps that
+    # don't send mail through Postmark.
+    #
+    # Postmark's error hierarchy is the reason `caller_errors` matters here:
+    # `ApiInputError` (422 — invalid payload, inactive recipient, 429-style
+    # throttling) and `InvalidApiKeyError` (401 — rotated / revoked token) both
+    # subclass `HttpServerError`, and Stoplight matches tracked errors with
+    # `is_a?`. Tracking `HttpServerError` without skipping them would let a
+    # burst of bad payloads or a config bug trip the breaker.
+    module Postmark
+      class << self
+        def server_errors
+          return [] unless defined?(::Postmark::HttpServerError)
+
+          [ ::Postmark::HttpServerError, ::Postmark::TimeoutError ]
+        end
+
+        def caller_errors
+          return [] unless defined?(::Postmark::HttpServerError)
+
+          [ ::Postmark::ApiInputError, ::Postmark::InvalidApiKeyError ]
+        end
+      end
+    end
+  end
+end

data/lib/standard_circuit/config.rb

@@ -5,6 +5,10 @@ module StandardCircuit
     DEFAULT_WINDOW = 60
     DEFAULT_CRITICALITY = :standard
     CRITICALITIES = [ :critical, :standard, :optional ].freeze
+    # 90s > the :postmark preset's 60s cool-off, so a retry lands after the
+    # breaker has had a chance to half-open. 5 attempts ≈ 7.5 minutes; 15%
+    # jitter so a backlog queued during an outage doesn't retry in lockstep.
+    MAILER_RETRY_DEFAULTS = { wait: 90, attempts: 5, jitter: 0.15 }.freeze
 
     CircuitSpec = Struct.new(
       :threshold,
@@ -22,19 +26,24 @@ module StandardCircuit
             "invalid criticality #{criticality.inspect}; must be one of #{CRITICALITIES.inspect}"
         end
 
+        tracked_errors = opts.fetch(:tracked_errors, NetworkErrors.defaults)
+
         new(
           threshold: opts.fetch(:threshold, DEFAULT_THRESHOLD),
           cool_off_time: opts.fetch(:cool_off_time, DEFAULT_COOL_OFF),
           window_size: opts.fetch(:window_size, DEFAULT_WINDOW),
-          tracked_errors: opts.fetch(:tracked_errors, NetworkErrors.defaults),
-          skipped_errors: opts.fetch(:skipped_errors, []),
+          tracked_errors: tracked_errors,
+          # An explicit `skipped_errors:` (including `[]`) always wins; the
+          # default only kicks in when the key is absent. See
+          # ErrorTaxonomies.default_skipped_for for why AWS needs one.
+          skipped_errors: opts.fetch(:skipped_errors) { ErrorTaxonomies.default_skipped_for(tracked_errors) },
           criticality: criticality
         )
       end
     end
 
     attr_accessor :sentry_enabled, :metric_prefix, :data_store, :logger
-    attr_reader :circuits, :prefixes, :extra_notifiers, :sentry_criticality_levels
+    attr_reader :circuits, :prefixes, :extra_notifiers, :sentry_criticality_levels, :mailer_retry
 
     def initialize
       @sentry_enabled = true
@@ -45,6 +54,22 @@ module StandardCircuit
       @circuits = {}
       @prefixes = {}
       @extra_notifiers = []
+      @extra_notifier_keys = []
+      @mailer_retry = nil
+    end
+
+    # Opt in to retrying ActionMailer::MailDeliveryJob on
+    # StandardCircuit::Mailer::CircuitOpenError (see Mailer::Retry). Accepts:
+    #
+    #   nil / false — (default) off; the gem installs nothing.
+    #   true        — MAILER_RETRY_DEFAULTS (wait: 90, attempts: 5, jitter: 0.15)
+    #   Hash        — MAILER_RETRY_DEFAULTS merged with :wait / :attempts /
+    #                 :jitter. `wait:` takes anything `retry_on` does (seconds,
+    #                 a Duration, :polynomially_longer, a Proc).
+    #
+    # The reader returns nil or a frozen, complete Hash.
+    def mailer_retry=(value)
+      @mailer_retry = normalize_mailer_retry(value)
     end
 
     # Opt in to criticality-aware Sentry reporting for the built-in Sentry
@@ -67,6 +92,7 @@ module StandardCircuit
       @circuits.clear
       @prefixes.clear
       @extra_notifiers.clear
+      @extra_notifier_keys.clear
     end
 
     def register(name, **opts)
@@ -89,16 +115,53 @@ module StandardCircuit
       spec
     end
 
+    # Register a circuit from a named preset (see StandardCircuit::Presets):
+    #
+    #   c.register_preset(:postmark)                  # c.register(:postmark, ...)
+    #   c.register_preset(:s3)                        # c.register_prefix(:s3, ...)
+    #   c.register_preset(:postmark, name: :mail, threshold: 5)
+    #
+    # +name:+ overrides the circuit name (or prefix); any other keyword is a
+    # `register` option that wins over the preset's value.
+    def register_preset(preset, name: preset, **overrides)
+      scope, opts = Presets.resolve(preset, **overrides)
+      scope == :prefix ? register_prefix(name, **opts) : register(name, **opts)
+    end
+
     # Register a host-supplied subscriber. Subscribers must respond to
     # `call(event_name, payload)` — Stoplight-shaped 4-arg notifiers from the
     # 0.1.x API are no longer accepted as extras (Logger / Sentry / Metrics
     # demonstrate the new shape).
-    def add_notifier(notifier)
+    #
+    # Idempotent: hosts call `configure` from `to_prepare`, which re-runs on
+    # every code reload, so re-adding "the same" notifier replaces the earlier
+    # entry in place instead of stacking a duplicate. "The same" means the same
+    # +key:+ when one is given, otherwise:
+    #
+    #   * a Proc / Method — same source location (a lambda re-created on reload)
+    #   * a Class / Module used directly — same name
+    #   * any other object — same class name (a reloaded class is a new class
+    #     object with the same name, so compare names, not classes)
+    #   * an instance of an anonymous class — never deduped
+    #
+    # The newest instance wins, so a reloaded notifier class takes effect.
+    # Pass distinct +key:+ values to register two instances of one class
+    # (e.g. two webhook notifiers pointed at different URLs).
+    def add_notifier(notifier, key: nil)
       unless notifier.respond_to?(:call)
         raise ArgumentError,
           "extra notifiers must respond to `call(event_name, payload)`; got #{notifier.class}"
       end
-      @extra_notifiers << notifier
+
+      identity = key.nil? ? notifier_identity(notifier) : [ :key, key ]
+      index = identity && @extra_notifier_keys.index(identity)
+      if index
+        @extra_notifiers[index] = notifier
+      else
+        @extra_notifiers << notifier
+        @extra_notifier_keys << identity
+      end
+      notifier
     end
 
     def spec_for(name)
@@ -119,6 +182,33 @@ module StandardCircuit
       end
     end
 
+    def notifier_identity(notifier)
+      if notifier.respond_to?(:source_location) && notifier.source_location
+        [ :source, notifier.source_location ]
+      elsif notifier.is_a?(Module)
+        notifier.name && [ :module, notifier.name ]
+      else
+        notifier.class.name && [ :class, notifier.class.name ]
+      end
+    end
+
+    def normalize_mailer_retry(value)
+      case value
+      when nil, false then nil
+      when true       then MAILER_RETRY_DEFAULTS
+      when Hash
+        options = value.transform_keys(&:to_sym)
+        unknown = options.keys - MAILER_RETRY_DEFAULTS.keys
+        unless unknown.empty?
+          raise ArgumentError,
+            "unknown mailer_retry option(s) #{unknown.inspect}; allowed: #{MAILER_RETRY_DEFAULTS.keys.inspect}"
+        end
+        MAILER_RETRY_DEFAULTS.merge(options).freeze
+      else
+        raise ArgumentError, "mailer_retry must be nil, true, false, or a Hash; got #{value.class}"
+      end
+    end
+
     def merge_sentry_criticality_levels(map)
       normalized = map.to_h do |criticality, level|
         # Check symbolizability before coercing: a key like 42 would otherwise

data/lib/standard_circuit/controller_support.rb

@@ -47,9 +47,10 @@ module StandardCircuit
 
     private
 
-    def handle_circuit_open(error)
+    def handle_circuit_open(_error)
+      # No metric here: Runner already counted this rejection as
+      # `<metric_prefix>.request{status: circuit_open}` before re-raising.
       fallback = self.class._circuit_open_fallback || {}
-      emit_circuit_open_metric(error)
 
       return instance_exec(&fallback[:json]) if request.format.json? && fallback[:json]
       return instance_exec(response, &fallback[:stream]) if streaming_controller? && fallback[:stream]
@@ -61,14 +62,5 @@ module StandardCircuit
     def streaming_controller?
       defined?(::ActionController::Live) && self.class.include?(::ActionController::Live)
     end
-
-    def emit_circuit_open_metric(error)
-      prefix = StandardCircuit.config.metric_prefix
-      ::Sentry::Metrics.count(
-        "#{prefix}.request",
-        value: 1,
-        attributes: { service: error.light_name, status: "circuit_open" }
-      )
-    end
   end
 end

data/lib/standard_circuit/deprecator.rb

@@ -0,0 +1,12 @@
+require "active_support"
+require "active_support/deprecation"
+
+module StandardCircuit
+  # The gem's ActiveSupport::Deprecation instance. Registered with the host as
+  # `Rails.application.deprecators[:standard_circuit]` by the engine, so the
+  # host's `config.active_support.deprecation` behaviour (log / raise /
+  # silence / report) applies to StandardCircuit deprecations too.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("0.5", "StandardCircuit")
+  end
+end

data/lib/standard_circuit/engine.rb

@@ -23,12 +23,19 @@ module StandardCircuit
     #   spec/integration/health_route_boot_spec.rb, which fails if this ever
     #   regresses).
     #
+    # `StandardCircuit::HealthController` lives in the engine's app/controllers
+    # and is autoloaded (and eager-loaded in production) by the host.
+    #
     # One real consequence: `StandardCircuit::HealthController` now picks up the
     # engine's (empty) url_helpers instead of the application's, so app path
     # helpers inside it — or inside a host subclass of it — need a `main_app.`
     # prefix. The controller only renders JSON, so nothing in-gem is affected.
     isolate_namespace StandardCircuit
 
+    initializer "standard_circuit.deprecator" do |app|
+      app.deprecators[:standard_circuit] = StandardCircuit.deprecator if app.respond_to?(:deprecators)
+    end
+
     initializer "standard_circuit.subscribers", after: :load_config_initializers do
       StandardCircuit.subscribers.setup!
     end

data/lib/standard_circuit/error_taxonomies.rb

@@ -16,6 +16,34 @@ module StandardCircuit
   # `AdapterErrors::*` because the right `skipped_errors` set is usually
   # app-specific and a shared taxonomy would over-skip.
   module ErrorTaxonomies
+    # Default `skipped_errors` for a circuit registered without an explicit
+    # `skipped_errors:`. Most adapters default to `[]`, but two can't, because
+    # their server-side error class is also the superclass of caller errors:
+    #
+    # * AWS — 5xx errors are dynamically generated `Aws::Errors::ServiceError`
+    #   subclasses (e.g. `Aws::S3::Errors::ServiceUnavailable`), so `Aws.tracked`
+    #   has to track `ServiceError` itself — which is also the superclass of
+    #   `AccessDenied` and `NoSuchKey`. Without a skip list, a burst of
+    #   missing-key lookups or permission errors would trip the S3 breaker.
+    # * Postmark — `ApiInputError` and `InvalidApiKeyError` subclass
+    #   `Postmark::HttpServerError`, which `Postmark.tracked` tracks.
+    #
+    # Returns the caller errors that some entry of +tracked+ covers (is the
+    # same class or an ancestor of), or `[]` when none are covered. Returns a
+    # fresh array each call.
+    def self.default_skipped_for(tracked)
+      trackable = Array(tracked).grep(Module)
+      covered_caller_errors.select do |caller_error|
+        trackable.any? { |klass| caller_error <= klass }
+      end
+    end
+
+    # @api private
+    def self.covered_caller_errors
+      AdapterErrors::Aws.caller_errors + AdapterErrors::Postmark.caller_errors
+    end
+    private_class_method :covered_caller_errors
+
     module Stripe
       def self.tracked
         NetworkErrors.defaults + AdapterErrors::Stripe.server_errors
@@ -39,5 +67,13 @@ module StandardCircuit
         NetworkErrors.defaults + AdapterErrors::Faraday.server_errors
       end
     end
+
+    # Pair with `skipped_errors: AdapterErrors::Postmark.caller_errors` — or
+    # omit `skipped_errors:` and let `default_skipped_for` supply it.
+    module Postmark
+      def self.tracked
+        NetworkErrors.defaults + AdapterErrors::Postmark.server_errors
+      end
+    end
   end
 end

data/lib/standard_circuit/health.rb

@@ -3,10 +3,10 @@ module StandardCircuit
   # and the Config's registered circuits / prefixes and return structured
   # snapshots plus an overall health status.
   #
-  # Intended for mounting in a Rails HealthController. Prefer +health_report+
-  # over calling +health_snapshot+ and +health_overall+ separately — the
-  # combined call takes a single atomic snapshot, so the rendered status and
-  # circuits always describe the same moment:
+  # Intended for mounting in a Rails HealthController. Use +health_report+ —
+  # it takes a single atomic snapshot, so the rendered status and circuits
+  # always describe the same moment (the separate module-level
+  # +health_snapshot+ / +health_overall+ readers are deprecated):
   #
   #   report = StandardCircuit.health_report
   #   render json: report, status: (report[:status] == :critical ? 503 : 200)

data/lib/standard_circuit/health_controller.rb

@@ -1,28 +1,23 @@
+# Deprecated load path, kept so `require "standard_circuit/health_controller"`
+# at the top of a host's config/routes.rb (the pre-0.4 opt-in) keeps working.
+#
+# The controller now lives at app/controllers/standard_circuit/health_controller.rb
+# and the engine autoloads it — delete the require and keep the route.
 require "action_controller"
+require "standard_circuit"
 
-module StandardCircuit
-  # Opt-in health-check controller. Renders +StandardCircuit.health_report+ as
-  # JSON and returns 503 when the rolled-up status is +:critical+ so upstream
-  # orchestrators pull the instance out of rotation. :degraded and :ok both
-  # return 200 — the app can still serve most traffic.
-  #
-  # This controller is not auto-loaded. Consumers opt in:
-  #
-  #   # config/routes.rb
-  #   require "standard_circuit/health_controller"
-  #
-  #   Rails.application.routes.draw do
-  #     get "/health", to: "standard_circuit/health#show"
-  #   end
-  #
-  # Inherits from +ActionController::API+ to sidestep any ApplicationController
-  # filters (authentication, bootstrap redirects, etc.) — health probes must be
-  # callable anonymously from load balancers and uptime monitors.
-  class HealthController < ::ActionController::API
-    def show
-      report = StandardCircuit.health_report
-      http_status = report[:status] == :critical ? :service_unavailable : :ok
-      render json: report, status: http_status
-    end
-  end
+StandardCircuit.deprecator.warn(
+  'require "standard_circuit/health_controller" is no longer needed: the engine ' \
+  "autoloads StandardCircuit::HealthController. Remove the require and keep the " \
+  '`get "/health", to: "standard_circuit/health#show"` route.'
+)
+
+# Booted Rails app (e.g. required from config/routes.rb): the engine's
+# autoloader already has an autoload set for the constant, so there is nothing
+# to do — loading the file here would race Zeitwerk for the same path.
+# Otherwise (required from an initializer before autoloaders are set up, or
+# outside Rails entirely) load it directly; Zeitwerk later sees the constant
+# is defined and leaves it alone.
+unless StandardCircuit.autoload?(:HealthController) || StandardCircuit.const_defined?(:HealthController, false)
+  require_relative "../../app/controllers/standard_circuit/health_controller"
 end

data/lib/standard_circuit/mailer/retry.rb

@@ -0,0 +1,121 @@
+require_relative "circuit_open_error"
+
+module StandardCircuit
+  module Mailer
+    # Opt-in `retry_on CircuitOpenError` for ActionMailer's delivery job, so a
+    # `deliver_later` that runs while the mail circuit is open is retried after
+    # the breaker has had a chance to half-open, instead of failing once and
+    # losing the email. Enabled with:
+    #
+    #   StandardCircuit.configure do |c|
+    #     c.mailer_retry = true                           # 90s wait, 5 attempts, 15% jitter
+    #     c.mailer_retry = { wait: 120, attempts: 8 }     # partial overrides
+    #   end
+    #
+    # Keep `wait` longer than the mail circuit's `cool_off_time`, or each retry
+    # lands on a still-open circuit.
+    #
+    # `ActionMailer::MailDeliveryJob` inherits from `ActiveJob::Base`, not the
+    # host's ApplicationJob, which is why every app was patching it from an
+    # initializer. Installation is idempotent — `configure` runs on every
+    # `to_prepare` (so on every code reload in development), and `retry_on`
+    # appends a rescue handler each time it's called — and it also stands down
+    # when a handler for CircuitOpenError is already present, so a host that
+    # still carries its own initializer doesn't end up with two.
+    #
+    # Subclasses of MailDeliveryJob (`self.delivery_job = MyJob`) inherit the
+    # handler; a `retry_on CircuitOpenError` declared on the subclass wins.
+    #
+    # On exhaustion: one error log line, a Sentry `:error` event (when
+    # `sentry_enabled` and Sentry is initialized), and a
+    # `standard_circuit.mailer.retries_exhausted` event. PII: recipient
+    # DOMAINS only — never addresses or subjects.
+    module Retry
+      EXHAUSTED_EVENT = "standard_circuit.mailer.retries_exhausted".freeze
+      EXHAUSTED_MESSAGE = "Email delivery failed: mail circuit breaker retries exhausted".freeze
+      FINGERPRINT = "standard_circuit-mailer-retries-exhausted".freeze
+
+      class << self
+        # Defers installation until ActiveJob::Base has loaded (immediately if
+        # it already has), so enabling this from an early initializer doesn't
+        # force ActiveJob to load before its own configuration is applied. The
+        # hook reads the live config when it runs; it is registered once.
+        def install_on_load
+          return if @on_load_registered
+
+          @on_load_registered = true
+          ::ActiveSupport.on_load(:active_job) do
+            options = StandardCircuit.config.mailer_retry
+            StandardCircuit::Mailer::Retry.install(::ActionMailer::MailDeliveryJob, options) if options
+          end
+        end
+
+        # Adds the retry_on to +job_class+ unless a CircuitOpenError handler is
+        # already there. Returns true when it installed one.
+        def install(job_class, options)
+          return false if installed?(job_class)
+
+          job_class.retry_on(
+            CircuitOpenError,
+            wait: options.fetch(:wait),
+            attempts: options.fetch(:attempts),
+            jitter: options.fetch(:jitter)
+          ) do |job, error|
+            StandardCircuit::Mailer::Retry.report_exhausted(job, error)
+          end
+          true
+        end
+
+        def installed?(job_class)
+          job_class.rescue_handlers.any? { |(error_name, _handler)| error_name == CircuitOpenError.name }
+        end
+
+        def report_exhausted(job, error)
+          mailer_class, mail_action = job.arguments
+          details = {
+            mailer_class: mailer_class,
+            mail_action: mail_action,
+            recipient_domains: recipient_domains(error.recipients),
+            job_id: job.job_id,
+            executions: job.executions
+          }
+
+          logger&.error("[standard_circuit] #{EXHAUSTED_MESSAGE} #{details.to_json}")
+          capture_sentry(details)
+          EventEmitter.emit(EXHAUSTED_EVENT, details)
+          details
+        end
+
+        def recipient_domains(recipients)
+          Array(recipients)
+            .filter_map { |address| address.to_s.split("@", 2)[1]&.strip&.downcase }
+            .reject(&:empty?)
+            .uniq
+        end
+
+        # @api private — test isolation.
+        def reset_on_load_registration!
+          @on_load_registered = false
+        end
+
+        private
+
+        def logger
+          StandardCircuit.config.logger || (::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger))
+        end
+
+        def capture_sentry(details)
+          return unless StandardCircuit.config.sentry_enabled
+          return unless defined?(::Sentry) && ::Sentry.respond_to?(:initialized?) && ::Sentry.initialized?
+
+          ::Sentry.capture_message(
+            EXHAUSTED_MESSAGE,
+            level: :error,
+            fingerprint: [ FINGERPRINT, details[:mailer_class], details[:mail_action] ].map(&:to_s),
+            extra: details
+          )
+        end
+      end
+    end
+  end
+end

data/lib/standard_circuit/presets.rb

@@ -0,0 +1,90 @@
+module StandardCircuit
+  # Named circuit registrations for integrations whose settings were being
+  # copy-pasted, line for line, across host apps. Use via
+  # `Config#register_preset`:
+  #
+  #   StandardCircuit.configure do |c|
+  #     c.register_preset(:postmark)                   # named circuit :postmark
+  #     c.register_preset(:s3)                         # prefix "s3" (s3_<bucket>)
+  #     c.register_preset(:postmark, criticality: :critical) # override any option
+  #   end
+  #
+  # A preset only fills in defaults — every `register` option passed alongside
+  # it wins. Each preset also requires its SDK before computing the error
+  # lists, so the taxonomy can't silently degrade to network errors only when
+  # the SDK is declared `require: false` and hasn't been loaded yet at
+  # configure time.
+  module Presets
+    Preset = Struct.new(:scope, :sdk_require, :sdk_constant, :options, keyword_init: true)
+
+    REGISTRY = {
+      # Postmark API delivery behind the `:standard_circuit` mailer delivery
+      # method. 60s cool-off pairs with `mailer_retry`'s 90s default wait, so a
+      # retried delivery lands after the breaker has had a chance to half-open.
+      # :standard — an email outage is user-visible but non-blocking.
+      postmark: Preset.new(
+        scope: :name,
+        sdk_require: "postmark",
+        sdk_constant: "Postmark::HttpServerError",
+        options: -> {
+          {
+            threshold: 3,
+            cool_off_time: 60,
+            criticality: :standard,
+            tracked_errors: ErrorTaxonomies::Postmark.tracked,
+            skipped_errors: AdapterErrors::Postmark.caller_errors
+          }
+        }
+      ),
+      # Per-bucket S3 circuits for `service: StandardCircuitS3` in storage.yml,
+      # which keys its circuit as `s3_<bucket>` — hence a prefix registration.
+      # `skipped_errors` is left to `ErrorTaxonomies.default_skipped_for`, which
+      # skips AccessDenied / NoSuchKey.
+      s3: Preset.new(
+        scope: :prefix,
+        sdk_require: "aws-sdk-s3",
+        sdk_constant: "Aws::S3::Errors::NoSuchKey",
+        options: -> {
+          {
+            threshold: 3,
+            cool_off_time: 30,
+            criticality: :standard,
+            tracked_errors: ErrorTaxonomies::Aws.tracked
+          }
+        }
+      )
+    }.freeze
+
+    class << self
+      def names
+        REGISTRY.keys
+      end
+
+      # Returns `[scope, options]` for +preset+ with +overrides+ merged on top.
+      # Raises ArgumentError for an unknown preset or a missing SDK.
+      def resolve(preset, **overrides)
+        entry = REGISTRY.fetch(preset.to_sym) do
+          raise ArgumentError, "unknown preset #{preset.inspect}; available: #{names.inspect}"
+        end
+        load_sdk!(preset, entry)
+        [ entry.scope, entry.options.call.merge(overrides) ]
+      end
+
+      private
+
+      def load_sdk!(preset, entry)
+        return if Object.const_defined?(entry.sdk_constant)
+
+        begin
+          require entry.sdk_require
+        rescue LoadError
+          nil
+        end
+        return if Object.const_defined?(entry.sdk_constant)
+
+        raise ArgumentError,
+          "preset #{preset.inspect} needs the #{entry.sdk_require} gem (#{entry.sdk_constant} is not defined)"
+      end
+    end
+  end
+end

data/lib/standard_circuit/version.rb

@@ -1,3 +1,3 @@
 module StandardCircuit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/standard_circuit.rb

@@ -3,12 +3,15 @@ require "concurrent"
 require "sentry-ruby"
 
 require "standard_circuit/version"
+require "standard_circuit/deprecator"
 require "standard_circuit/network_errors"
 require "standard_circuit/adapter_errors/stripe"
 require "standard_circuit/adapter_errors/aws"
 require "standard_circuit/adapter_errors/faraday"
 require "standard_circuit/adapter_errors/smtp"
+require "standard_circuit/adapter_errors/postmark"
 require "standard_circuit/error_taxonomies"
+require "standard_circuit/presets"
 require "standard_circuit/event_emitter"
 require "standard_circuit/notifier_bridge"
 require "standard_circuit/notifiers/logger"
@@ -20,6 +23,7 @@ require "standard_circuit/health"
 require "standard_circuit/runner"
 require "standard_circuit/mailer/circuit_open_error"
 require "standard_circuit/mailer/delivery_method"
+require "standard_circuit/mailer/retry"
 require "standard_circuit/controller_support"
 require "standard_circuit/engine" if defined?(::Rails::Engine)
 
@@ -32,6 +36,7 @@ module StandardCircuit
       yield config
       runner.apply_config!(config)
       subscribers.setup!
+      Mailer::Retry.install_on_load if config.mailer_retry
       config
     end
 
@@ -67,11 +72,21 @@ module StandardCircuit
       runner.reset!
     end
 
+    # @deprecated Use +health_report[:circuits]+. Removed in 0.5.
     def health_snapshot
+      deprecator.warn(
+        "StandardCircuit.health_snapshot is deprecated and will be removed in 0.5; " \
+        "use StandardCircuit.health_report[:circuits] (one atomic read of status + circuits)."
+      )
       runner.health_snapshot
     end
 
+    # @deprecated Use +health_report[:status]+. Removed in 0.5.
     def health_overall(snapshot = nil)
+      deprecator.warn(
+        "StandardCircuit.health_overall is deprecated and will be removed in 0.5; " \
+        "use StandardCircuit.health_report[:status] (one atomic read of status + circuits)."
+      )
       runner.health_overall(snapshot)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_circuit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -65,6 +65,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: brakeman
   requirement: !ruby/object:Gem::Requirement
@@ -120,18 +148,20 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- app/controllers/standard_circuit/health_controller.rb
 - lib/active_storage/service/standard_circuit_s3_service.rb
 - lib/generators/standard_circuit/install/install_generator.rb
-- lib/generators/standard_circuit/install/templates/health_initializer.rb.tt
 - lib/generators/standard_circuit/install/templates/initializer.rb.tt
 - lib/standard_circuit.rb
 - lib/standard_circuit/active_storage/s3_service.rb
 - lib/standard_circuit/adapter_errors/aws.rb
 - lib/standard_circuit/adapter_errors/faraday.rb
+- lib/standard_circuit/adapter_errors/postmark.rb
 - lib/standard_circuit/adapter_errors/smtp.rb
 - lib/standard_circuit/adapter_errors/stripe.rb
 - lib/standard_circuit/config.rb
 - lib/standard_circuit/controller_support.rb
+- lib/standard_circuit/deprecator.rb
 - lib/standard_circuit/engine.rb
 - lib/standard_circuit/error_taxonomies.rb
 - lib/standard_circuit/event_emitter.rb
@@ -139,11 +169,13 @@ files:
 - lib/standard_circuit/health_controller.rb
 - lib/standard_circuit/mailer/circuit_open_error.rb
 - lib/standard_circuit/mailer/delivery_method.rb
+- lib/standard_circuit/mailer/retry.rb
 - lib/standard_circuit/network_errors.rb
 - lib/standard_circuit/notifier_bridge.rb
 - lib/standard_circuit/notifiers/logger.rb
 - lib/standard_circuit/notifiers/metrics.rb
 - lib/standard_circuit/notifiers/sentry.rb
+- lib/standard_circuit/presets.rb
 - lib/standard_circuit/rspec.rb
 - lib/standard_circuit/runner.rb
 - lib/standard_circuit/subscribers.rb

data/lib/generators/standard_circuit/install/templates/health_initializer.rb.tt

@@ -1,25 +0,0 @@
-# StandardCircuit health-check controller
-# Generated by: rails g standard_circuit:install --with-health-endpoint
-#
-# The controller is opt-in: this require pulls it onto the autoload path so
-# the route below resolves. Add the matching route to config/routes.rb:
-#
-#   get "/health", to: "standard_circuit/health#show"
-#
-# ORDERING IS LOAD-BEARING: if your app also mounts StandardHealth::Engine at
-# "/health", draw this aggregate route BEFORE the mount —
-#
-#   get "/health", to: "standard_circuit/health#show"        # aggregate — FIRST
-#   mount StandardHealth::Engine => "/health", as: :standard_health
-#
-# StandardHealth::Engine registers sub-paths only ("/alive", "/ready",
-# "/diagnostics/env") — it never serves the aggregate tier itself. So an app
-# that mounts the engine and assumes "/health" is covered has no aggregate tier
-# at all, and nothing says so: no boot error, and no failing route spec unless
-# one already exists. Draw this route explicitly, first.
-#
-# The endpoint renders StandardCircuit.health_report as JSON and returns
-# 503 when the rolled-up status is :critical (so orchestrators pull the
-# instance out of rotation) and 200 otherwise.
-
-require "standard_circuit/health_controller"