standard_circuit 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60bd3d9dbd17cad5bdf8062be096c8f7b1d8baa00f167e25f1ea96581a078cca
-  data.tar.gz: 5abdcf7eb5bf00b65bc0b724d3ced093f71f6ee1cb59a8d594c6a8d3944998e1
+  metadata.gz: 5772ca0d1cec01fde070aab6ed65f232e52b00f7b2f4fa966348f3866a49dea7
+  data.tar.gz: a8ce2582796937fe0816f454c9a2fd56e6a29d85e35850136a0b5f7a0bc7885f
 SHA512:
-  metadata.gz: f88dc067ff12e4651a0f6f5317d55f22f5a9b78507d0bc31bf7fc737fa2dc3a7efa09853b64bb89f3fb608660eb4da79b126921d90a87e7ad9396bcb81cb317b
-  data.tar.gz: 1ed24fba0bdd0e373dfbe4cc4a18cc9e22675db527c109b151395ba2681d403ea64dbf0a12672b53250edfd8886aa66be1cedd42a36099833c23562a828b89c0
+  metadata.gz: 1c880e1e97c57f07a0a576a3b2e699583cf7719b1414a4dcc363f55b35109c30367954cea575b163abb8419439a1e9ed264a724110eec85264871e9894b7b930
+  data.tar.gz: 0b14981a97b3588b149b41d24c7ac7a554254a449ce40a1773f5921f9d6ca1417e7f5f21116ac239aaefba1993aade11d54a9985026d79adc88aeaaa78555580

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/lib/standard_circuit/mailer/retry.rb

@@ -35,19 +35,73 @@ module StandardCircuit
       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

data/lib/standard_circuit/version.rb

@@ -1,3 +1,3 @@
 module StandardCircuit
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 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.1
 platform: ruby
 authors:
 - Jaryl Sim