standard_circuit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2faee952d1a2a7a131f721af4ac58ce46cbbe94dadc50cd50d4e6ac24af08600
+  data.tar.gz: e20f8adb374398ad0fab643b6333e329b6c7f5e187fc927092b1d167b4e290f8
+SHA512:
+  metadata.gz: '09dd4b8be7afd25bb06044c3b80d41fa39c302ccbb9357cd770127050af30d517cef73d8f6ad03a6112f837ae5d6a278068bc7edc147824403081afe63670f13'
+  data.tar.gz: ef93377225b985b979ee54f35d86f9e52354030d0c5cad2131653828ee3a767239206268eb0b18b776b3ec3fa3cfc69fc9d9ed8118a9cd53ca0e9eb74cc6c834

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-27
+
+### Fixed
+- `Mailer::Railtie` is now idempotent: skips `add_delivery_method` when `:standard_circuit` is already in `delivery_methods`. Previously, a host app that pre-registered the delivery method from an env-file `on_load(:action_mailer)` block (a common workaround for the `NoMethodError` that `config.action_mailer.standard_circuit_settings=` triggers during eager_load) would have its settings hash wiped when the gem Railtie's `on_load` fired afterwards, causing `KeyError: key not found: :circuit` at delivery time. Reproduced in production at nutripod-web (Sentry NUTRIPOD-WEB-EE / Linear LMT-454).
+
+### Added
+- `StandardCircuit::Mailer::CircuitOpenError` — now the default `retry_error_class` for the mailer delivery method; consumers no longer need to define their own.
+- Opt-in `StandardCircuit::HealthController` — `require "standard_circuit/health_controller"` then route `get "/health", to: "standard_circuit/health#show"`. Renders `StandardCircuit.health_report` as JSON and returns 503 on `:critical`.
+- Initial extraction from `sidekick-web/app/services/circuit_breaker.rb` (see design doc §4 for the five flaws addressed).
+- `StandardCircuit.run(:name, fallback:, &block)` module-method API.
+- `StandardCircuit::Config` with `register`, `register_prefix`.
+- `StandardCircuit::NetworkErrors` narrow default tracked-errors list.
+- `StandardCircuit::AdapterErrors::{Stripe,Aws,Faraday,Smtp}` modules exposing `server_errors` and `caller_errors`.
+- `StandardCircuit::Notifiers::{Logger,Sentry,Metrics}`.
+- `StandardCircuit::ActiveStorage::S3Service` — per-bucket circuit keying (`:s3_<bucket>`), wraps `upload`/`download`/`download_chunk`/`delete`/`delete_prefixed`/`exist?`/`compose`/`update_metadata`.
+- `StandardCircuit::Mailer::DeliveryMethod` — accepts `underlying:` as instance or symbol.
+- `StandardCircuit::ControllerSupport` — `circuit_open_fallback` DSL for production 503 handling.
+- `StandardCircuit.force_open`, `force_closed`, `reset_force!` + `require "standard_circuit/rspec"` for auto-cleanup.
+
+### Changed
+- Removed redundant `defined?(::Sentry::Metrics)` guards in `Runner`, `ControllerSupport`, and `Notifiers::Metrics`. `sentry-ruby` is a hard runtime dependency; the guards were dead code.
+- Tightened `sentry-ruby` lower bound from `>= 5.0` to `>= 5.17`. `Sentry::Metrics` was introduced in 5.17; the previous floor let Bundler resolve a version where the metrics API does not exist.
+

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaryl Sim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# StandardCircuit
+
+Circuit breaker primitives for Rails apps, built on [stoplight](https://github.com/bolshakov/stoplight).
+
+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)
+- Sentry notifier (warning on GREEN→RED) and metrics notifier (`external.circuit_breaker`, `external.request`)
+- ActiveStorage S3 adapter with per-bucket circuit keying
+- Generic ActionMailer delivery-method wrapper (supports both instance and symbol `underlying:` forms)
+- Controller concern for standardized 503 responses on `Stoplight::Error::RedLight`
+- Test helpers (`force_open`, `force_closed`, `reset_force!`) with RSpec auto-cleanup
+
+## Installation
+
+```ruby
+# Gemfile
+gem "standard_circuit", git: "https://github.com/rarebit-one/standard_circuit", ref: "<sha>"
+```
+
+## Quick start
+
+```ruby
+# config/initializers/standard_circuit.rb
+StandardCircuit.configure do |c|
+  c.sentry_enabled = true
+  c.metric_prefix = "external"
+
+  c.register(:stripe,
+    threshold: 5,
+    cool_off_time: 30,
+    tracked_errors: StandardCircuit::NetworkErrors.defaults + StandardCircuit::AdapterErrors::Stripe.server_errors,
+    skipped_errors: StandardCircuit::AdapterErrors::Stripe.caller_errors)
+end
+```
+
+```ruby
+# anywhere in app code
+StandardCircuit.run(:stripe) do
+  Stripe::PaymentIntent.create(amount:, currency:)
+end
+```
+
+## 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.
+
+It's opt-in — not auto-required — so apps that don't want a health route don't pay for it.
+
+```ruby
+# config/routes.rb
+require "standard_circuit/health_controller"
+
+Rails.application.routes.draw do
+  get "/health", to: "standard_circuit/health#show"
+end
+```
+
+The controller inherits from `ActionController::API` to sidestep app-level filters (authentication, bootstrap redirects, etc.) so probes can call it anonymously.
+
+See [`standard_circuit-design.md`](../standard_circuit-design.md) for the full design.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/active_storage/service/standard_circuit_s3_service.rb

