standard_circuit 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5772ca0d1cec01fde070aab6ed65f232e52b00f7b2f4fa966348f3866a49dea7
-  data.tar.gz: a8ce2582796937fe0816f454c9a2fd56e6a29d85e35850136a0b5f7a0bc7885f
+  metadata.gz: 1c26b42239426b6e97f01c017a4dead949a827d1f4d3e0cd991493c5292d127a
+  data.tar.gz: 2689f5e66f85ea012dd3d84f2a17fdf9700fa7938c862ba35a2f5d4f651f4951
 SHA512:
-  metadata.gz: 1c880e1e97c57f07a0a576a3b2e699583cf7719b1414a4dcc363f55b35109c30367954cea575b163abb8419439a1e9ed264a724110eec85264871e9894b7b930
-  data.tar.gz: 0b14981a97b3588b149b41d24c7ac7a554254a449ce40a1773f5921f9d6ca1417e7f5f21116ac239aaefba1993aade11d54a9985026d79adc88aeaaa78555580
+  metadata.gz: fa4ac99fa63f03cd2790084476189a8d0ecc6d3d993b4ceaf5c1aa7d5a06a2fe2b5dcb64f8a5165b230c7a700ae30e2a7385c68301e7e0c7937f64f5216da6a0
+  data.tar.gz: 0addb3ca191eeb7cf62fe15a297c8997b62e716ca5bf48f9eea1ffbd5493ad429edf994df0b91bf62c89a035e15062ec3b0445460a4304c7a4569a40194ea31c

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-24
+
+**Breaking.** Removes everything 0.4 deprecated. Behaviour of everything that remains is unchanged, including 0.4.2's `mailer_retry` (exhaustion reports, then re-raises so the job dead-letters).
+
+### Removed
+- `require "standard_circuit/health_controller"`. The shim file is gone, so the require now raises `LoadError`. `StandardCircuit::HealthController` is autoloaded by the engine (since 0.4); keep the `get "/health", to: "standard_circuit/health#show"` route and delete the require.
+- `StandardCircuit.health_snapshot` and `StandardCircuit.health_overall`. Use `StandardCircuit.health_report[:circuits]` / `[:status]`, which read both atomically. `StandardCircuit::Runner#health_overall`, which only backed the removed reader, is removed too; `Runner#health_snapshot` stays because `health_report` uses it.
+- `StandardCircuit::AdapterErrors::Faraday.caller_errors`. `Faraday::ClientError` is never in `ErrorTaxonomies::Faraday.tracked`, so skipping it was a no-op. `Aws`, `Stripe`, `Smtp` and `Postmark` `caller_errors` are unchanged.
+- `StandardCircuit::ActiveStorage::S3Service`, the unused alias. Use `ActiveStorage::Service::StandardCircuitS3Service`, or `service: StandardCircuitS3` in storage.yml (unchanged).
+- The boot probe's two legacy-require modes; a spec now pins the `LoadError`.
+
+### Changed
+- `StandardCircuit.deprecator`'s horizon is now `0.6`.
+
+### Upgrade notes
+- **No host code change is required in any of the five consumer apps.** Grepped `origin/main` of sidekick-web, jumpdrive-web (control-plane), fundbright-web, luminality-web and nutripod-web on 2026-09-24: none calls `health_snapshot` / `health_overall` / `Faraday.caller_errors`, references `StandardCircuit::ActiveStorage::S3Service`, or requires `standard_circuit/health_controller` (sidekick-web's `health_snapshots` is an unrelated model).
+- Regenerate Sorbet RBIs after bumping (`bin/tapioca gem standard_circuit`): jumpdrive-web's `control-plane/sorbet/rbi/gems/standard_circuit@0.4.1.rbi` still declares the removed readers. `require "standard_circuit/controller_support"` / `"standard_circuit/mailer/delivery_method"` in fundbright-web's and luminality-web's `sorbet/tapioca/require.rb` are still valid paths and can stay.
+- If anything outside these apps still has the legacy require, it now fails at boot with `LoadError` rather than warning. Delete the line.
+
+## [0.4.2] - 2026-09-24
+
+### Fixed
+- **Exhausted mail jobs now fail (dead-letter) instead of being discarded.** `mailer_retry` installs `retry_on CircuitOpenError` with a block, and ActiveJob swallows the error when that block returns normally. So on exhaustion 0.4.0 and 0.4.1 logged, sent the Sentry event, emitted `standard_circuit.mailer.retries_exhausted`, and then let the job complete. The email was silently dropped, and nothing reached Solid Queue's failed executions, where it could have been retried. The handler now reports exactly as before and then re-raises the `CircuitOpenError`, so the job fails. Earlier attempts still re-enqueue with the configured wait. If reporting itself raises, that is logged and the original error is still re-raised. No config change.
+
+### Upgrade notes
+- **Expect one more Sentry event per exhausted email** if your host captures failed jobs (sentry-rails' ActiveJob integration does). It is the re-raised `CircuitOpenError`, grouped by exception class rather than by the `standard_circuit-mailer-retries-exhausted` fingerprint. The fingerprinted event is unchanged and is still the one to alert on. To keep only the fingerprinted event, drop the job-failure event in `before_send`. The gem does not set the fingerprint on the ambient Sentry scope, because outside a job's own scope (inline `perform_now`) it would leak onto unrelated events.
+- Failed mail jobs now accumulate in your queue backend's failed jobs (Solid Queue: `solid_queue_failed_executions`). Retry them once the provider is healthy, or discard them deliberately.
+
 ## [0.4.1] - 2026-09-24
 
 ### Fixed

data/README.md

@@ -219,7 +219,7 @@ end
 - **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.
+- **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. It then **re-raises** the `CircuitOpenError`, so the job fails and lands in your queue backend's failed jobs (Solid Queue's failed executions) where it can be inspected and retried, instead of completing with the email dropped (since 0.4.2). If your Sentry setup also captures job failures (sentry-rails' ActiveJob integration does), that failure arrives as a second event, grouped by the exception rather than by the fingerprint above.
 - 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:
@@ -323,7 +323,7 @@ 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 old `require` was deprecated in 0.4 and **removed in 0.5**: it now raises `LoadError`, so delete it.
 
 The controller inherits from `ActionController::API` to sidestep app-level filters (authentication, bootstrap redirects, etc.) so probes can call it anonymously.
 
@@ -350,18 +350,20 @@ These are supported public API for host test suites, not internals:
 
 All of these are **process-local**. They are test and console tools, not an operational kill switch (see `data_store` above).
 
-## Deprecations
+## Removed in 0.5
 
-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.
+0.4 deprecated these and 0.5 removes them. None of the five consumer apps used any of them at removal time.
 
-| Deprecated | Use instead |
-|------------|-------------|
-| `require "standard_circuit/health_controller"` | nothing — the controller is autoloaded |
+| Removed | Use instead |
+|---------|-------------|
+| `require "standard_circuit/health_controller"` (now `LoadError`) | nothing — the controller is autoloaded; keep the route |
 | `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.health_overall` (and `StandardCircuit.runner.health_overall`) | `StandardCircuit.health_report[:status]` |
+| `StandardCircuit::AdapterErrors::Faraday.caller_errors` | drop it — `Faraday::ClientError` is never tracked, so skipping it was a no-op |
 | `StandardCircuit::ActiveStorage::S3Service` | `ActiveStorage::Service::StandardCircuitS3Service` / `service: StandardCircuitS3` |
 
+Future deprecations warn through `Rails.application.deprecators[:standard_circuit]`, so your app's `config.active_support.deprecation` setting applies.
+
 ## License
 
 MIT

data/app/controllers/standard_circuit/health_controller.rb

@@ -12,8 +12,8 @@ module StandardCircuit
   #     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).
+  # The pre-0.4 `require "standard_circuit/health_controller"` was removed in
+  # 0.5 (it raises LoadError); delete it and keep the route.
   #
   # Inherits from +ActionController::API+ to sidestep any ApplicationController
   # filters (authentication, bootstrap redirects, etc.) — health probes must be

data/lib/standard_circuit/active_storage/s3_service.rb

@@ -33,17 +33,3 @@ module ActiveStorage
     end
   end
 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
-    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

@@ -9,20 +9,6 @@ module StandardCircuit
           errors << ::Faraday::ServerError if defined?(::Faraday::ServerError)
           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 ]
-        end
       end
     end
   end

data/lib/standard_circuit/deprecator.rb

@@ -7,6 +7,6 @@ module StandardCircuit
   # 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")
+    @deprecator ||= ActiveSupport::Deprecation.new("0.6", "StandardCircuit")
   end
 end

data/lib/standard_circuit/health.rb

@@ -5,8 +5,7 @@ module StandardCircuit
   #
   # 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):
+  # always describe the same moment:
   #
   #   report = StandardCircuit.health_report
   #   render json: report, status: (report[:status] == :critical ? 503 : 200)

data/lib/standard_circuit/mailer/retry.rb

@@ -29,7 +29,9 @@ module StandardCircuit
     # 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.
+    # DOMAINS only — never addresses or subjects. Then the CircuitOpenError is
+    # re-raised, so the job FAILS (dead letter) rather than completing with
+    # the email dropped (0.4.2; 0.4.0/0.4.1 swallowed it).
     module Retry
       EXHAUSTED_EVENT = "standard_circuit.mailer.retries_exhausted".freeze
       EXHAUSTED_MESSAGE = "Email delivery failed: mail circuit breaker retries exhausted".freeze
@@ -115,11 +117,32 @@ module StandardCircuit
             attempts: options.fetch(:attempts),
             jitter: options.fetch(:jitter)
           ) do |job, error|
