standard_circuit 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60bd3d9dbd17cad5bdf8062be096c8f7b1d8baa00f167e25f1ea96581a078cca
-  data.tar.gz: 5abdcf7eb5bf00b65bc0b724d3ced093f71f6ee1cb59a8d594c6a8d3944998e1
+  metadata.gz: 27549729eb52395cef12a0e01e39d48f7218b2cd564f823f2d12d515ffe2fb82
+  data.tar.gz: 6ed8b33e22ccd8e655bb75dcb815098bb4a9dd16ed1daef7bd7c9c586eb1a18d
 SHA512:
-  metadata.gz: f88dc067ff12e4651a0f6f5317d55f22f5a9b78507d0bc31bf7fc737fa2dc3a7efa09853b64bb89f3fb608660eb4da79b126921d90a87e7ad9396bcb81cb317b
-  data.tar.gz: 1ed24fba0bdd0e373dfbe4cc4a18cc9e22675db527c109b151395ba2681d403ea64dbf0a12672b53250edfd8886aa66be1cedd42a36099833c23562a828b89c0
+  metadata.gz: e8ebb089c834961f250167f316c9e0648fa51f3600a6a1d6774731acdad3842be7c7fde2afb24806fb4be6af4fb341f0a412090a4100151226c9b3dca58aab46
+  data.tar.gz: 3a5f2af8401788aba1f13321a16dd23d7a94f9becf14834e6bc95672a4d21beeaa0e2b87e6cf440ad3417d90ded2c47b30067d4d3cb72634a63b1aca474a0348

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **`mailer_retry` no longer crashes a lazily-loaded process with `NameError: uninitialized constant ActionMailer::MailDeliveryJob`.** 0.4.0 installed the retry from `ActiveSupport.on_load(:active_job)` and referenced `ActionMailer::MailDeliveryJob` inside the hook. When `class MailDeliveryJob < ActiveJob::Base` was itself what loaded `ActiveJob::Base`, the hook ran while that class was still being autoloaded. In development this broke the first `deliver_later` of a fresh process, and `bin/tapioca dsl` hit it too. Eager-loaded production processes and RSpec runs were not affected. The retry is now installed at whichever of these happens first, and never while `MailDeliveryJob` is still mid-autoload:
+  - `ActiveJob::Base` loads when `MailDeliveryJob` can already be referenced safely.
+  - `ActionMailer::Base` loads. It references `MailDeliveryJob`, so the class is complete by then. Every delivery goes through a mailer, so this also covers a worker that deserializes the job before any mailer loads.
+  - Something subclasses `MailDeliveryJob`. This covers a custom `delivery_job` with its own `rescue_from` that loads before any mailer. The subclass's own handlers keep precedence.
+
+  A new integration spec boots a Rails app in a subprocess for each load order (mailer first, job first, subclass first, `ActiveJob::Base` first, eager load).
+
+  **Hosts can delete their workaround.** Any initializer that preloads `ActiveJob::Base` to dodge this bug, such as jumpdrive-web's `config.after_initialize { ActiveJob::Base }`, can be removed.
+
 ## [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.

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:

data/lib/standard_circuit/mailer/retry.rb

@@ -29,25 +29,81 @@ 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
       FINGERPRINT = "standard_circuit-mailer-retries-exhausted".freeze
 
+      # Prepended onto ActiveJob::Base's singleton class only when the
+      # :active_job hook fired mid-way through MailDeliveryJob's own
+      # definition. MailDeliveryJob is complete by the time anything
+      # subclasses it, and installing on it before the subclass body runs keeps
+      # the handler's precedence the same as for any other load order.
+      module InstallBeforeSubclassing
+        def inherited(subclass)
+          StandardCircuit::Mailer::Retry.install_configured if name == "ActionMailer::MailDeliveryJob"
+          super
+        end
+      end
+
       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.
+        # Defers installation until MailDeliveryJob can be referenced safely,
+        # so enabling this from an early initializer doesn't force ActiveJob
+        # or ActionMailer to load before their own configuration is applied.
+        # The hooks read the live config when they run; they are registered
+        # once.
+        #
+        # `ActionMailer::MailDeliveryJob` can't simply be referenced from an
+        # `on_load(:active_job)` hook: when `class MailDeliveryJob <
+        # ActiveJob::Base` is itself what loads ActiveJob::Base (a mailer or
+        # `deliver_later` touched first in a lazily-loaded process), the hook
+        # fires while that class is still being autoloaded and the reference
+        # raises NameError. So each trigger checks first, and together they
+        # cover every load order:
+        #
+        # * :active_job — installs straight away when ActiveJob::Base loads
+        #   ahead of MailDeliveryJob (eager load, or any ApplicationJob first).
+        # * :action_mailer — ActionMailer::Base references MailDeliveryJob, so
+        #   by the time this runs the class is complete. Every delivery goes
+        #   through a mailer class, so this runs before the first delivery can
+        #   raise, including in a worker that deserialized the job first
+        #   (rescue handlers are read when an error is rescued, not at enqueue).
+        # * the first subclass of MailDeliveryJob — covers a custom
+        #   `delivery_job` loaded ahead of any mailer, which would otherwise
+        #   take a copy of the parent's rescue handlers without this one.
         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
+            if StandardCircuit::Mailer::Retry.mail_delivery_job_referenceable?
+              StandardCircuit::Mailer::Retry.install_configured
+            else
+              singleton_class.prepend(StandardCircuit::Mailer::Retry::InstallBeforeSubclassing)
+            end
           end
+          ::ActiveSupport.on_load(:action_mailer) { StandardCircuit::Mailer::Retry.install_configured }
+        end
+
+        # Installs on ActionMailer::MailDeliveryJob with the configured options
+        # when mailer_retry is on and the class is safe to reference. Returns
+        # true when the handler is in place afterwards.
+        def install_configured
+          options = StandardCircuit.config.mailer_retry
+          return false unless options && mail_delivery_job_referenceable?
+
+          install(::ActionMailer::MailDeliveryJob, options)
+          true
+        end
+
+        # False only while MailDeliveryJob is mid-autoload on this thread (see
+        # install_on_load): Ruby reports an in-progress autoload as undefined.
+        # When the autoload is merely pending, referencing it loads it normally.
+        def mail_delivery_job_referenceable?
+          defined?(::ActionMailer) && ::ActionMailer.const_defined?(:MailDeliveryJob, false)
         end
 
         # Adds the retry_on to +job_class+ unless a CircuitOpenError handler is
@@ -61,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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_circuit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Jaryl Sim