@@ -0,0 +1,13 @@
+# Shim for ActiveStorage::Service::Configurator
+#
+# When storage.yml says `service: StandardCircuitS3`, ActiveStorage's
+# Configurator calls:
+#   require "active_storage/service/standard_circuit_s3_service"
+#   const_get("StandardCircuitS3Service")
+#
+# This file's only purpose is to exist at that load path so the require
+# succeeds. The actual implementation lives at
+# lib/standard_circuit/active_storage/s3_service.rb so the gem's layout
+# follows the StandardCircuit:: namespace convention.
+
+require "standard_circuit/active_storage/s3_service"

data/lib/standard_circuit/active_storage/s3_service.rb

@@ -0,0 +1,41 @@
+require "active_storage"
+require "active_storage/service"
+require "active_storage/service/s3_service"
+
+# NOTE: ActiveStorage's Configurator does
+#   require "active_storage/service/standard_circuit_s3_service"
+# when storage.yml has `service: StandardCircuitS3`. We ship a shim at
+# lib/active_storage/service/standard_circuit_s3_service.rb that requires this
+# file, so the conventional require path works.
+module ActiveStorage
+  class Service::StandardCircuitS3Service < Service::S3Service
+    WRAPPED_METHODS = %i[
+      upload
+      download
+      download_chunk
+      delete
+      delete_prefixed
+      exist?
+      compose
+      update_metadata
+    ].freeze
+
+    WRAPPED_METHODS.each do |method_name|
+      define_method(method_name) do |*args, **kwargs, &block|
+        StandardCircuit.run(circuit_name) { super(*args, **kwargs, &block) }
+      end
+    end
+
+    private
+
+    def circuit_name
+      :"s3_#{bucket.name}"
+    end
+  end
+end
+
+module StandardCircuit
+  module ActiveStorage
+    S3Service = ::ActiveStorage::Service::StandardCircuitS3Service
+  end
+end

data/lib/standard_circuit/adapter_errors/aws.rb

@@ -0,0 +1,23 @@
+module StandardCircuit
+  module AdapterErrors
+    module Aws
+      class << self
+        def server_errors
+          errors = []
+          errors << ::Seahorse::Client::NetworkingError if defined?(::Seahorse::Client::NetworkingError)
+          errors << ::Aws::Errors::ServiceError if defined?(::Aws::Errors::ServiceError)
+          errors
+        end
+
+        def caller_errors
+          return [] unless defined?(::Aws::S3::Errors::NoSuchKey)
+
+          [
+            ::Aws::S3::Errors::NoSuchKey,
+            ::Aws::S3::Errors::AccessDenied
+          ].select { |klass| klass.is_a?(Class) }
+        end
+      end
+    end
+  end
+end