-            StandardCircuit::Mailer::Retry.report_exhausted(job, error)
+            StandardCircuit::Mailer::Retry.exhausted!(job, error)
           end
           true
         end
 
+        # Runs when the last attempt still hits an open circuit. Reports first
+        # (log, fingerprinted Sentry event, retries_exhausted event), then
+        # RE-RAISES so the job fails. ActiveJob's retry_on swallows the error
+        # when given a block unless the block raises, and a swallowed error
+        # means the job "succeeds" and the email is silently dropped. Raising
+        # lands it in the queue backend's failed executions (Solid Queue's
+        # dead letter), where it can be inspected and retried.
+        #
+        # A report that raises must not turn into a dropped email, so it is
+        # rescued and logged; the original error is raised regardless.
+        #
+        # @api private
+        def exhausted!(job, error)
+          begin
+            report_exhausted(job, error)
+          rescue StandardError => report_error
+            logger&.error("[standard_circuit] failed to report mail retry exhaustion: #{report_error.class}: #{report_error.message}")
+          end
+          raise error
+        end
+
         def installed?(job_class)
           job_class.rescue_handlers.any? { |(error_name, _handler)| error_name == CircuitOpenError.name }
         end

data/lib/standard_circuit/runner.rb

@@ -63,14 +63,6 @@ module StandardCircuit
       Health.snapshot(self, @config)
     end
 
-    # Accepts an optional pre-computed snapshot so callers that also need the
-    # raw circuits list don't read the data store twice (which could yield
-    # an inconsistent status/circuits pair). Prefer +health_report+ when you
-    # need both.
-    def health_overall(snapshot = nil)
-      Health.overall(snapshot || health_snapshot)
-    end
-
     # Atomic health report — takes a single snapshot and returns both the
     # rolled-up status and the per-circuit list. Preferred for rendering a
     # health-check endpoint so status and circuits describe the same moment.

data/lib/standard_circuit/version.rb

@@ -1,3 +1,3 @@
 module StandardCircuit
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/standard_circuit.rb

@@ -72,24 +72,6 @@ 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
-
     def health_report
       runner.health_report
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_circuit
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -166,7 +166,6 @@ files:
 - lib/standard_circuit/error_taxonomies.rb
 - lib/standard_circuit/event_emitter.rb
 - lib/standard_circuit/health.rb
-- 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

data/lib/standard_circuit/health_controller.rb

@@ -1,23 +0,0 @@
-# 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"
-
-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