standard_circuit 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27549729eb52395cef12a0e01e39d48f7218b2cd564f823f2d12d515ffe2fb82
-  data.tar.gz: 6ed8b33e22ccd8e655bb75dcb815098bb4a9dd16ed1daef7bd7c9c586eb1a18d
+  metadata.gz: 195e01d912e93d7bf158cafd091aab7ab27571994e9d4c2953d0a39b76c92d71
+  data.tar.gz: 880f2b881ada6a92660c8c26c1c2b49abf2ea283411606a7131c9cf1af8bd75f
 SHA512:
-  metadata.gz: e8ebb089c834961f250167f316c9e0648fa51f3600a6a1d6774731acdad3842be7c7fde2afb24806fb4be6af4fb341f0a412090a4100151226c9b3dca58aab46
-  data.tar.gz: 3a5f2af8401788aba1f13321a16dd23d7a94f9becf14834e6bc95672a4d21beeaa0e2b87e6cf440ad3417d90ded2c47b30067d4d3cb72634a63b1aca474a0348
+  metadata.gz: 4706259801d563a2b60183691ad7c4ae935face858318e358d4e3bd5459c4b2eee097da52c8cb4748c7726883455f96a1416a23cde8b0123d172207d2f64b373
+  data.tar.gz: 05f1578d83f4bdbc34d310350570322bf4cd357d24d50e07874bed2e34019d33bb3cf0f396e49cf9a598797700aef34d3182b98c730d4a25e737f3f083ad6e80

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-22
+
+### Fixed
+
+- **Zero-argument fallback lambdas no longer crash when the circuit opens.**
+  A fallback is called with the error (or `nil` when forced open), so a
+  `fallback: -> { ... }` raised `ArgumentError` at exactly the moment the
+  circuit opened, the case the fallback exists for. Such lambdas are now called
+  without the argument. Fallbacks that take the error, and procs, are
+  unchanged. Zero-arity `Method` fallbacks are accepted the same way.
+
+### Changed
+
+- **Requires Rails 8.1** (`railties`, `actionmailer`, `actionpack` `>= 8.1`,
+  was `>= 8.0`). Every consumer app runs 8.1; 8.0 was never exercised in CI.
+
+## [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

data/README.md

@@ -54,8 +54,17 @@ end
 StandardCircuit.run(:stripe) do
   Stripe::PaymentIntent.create(amount:, currency:)
 end
+
+# with a fallback, returned instead of raising while the circuit is open
+StandardCircuit.run(:analytics, fallback: -> { nil }) do
+  Analytics.track(event)
+end
 ```
 
+A fallback may take the error (`->(error) { ... }`: the error the block raised,
+or `nil` once the circuit is open, since the block then never runs) or take
+nothing (`-> { ... }`, or a zero-arity `method(...)`); all are called correctly.
+
 ## 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.
@@ -323,7 +332,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 +359,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/runner.rb

@@ -12,6 +12,7 @@ module StandardCircuit
     end
 
     def run(name, fallback: nil, &block)
+      fallback = accept_error_argument(fallback)
       forced = @forced_states[name.to_sym]
       return run_forced_open(name, fallback) if forced == :open
       return yield if forced == :closed
@@ -63,14 +64,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.
@@ -81,6 +74,20 @@ module StandardCircuit
 
     private
 
+    # A fallback is called with one argument: the error, or nil when the
+    # circuit is forced open. A zero-argument lambda (`-> { ... }`, the
+    # natural way to write "return this instead") raises ArgumentError on that
+    # call, so the fallback would crash at exactly the moment the circuit
+    # opens. Accept it, and a zero-arity Method (`fallback: method(:degraded)`),
+    # by calling it without the argument. Procs, and callables that take the
+    # error, are passed through unchanged.
+    def accept_error_argument(fallback)
+      strict = fallback.is_a?(Method) || (fallback.is_a?(Proc) && fallback.lambda?)
+      return fallback unless strict && fallback.arity.zero?
+
+      ->(_error) { fallback.call }
+    end
+
     def execute(name, fallback, &block)
       started_at = monotonic_now
       light = light_for(name)

data/lib/standard_circuit/version.rb

@@ -1,3 +1,3 @@
 module StandardCircuit
-  VERSION = "0.4.2"
+  VERSION = "0.6.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.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -57,42 +57,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: actionmailer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: brakeman
   requirement: !ruby/object:Gem::Requirement
@@ -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
@@ -202,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Circuit breaker primitives for Rails apps, built on stoplight.
 test_files: []

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