data/lib/standard_circuit/adapter_errors/faraday.rb

@@ -0,0 +1,21 @@
+module StandardCircuit
+  module AdapterErrors
+    module Faraday
+      class << self
+        def server_errors
+          return [] unless defined?(::Faraday::Error)
+
+          errors = [ ::Faraday::TimeoutError, ::Faraday::ConnectionFailed ]
+          errors << ::Faraday::ServerError if defined?(::Faraday::ServerError)
+          errors.select { |klass| klass.is_a?(Class) }
+        end
+
+        def caller_errors
+          return [] unless defined?(::Faraday::ClientError)
+
+          [ ::Faraday::ClientError ]
+        end
+      end
+    end
+  end
+end

data/lib/standard_circuit/adapter_errors/smtp.rb

@@ -0,0 +1,27 @@
+require "net/smtp"
+
+module StandardCircuit
+  module AdapterErrors
+    module Smtp
+      SERVER_ERRORS = [
+        Net::SMTPServerBusy,
+        Net::SMTPFatalError,
+        Net::SMTPUnknownError,
+        EOFError
+      ].freeze
+
+      CALLER_ERRORS = [
+        Net::SMTPSyntaxError,
+        Net::SMTPAuthenticationError
+      ].freeze
+
+      def self.server_errors
+        SERVER_ERRORS.dup
+      end
+
+      def self.caller_errors
+        CALLER_ERRORS.dup
+      end
+    end
+  end
+end

data/lib/standard_circuit/adapter_errors/stripe.rb

@@ -0,0 +1,27 @@
+module StandardCircuit
+  module AdapterErrors
+    module Stripe
+      class << self
+        def server_errors
+          return [] unless defined?(::Stripe::StripeError)
+
+          [
+            ::Stripe::APIConnectionError,
+            ::Stripe::RateLimitError,
+            ::Stripe::APIError
+          ]
+        end
+
+        def caller_errors
+          return [] unless defined?(::Stripe::StripeError)
+
+          [
+            ::Stripe::InvalidRequestError,
+            ::Stripe::CardError,
+            ::Stripe::AuthenticationError
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/standard_circuit/config.rb

@@ -0,0 +1,86 @@
+module StandardCircuit
+  class Config
+    DEFAULT_THRESHOLD = 3
+    DEFAULT_COOL_OFF = 30
+    DEFAULT_WINDOW = 60
+    DEFAULT_CRITICALITY = :standard
+    CRITICALITIES = [ :critical, :standard, :optional ].freeze
+
+    CircuitSpec = Struct.new(
+      :threshold,
+      :cool_off_time,
+      :window_size,
+      :tracked_errors,
+      :skipped_errors,
+      :criticality,
+      keyword_init: true
+    ) do
+      def self.build(**opts)
+        criticality = opts.fetch(:criticality, DEFAULT_CRITICALITY)
+        unless CRITICALITIES.include?(criticality)
+          raise ArgumentError,
+            "invalid criticality #{criticality.inspect}; must be one of #{CRITICALITIES.inspect}"
+        end
+
+        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, []),
+          criticality: criticality
+        )
+      end
+    end
+
+    attr_accessor :sentry_enabled, :metric_prefix, :data_store, :logger
+    attr_reader :circuits, :prefixes, :extra_notifiers
+
+    def initialize
+      @sentry_enabled = true
+      @metric_prefix = "external"
+      @data_store = Stoplight::DataStore::Memory.new
+      @logger = nil
+      @circuits = {}
+      @prefixes = {}
+      @extra_notifiers = []
+    end
+
+    def notifiers
+      built = [ Notifiers::Logger.new(@logger) ]
+      built << Notifiers::Sentry.new if @sentry_enabled
+      built << Notifiers::Metrics.new(metric_prefix: @metric_prefix)
+      built + @extra_notifiers
+    end
+
+    def reset_registry!
+      @circuits.clear
+      @prefixes.clear
+      @extra_notifiers.clear
+    end
+
+    def register(name, **opts)
+      @circuits[name.to_sym] = CircuitSpec.build(**opts)
+    end
+
+    def register_prefix(prefix, **opts)
+      @prefixes[prefix.to_s] = CircuitSpec.build(**opts)
+    end
+
+    def add_notifier(notifier)
+      @extra_notifiers << notifier
+    end
+
+    def spec_for(name)
+      @circuits[name.to_sym] || spec_for_prefix(name)
+    end
+
+    private
+
+    def spec_for_prefix(name)
+      key = name.to_s
+      _matched_prefix, spec = @prefixes.find { |prefix, _| key.start_with?("#{prefix}_") }
+      spec
+    end
+  end
+end

data/lib/standard_circuit/controller_support.rb

@@ -0,0 +1,53 @@
+require "active_support/concern"
+require "action_controller"
+
+module StandardCircuit
+  module ControllerSupport
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from Stoplight::Error::RedLight do |error|
+        handle_circuit_open(error)
+      end
+
+      class_attribute :_circuit_open_fallback, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      def circuit_open_fallback(status: :service_unavailable, html: nil, json: nil, stream: nil)
+        self._circuit_open_fallback = {
+          status: status,
+          html: html,
+          json: json,
+          stream: stream
+        }
+      end
+    end
+
+    private
+
+    def handle_circuit_open(error)
+      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]
+      return instance_exec(&fallback[:html]) if fallback[:html]
+
+      head(fallback[:status] || :service_unavailable)
+    end
+
+    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/health.rb

@@ -0,0 +1,102 @@
+module StandardCircuit
+  # Health-reporting helpers that inspect the Runner's Stoplight Light cache
+  # 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:
+  #
+  #   report = StandardCircuit.health_report
+  #   render json: report, status: (report[:status] == :critical ? 503 : 200)
+  #
+  module Health
+    module_function
+
+    # Build a snapshot of every relevant circuit.
+    #
+    # Includes: every named circuit registered via +Config#register+ (lights
+    # are eagerly built if not yet cached so the snapshot reflects real state
+    # instead of "never exercised"); plus every circuit already present in the
+    # runner's light cache that was matched via a prefix registration.
+    #
+    # Prefix-registered circuits that have never been exercised are not
+    # enumerable and are therefore omitted.
+    def snapshot(runner, config)
+      entries = named_entries(runner, config) + prefix_entries(runner, config)
+      # Dedupe by name — a named circuit might also match a prefix; the named
+      # registration wins and we keep its entry.
+      entries.uniq { |entry| entry[:name] }
+    end
+
+    # Roll the snapshot up to :ok | :degraded | :critical.
+    #
+    # - any :critical circuit RED    -> :critical
+    # - any :critical circuit YELLOW -> :degraded
+    # - any :standard circuit RED    -> :degraded
+    # - otherwise                    -> :ok
+    #
+    # :optional circuits never elevate the overall state.
+    def overall(snapshot)
+      return :critical if snapshot.any? { |e| e[:criticality] == :critical && e[:color] == "red" }
+
+      degraded = snapshot.any? do |e|
+        (e[:criticality] == :critical && e[:color] == "yellow") ||
+          (e[:criticality] == :standard && e[:color] == "red")
+      end
+
+      degraded ? :degraded : :ok
+    end
+
+    # --- internals -------------------------------------------------------
+
+    def named_entries(runner, config)
+      config.circuits.map do |name, spec|
+        build_entry(runner.light_for(name), spec, config)
+      end
+    end
+    private_class_method :named_entries
+
+    def prefix_entries(runner, config)
+      runner.cached_lights.filter_map do |name, light|
+        next if config.circuits.key?(name.to_sym)
+
+        spec = config.spec_for(name)
+        next unless spec # defensive: light exists but no matching registration
+
+        build_entry(light, spec, config)
+      end
+    end
+    private_class_method :prefix_entries
+
+    def build_entry(light, spec, config)
+      {
+        name: light.name.to_sym,
+        color: light.color,
+        locked: locked?(light, config),
+        criticality: spec.criticality
+      }
+    end
+    private_class_method :build_entry
+
+    def locked?(light, config)
+      state = safe_state(light, config)
+      state == Stoplight::State::LOCKED_RED || state == Stoplight::State::LOCKED_GREEN
+    end
+    private_class_method :locked?
+
+    # Reading +light.state+ can raise when the data store is unreachable
+    # (e.g. Redis connection dropped). Swallow the failure so the health
+    # endpoint still returns the rest of the snapshot, but log via the
+    # passed-in config's logger so operators see the underlying fault and
+    # tests that inject a throwaway Config don't leak to the global logger.
+    def safe_state(light, config)
+      light.state
+    rescue StandardError => e
+      config.logger&.warn("StandardCircuit::Health.safe_state failed for #{light.name}: #{e.class}: #{e.message}")
+      nil
+    end
+    private_class_method :safe_state
+  end
+end

data/lib/standard_circuit/health_controller.rb

@@ -0,0 +1,28 @@
+require "action_controller"
+
+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
+end

data/lib/standard_circuit/mailer/circuit_open_error.rb

@@ -0,0 +1,23 @@
+module StandardCircuit
+  module Mailer
+    # Default error class raised by +StandardCircuit::Mailer::DeliveryMethod+
+    # when the wrapped mailer circuit is open. Mailer jobs can rescue/retry on
+    # this class to defer delivery until the upstream recovers.
+    #
+    # Constructor contract (matches DeliveryMethod#deliver!):
+    #   new(recipients:, subject:)
+    #
+    # Consumers that want their own error class can still pass
+    # +retry_error_class:+ to the delivery method settings; this class is the
+    # default when none is provided.
+    class CircuitOpenError < StandardError
+      attr_reader :recipients, :subject
+
+      def initialize(recipients:, subject:)
+        @recipients = recipients
+        @subject = subject
+        super("Circuit breaker is open: to=#{recipients.inspect} subject=#{subject.inspect}")
+      end
+    end
+  end
+end

data/lib/standard_circuit/mailer/delivery_method.rb

@@ -0,0 +1,77 @@
+require "action_mailer"
+require_relative "circuit_open_error"
+
+module StandardCircuit
+  module Mailer
+    class DeliveryMethod
+      attr_accessor :settings
+
+      def initialize(settings)
+        @settings = settings
+        @underlying = nil
+      end
+
+      def deliver!(mail)
+        StandardCircuit.run(circuit_name) do
+          underlying_instance.deliver!(mail)
+        end
+      rescue Stoplight::Error::RedLight
+        raise retry_error_class.new(
+          recipients: Array(mail.to),
+          subject: mail.subject
+        )
+      end
+
+      private
+
+      def circuit_name
+        settings.fetch(:circuit)
+      end
+
+      def retry_error_class
+        settings.fetch(:retry_error_class, StandardCircuit::Mailer::CircuitOpenError)
+      end
+
+      def underlying_instance
+        @underlying ||= resolve_underlying
+      end
+
+      def resolve_underlying
+        target = settings.fetch(:underlying)
+        return target unless target.is_a?(Symbol)
+
+        registry = ::ActionMailer::Base.delivery_methods
+        klass = registry.fetch(target) do
+          raise ArgumentError, "unknown delivery method #{target.inspect}. Registered: #{registry.keys.inspect}"
+        end
+        klass.new(settings.fetch(:underlying_settings, {}))
+      end
+    end
+
+    if defined?(::Rails::Railtie)
+      class Railtie < ::Rails::Railtie
+        # ActionMailer's `add_delivery_method` unconditionally resets
+        # `<symbol>_settings` to its `default_options` arg. If the host app
+        # has already registered :standard_circuit (e.g. from its own
+        # `on_load(:action_mailer)` block in an env file, queued earlier),
+        # calling `add_delivery_method` again would wipe the settings the
+        # app just wrote — causing `KeyError: key not found: :circuit` at
+        # delivery time. Skip if already registered. (This guard assumes the
+        # host app registers first; if you call `add_delivery_method` from
+        # `after_initialize` or otherwise after the gem's Railtie hook fires,
+        # use `standard_circuit_settings=` directly to avoid the reset.)
+        def self.install(mailer_class)
+          return if mailer_class.delivery_methods.key?(:standard_circuit)
+
+          mailer_class.add_delivery_method :standard_circuit, StandardCircuit::Mailer::DeliveryMethod
+        end
+
+        initializer "standard_circuit.action_mailer" do
+          ActiveSupport.on_load(:action_mailer) do
+            StandardCircuit::Mailer::Railtie.install(self)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/standard_circuit/network_errors.rb

@@ -0,0 +1,22 @@
+require "net/http"
+require "openssl"
+require "socket"
+
+module StandardCircuit
+  module NetworkErrors
+    DEFAULTS = [
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT,
+      SocketError,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    def self.defaults
+      DEFAULTS.dup
+    end
+  end
+end

data/lib/standard_circuit/notifiers/logger.rb

@@ -0,0 +1,26 @@
+require "logger"
+
+module StandardCircuit
+  module Notifiers
+    class Logger
+      def initialize(logger = nil)
+        @logger = logger || ::Logger.new($stdout)
+      end
+
+      def notify(light, from_color, to_color, error)
+        message = build_message(light, from_color, to_color, error)
+        level = to_color == Stoplight::Color::RED ? :warn : :info
+        @logger.public_send(level, message)
+        message
+      end
+
+      private
+
+      def build_message(light, from_color, to_color, error)
+        words = [ "Stoplight", light.name, "switched from", from_color, "to", to_color ]
+        words += [ "because", error.class.name, error.message ] if error
+        words.join(" ")
+      end
+    end
+  end
+end

data/lib/standard_circuit/notifiers/metrics.rb

@@ -0,0 +1,24 @@
+module StandardCircuit
+  module Notifiers
+    class Metrics
+      STATE_FOR_COLOR = {
+        Stoplight::Color::RED => "opened",
+        Stoplight::Color::GREEN => "closed",
+        Stoplight::Color::YELLOW => "half_open"
+      }.freeze
+
+      def initialize(metric_prefix: "external")
+        @metric_prefix = metric_prefix
+      end
+
+      def notify(light, _from_color, to_color, _error)
+        state = STATE_FOR_COLOR.fetch(to_color, to_color)
+        ::Sentry::Metrics.count(
+          "#{@metric_prefix}.circuit_breaker",
+          value: 1,
+          attributes: { service: light.name, state: state }
+        )
+      end
+    end
+  end
+end

data/lib/standard_circuit/notifiers/sentry.rb

@@ -0,0 +1,24 @@
+module StandardCircuit
+  module Notifiers
+    class Sentry
+      def notify(light, from_color, to_color, error)
+        return unless to_color == Stoplight::Color::RED
+        return unless defined?(::Sentry) && ::Sentry.respond_to?(:capture_message)
+
+        message = "Circuit breaker opened: #{light.name}"
+        ::Sentry.capture_message(
+          message,
+          level: :warning,
+          extra: {
+            circuit: light.name,
+            from_color: from_color,
+            to_color: to_color,
+            error_class: error&.class&.name,
+            error_message: error&.message
+          }.compact
+        )
+        message
+      end
+    end
+  end
+end

data/lib/standard_circuit/rspec.rb

@@ -0,0 +1,18 @@
+require "standard_circuit"
+
+# Full StandardCircuit state reset between examples.
+#
+# - Clears the light cache so rebuilt lights pick up fresh config if a spec
+#   mutates it.
+# - Clears forced states (force_open / force_closed).
+# - Swaps a fresh Stoplight::DataStore::Memory into the Config when the
+#   current store is already Memory, so failure counters from one spec don't
+#   leak into the next. Redis stores are left alone.
+#
+# This is intentionally `before(:each)` rather than `after(:each)` so the
+# setup happens even when a previous example aborted in an after hook.
+RSpec.configure do |config|
+  config.before(:each) do
+    StandardCircuit.reset!
+  end
+end

data/lib/standard_circuit/runner.rb

@@ -0,0 +1,164 @@
+module StandardCircuit
+  class Runner
+    def initialize
+      @lights = Concurrent::Map.new
+      @forced_states = Concurrent::Map.new
+      @config = Config.new
+    end
+
+    def apply_config!(config)
+      @config = config
+      @lights.clear
+    end
+
+    def run(name, fallback: nil, &block)
+      forced = @forced_states[name.to_sym]
+      return run_forced_open(name, fallback) if forced == :open
+      return yield if forced == :closed
+
+      execute(name, fallback, &block)
+    end
+
+    def force_open(name, &block)
+      apply_force(name, :open, &block)
+    end
+
+    def force_closed(name, &block)
+      apply_force(name, :closed, &block)
+    end
+
+    def reset_force!
+      @forced_states.clear
+    end
+
+    # Full state reset for tests. Clears the light cache, forced states, AND
+    # swaps the Stoplight data store to a fresh Memory instance. Clearing the
+    # cache alone is not sufficient: failure counters live in the data store,
+    # so a spec that deliberately trips a circuit would otherwise leak RedLight
+    # into later specs. We only swap the store when the existing one is already
+    # a Memory store, because replacing a Redis store (production config) would
+    # silently defeat shared-process coordination.
+    def reset!
+      @lights.clear
+      @forced_states.clear
+      return unless @config.data_store.is_a?(Stoplight::DataStore::Memory)
+
+      @config.data_store = Stoplight::DataStore::Memory.new
+    end
+
+    def light_for(name)
+      @lights.compute_if_absent(name.to_sym) { build_light(name.to_sym) }
+    end
+
+    # Snapshot Hash of the current cached lights. Used by Health to discover
+    # prefix-matched circuits that have been exercised at least once — we can't
+    # enumerate prefix-matched dynamic names any other way.
+    def cached_lights
+      hash = {}
+      @lights.each_pair { |name, light| hash[name] = light }
+      hash
+    end
+
+    def health_snapshot
+      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.
+    def health_report
+      snapshot = health_snapshot
+      { status: Health.overall(snapshot), circuits: snapshot }
+    end
+
+    private
+
+    def execute(name, fallback, &block)
+      started_at = monotonic_now
+      light = light_for(name)
+
+      result = fallback ? light.run(fallback, &block) : light.run(&block)
+      emit_request_metric(name, :success, duration_ms(started_at))
+      result
+    rescue Stoplight::Error::RedLight => e
+      emit_request_metric(name, :circuit_open, duration_ms(started_at))
+      raise e unless fallback
+
+      fallback.call(nil)
+    rescue StandardError => e
+      emit_request_metric(name, :failure, duration_ms(started_at))
+      raise e
+    end
+
+    def run_forced_open(name, fallback)
+      emit_request_metric(name, :circuit_open, 0)
+      return fallback.call(nil) if fallback
+
+      spec = @config.spec_for(name)
+      raise Stoplight::Error::RedLight.new(
+        name.to_s,
+        cool_off_time: spec&.cool_off_time || Config::DEFAULT_COOL_OFF,
+        retry_after: nil
+      )
+    end
+
+    def apply_force(name, state)
+      key = name.to_sym
+      return set_force(key, state) unless block_given?
+
+      prior = @forced_states[key]
+      set_force(key, state)
+      begin
+        yield
+      ensure
+        prior.nil? ? @forced_states.delete(key) : set_force(key, prior)
+      end
+    end
+
+    def set_force(key, state)
+      @forced_states[key] = state
+    end
+
+    def build_light(name)
+      spec = @config.spec_for(name) or raise UnknownCircuit, "no circuit registered for #{name.inspect}"
+
+      Stoplight.light(
+        name.to_s,
+        threshold: spec.threshold,
+        cool_off_time: spec.cool_off_time,
+        window_size: spec.window_size,
+        tracked_errors: spec.tracked_errors,
+        skipped_errors: spec.skipped_errors,
+        data_store: @config.data_store,
+        notifiers: notifiers
+      )
+    end
+
+    def notifiers
+      @config.notifiers
+    end
+
+    def emit_request_metric(name, status, duration)
+      prefix = @config.metric_prefix
+      attrs = { service: name.to_s, status: status.to_s }
+      ::Sentry::Metrics.count("#{prefix}.request", value: 1, attributes: attrs)
+      ::Sentry::Metrics.distribution("#{prefix}.request.duration", duration, unit: "millisecond", attributes: attrs)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def duration_ms(started_at)
+      ((monotonic_now - started_at) * 1000.0).round(2)
+    end
+  end
+end

data/lib/standard_circuit/version.rb

@@ -0,0 +1,3 @@
+module StandardCircuit
+  VERSION = "0.1.0"
+end

data/lib/standard_circuit.rb

@@ -0,0 +1,72 @@
+require "stoplight"
+require "concurrent"
+require "sentry-ruby"
+
+require "standard_circuit/version"
+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/notifiers/logger"
+require "standard_circuit/notifiers/sentry"
+require "standard_circuit/notifiers/metrics"
+require "standard_circuit/config"
+require "standard_circuit/health"
+require "standard_circuit/runner"
+require "standard_circuit/mailer/circuit_open_error"
+require "standard_circuit/mailer/delivery_method"
+require "standard_circuit/controller_support"
+
+module StandardCircuit
+  class Error < StandardError; end
+  class UnknownCircuit < Error; end
+
+  class << self
+    def configure
+      yield config
+      runner.apply_config!(config)
+      config
+    end
+
+    def config
+      @config ||= Config.new
+    end
+
+    def runner
+      @runner ||= Runner.new
+    end
+
+    def run(name, fallback: nil, &block)
+      runner.run(name, fallback: fallback, &block)
+    end
+
+    def force_open(name, &block)
+      runner.force_open(name, &block)
+    end
+
+    def force_closed(name, &block)
+      runner.force_closed(name, &block)
+    end
+
+    def reset_force!
+      runner.reset_force!
+    end
+
+    def reset!
+      runner.reset!
+    end
+
+    def health_snapshot
+      runner.health_snapshot
+    end
+
+    def health_overall(snapshot = nil)
+      runner.health_overall(snapshot)
+    end
+
+    def health_report
+      runner.health_report
+    end
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: standard_circuit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jaryl Sim
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: stoplight
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.8'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sentry-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.17'
+- !ruby/object:Gem::Dependency
+  name: railties
+  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'
+description: StandardCircuit wraps the stoplight gem with opinionated error taxonomy,
+  Sentry notifiers, ActiveStorage S3 and ActionMailer adapters, and test helpers shared
+  across Rails apps.
+email:
+- code@jaryl.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/active_storage/service/standard_circuit_s3_service.rb
+- 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/smtp.rb
+- lib/standard_circuit/adapter_errors/stripe.rb
+- lib/standard_circuit/config.rb
+- lib/standard_circuit/controller_support.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/network_errors.rb
+- lib/standard_circuit/notifiers/logger.rb
+- lib/standard_circuit/notifiers/metrics.rb
+- lib/standard_circuit/notifiers/sentry.rb
+- lib/standard_circuit/rspec.rb
+- lib/standard_circuit/runner.rb
+- lib/standard_circuit/version.rb
+homepage: https://github.com/rarebit-one/standard_circuit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rarebit-one/standard_circuit
+  source_code_uri: https://github.com/rarebit-one/standard_circuit
+  changelog_uri: https://github.com/rarebit-one/standard_circuit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rarebit-one/standard_circuit/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Circuit breaker primitives for Rails apps, built on stoplight.
+test_files: []