standard_circuit 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e92eb79ddb1cfc0f2e9221aa62f45d7c304df0dfea22c114eb31a78c071b6c3c
-  data.tar.gz: 0aac1e3c093805ea2825cfb434840d83842999cb757cdcca896466c86a6abbff
+  metadata.gz: f8a58ef94e0f296c0e3b107fda1decfc29037324942c5326ec2fcfd1fdf19f2f
+  data.tar.gz: b3a78ae40f5a60c0e9754011eca3174ec4d489f61e51d41f81a6eb5a7efeb946
 SHA512:
-  metadata.gz: 9e5ac3bb1d7352c6300fa70530602910dd3a45539e1cfad5d45b8ac702a223a22961cdaef377daf7c968ad7bbb5db54814c70a40b1a054a41df88c15fc5908c2
-  data.tar.gz: e8f4b265dd59f67442b52fafdb4db15923236df241b4296adc80bb6576654a888cdc564a5c2aa36e9ad291f5720f0c7fae7a274edcce046bb6995b6fbcb04dc7
+  metadata.gz: c9e4a015cf36e76ff7bece785930be035b323e4306897538750d5641237b0c34a931ba69f72aeb568456202b1472657d9e44c628967bbcd0bf2d240727c34a9b
+  data.tar.gz: 37a2b60ddb1488905ab5a01652ca41fd5f5452e55f689168041edb3dd46235503c31c23e92d51b154d86f1faaae3755aa506b05c15aef6f9e77a7463fff02ce3

data/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-28
+
+### Added
+- Rails event emission for every circuit-breaker lifecycle moment. The `StandardCircuit::Runner` (via a small internal `NotifierBridge` registered with Stoplight) now emits five events as host apps' breakers change state:
+  - `standard_circuit.circuit.opened` — RED transition (the "alert me" event)
+  - `standard_circuit.circuit.closed` — GREEN transition (recovery)
+  - `standard_circuit.circuit.degraded` — YELLOW transition (half-open probe)
+  - `standard_circuit.circuit.fallback_invoked` — Runner returned a fallback rather than raising RedLight
+  - `standard_circuit.circuit.registered` — `Config#register` / `register_prefix` was called
+
+  Payloads carry `circuit:`, `from_color:`, `to_color:`, `criticality:`, and (when applicable) `error_class:` / `error_message:` / `reason:`.
+- `standard_circuit.run.completed` event. Per-call complement to the lifecycle events above — fires once per wrapped `StandardCircuit.run` invocation with `circuit:`, `status:` (`:success` / `:failure` / `:circuit_open`), `duration_ms:`, `criticality:`, `error_class:`, and `error_message:`. The right hook for cost-tracking, p95 latency, and per-circuit success-rate dashboards. (`force_closed` runs are intentionally not emitted — that path bypasses the runner.) Routed through the same `EventEmitter` as the lifecycle events, so subscribers get it on `Rails.event` (8.1+) or `ActiveSupport::Notifications` automatically; `duration_ms` is in the payload (not `event.duration`) so backend choice doesn't matter.
+- Dual-backend dispatch in `StandardCircuit::EventEmitter`: emits through `Rails.event.notify` on Rails 8.1+ and falls back to `ActiveSupport::Notifications.instrument` on older Rails. Detection happens at call time, so the gem still loads cleanly before Rails has booted and before `railties` is even required.
+- `StandardCircuit::Engine` Railtie that registers the internal subscribers (Logger / Sentry / Metrics) plus any `extra_notifiers` at boot via the `standard_circuit.subscribers` initializer.
+- `StandardCircuit.subscribers` accessor + `Subscribers#setup!` / `#teardown!` for tests and host apps that need to re-register listeners after mutating config.
+- `rails g standard_circuit:install` — Rails install generator. Writes `config/initializers/standard_circuit.rb` with commented-out examples covering the public Config DSL (`register`, `register_prefix`, notifiers, data store, criticality). Idempotent: re-running on an existing initializer skips with a clear message; pass `--force` to overwrite. Pass `--with-health-endpoint` to also write `config/initializers/standard_circuit_health.rb` (which `require`s the opt-in `HealthController`) and print the route line to add to `config/routes.rb`. The generator does not auto-edit `routes.rb` — too invasive — so consumers paste the printed line themselves.
+- README section on streaming responses and non-controller contexts: shows the recipe for catching `Stoplight::Error::RedLight` inside a `Live` controller's streaming proc (where `circuit_open_fallback` can't render over an open response), and notes the equivalent pattern for background jobs.
+
+### Changed
+- **BREAKING.** `StandardCircuit::Notifiers::{Logger,Sentry,Metrics}` are no longer Stoplight-shaped notifiers. Each now exposes `call(event_name, payload)` and is registered as an event subscriber by the gem's Railtie. They are still considered an internal implementation detail — host apps that want their own behaviour should subscribe to the `standard_circuit.*` namespace directly rather than instantiating these classes.
+- **BREAKING.** `Config#add_notifier` now requires the supplied object to respond to `call(event_name, payload)`. Stoplight-shaped 4-arg notifiers from 0.1.x are rejected with `ArgumentError`. Callers should subscribe via `Rails.event.subscribe` / `ActiveSupport::Notifications.subscribe("standard_circuit.*")` for full control, or pass a lambda to `add_notifier` for the simple case.
+- **BREAKING.** Stoplight only sees a single internal `StandardCircuit::NotifierBridge` notifier now; host apps that previously read `StandardCircuit.config.notifiers` to build their own Stoplight light will need to register against the new event namespace instead.
+- README "Quick start" and the `rails g standard_circuit:install` initializer template now use `ErrorTaxonomies::*.tracked` consistently (the S3 example in the template still showed the pre-0.1.2 `AdapterErrors::Aws.server_errors` form).
+- The install template's "Extra notifiers" example now uses `add_notifier` with a 2-arg `call(name, payload)` callable, matching the contract `Config#add_notifier` enforces. The previous example wrote directly to `extra_notifiers <<` with a 1-arg lambda — both bypassing validation and using the wrong arity, so any consumer who uncommented it would get `ArgumentError: wrong number of arguments` on the first emitted event.
+- `lib/standard_circuit/rspec.rb` now also tears down event subscribers between examples so a spec that subscribes manually doesn't leak listeners into the next.
+- CI and release workflows migrated to the shared `rarebit-one/.github` reusable workflows (`reusable-gem-ci.yml@v1`, `reusable-gem-release.yml@v1`); `.github/workflows/ci.yml` and `release.yml` are now thin shims.
+
 ## [0.1.2] - 2026-04-27
 
 ### Added
@@ -37,6 +64,7 @@ All notable changes to this project will be documented in this file.
 - `StandardCircuit.force_open`, `force_closed`, `reset_force!` + `require "standard_circuit/rspec"` for auto-cleanup.
 
 ### Changed
+- Minimum Ruby version is now `>= 4.0` (was `>= 3.4`). CI tests all four published 4.0.x patches.
 - 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/README.md

@@ -6,7 +6,7 @@ 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`)
+- Rails event emission (`standard_circuit.circuit.{opened,closed,degraded,fallback_invoked,registered}`) with built-in Logger, Sentry, and Sentry::Metrics subscribers
 - 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`
@@ -19,6 +19,22 @@ Wraps the upstream `stoplight` gem with:
 gem "standard_circuit", git: "https://github.com/rarebit-one/standard_circuit", ref: "<sha>"
 ```
 
+Then run the install generator to drop a commented-out initializer into
+`config/initializers/standard_circuit.rb`:
+
+```bash
+bundle add standard_circuit
+rails g standard_circuit:install
+```
+
+Pass `--with-health-endpoint` to also generate
+`config/initializers/standard_circuit_health.rb` (which requires the opt-in
+health controller); the generator prints the matching route line for you to
+add to `config/routes.rb`.
+
+The generator is idempotent — re-running skips an existing initializer
+unless you pass `--force`.
+
 ## Quick start
 
 ```ruby
@@ -30,7 +46,7 @@ StandardCircuit.configure do |c|
   c.register(:stripe,
     threshold: 5,
     cool_off_time: 30,
-    tracked_errors: StandardCircuit::NetworkErrors.defaults + StandardCircuit::AdapterErrors::Stripe.server_errors,
+    tracked_errors: StandardCircuit::ErrorTaxonomies::Stripe.tracked,
     skipped_errors: StandardCircuit::AdapterErrors::Stripe.caller_errors)
 end
 ```
@@ -42,6 +58,78 @@ StandardCircuit.run(:stripe) do
 end
 ```
 
+## Events
+
+Every circuit lifecycle moment is emitted as a Rails event. On Rails 8.1+ the canonical bus is `Rails.event`; on older Rails versions the gem transparently falls back to `ActiveSupport::Notifications`. Detection happens per-emit, so subscribers do not need to care which backend is live.
+
+| Event | When it fires | Payload |
+|-------|---------------|---------|
+| `standard_circuit.circuit.opened` | RED transition (circuit tripped) | `circuit:, from_color:, to_color:, criticality:, error_class:, error_message:` |
+| `standard_circuit.circuit.closed` | GREEN transition (recovered) | `circuit:, from_color:, to_color:, criticality:` |
+| `standard_circuit.circuit.degraded` | YELLOW transition (half-open probe) | `circuit:, from_color:, to_color:, criticality:` |
+| `standard_circuit.circuit.fallback_invoked` | Runner returned a fallback instead of raising RedLight | `circuit:, reason: (:circuit_open\|:forced_open), criticality:` |
+| `standard_circuit.circuit.registered` | `Config#register` / `register_prefix` was called (see note below) | `circuit:, criticality:, scope: (:name\|:prefix)` |
+| `standard_circuit.run.completed` | Every wrapped `StandardCircuit.run` call (success, failure, or circuit_open) | `circuit:, status: (:success\|:failure\|:circuit_open), duration_ms:, criticality:, error_class:, error_message:` |
+
+> **Note on `standard_circuit.run.completed`:** the per-call event for cost / latency / success-rate dashboards. Fires on every `Runner#execute` invocation and on `force_open` runs; **not** emitted for `force_closed` runs (which intentionally bypass the runner). All payload keys are always present — `error_class` and `error_message` are `nil` on `:success`. Payload duration uses `duration_ms` (numeric), not `event.duration`, so subscribers work identically on the `Rails.event` and `ActiveSupport::Notifications` backends.
+
+> **Note on `standard_circuit.circuit.registered`:** subscribers are wired up *after* the `StandardCircuit.configure` block yields, so any `c.register` calls inside that block fire before any subscriber can hear them. This event is reliable only for post-boot, dynamic `register` / `register_prefix` calls — do not rely on it for a boot-time circuit inventory.
+
+Built-in subscribers (Logger / Sentry / Metrics) are registered automatically by the gem's Railtie. Host apps can subscribe to the namespace however they like:
+
+```ruby
+# Rails 8.1+
+class MyAuditSubscriber
+  def emit(event)
+    return unless event[:name].start_with?("standard_circuit.")
+    Rails.logger.info("circuit event: #{event[:name]} #{event[:payload].inspect}")
+  end
+end
+Rails.event.subscribe(MyAuditSubscriber.new)
+
+# Older Rails
+ActiveSupport::Notifications.subscribe(/\Astandard_circuit\./) do |name, _start, _finish, _id, payload|
+  Rails.logger.info("circuit event: #{name} #{payload.inspect}")
+end
+
+# Quick host-supplied callable (auto-wired at boot via the Railtie)
+StandardCircuit.configure do |c|
+  c.add_notifier(->(name, payload) { MyAlerting.notify(name, payload) })
+end
+```
+
+## Streaming and non-controller contexts
+
+`ControllerSupport.circuit_open_fallback` only works for non-streaming responses — once a `Live` controller has flushed any output, Rails can't render an error template over the wire. For a streaming controller, catch `Stoplight::Error::RedLight` *inside* the streaming proc and write a degraded payload before the stream closes:
+
+```ruby
+class Api::MessagesController < ApplicationController
+  include ActionController::Live
+
+  def stream
+    response.headers["Content-Type"] = "application/x-ndjson"
+
+    StandardCircuit.run(:openai) do
+      llm.stream do |chunk|
+        response.stream.write({ delta: chunk }.to_json + "\n")
+      end
+    end
+  rescue Stoplight::Error::RedLight
+    # Only reachable when the circuit was already open at call time —
+    # Stoplight raises RedLight before executing the block, not mid-stream.
+    # Errors raised mid-stream propagate as their original class through the
+    # `ensure` below; add a broader rescue if you also need to write a
+    # terminal NDJSON line for those.
+    response.stream.write({ error: "service_unavailable" }.to_json + "\n")
+  ensure
+    response.stream.close
+  end
+end
+```
+
+Same pattern applies in background jobs (where `circuit_open_fallback` doesn't help): wrap the work in `StandardCircuit.run` and rescue `Stoplight::Error::RedLight` to either `discard_on` (avoid thundering retries) or `retry_on` with backoff (defer until cool-off), depending on whether eventual delivery is required.
+
+
 ## 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.

data/lib/generators/standard_circuit/install/install_generator.rb

@@ -0,0 +1,77 @@
+require "rails/generators"
+
+module StandardCircuit
+  module Generators
+    # Installs StandardCircuit in a host Rails application.
+    #
+    # By default, writes config/initializers/standard_circuit.rb with
+    # commented-out examples covering the public Config DSL.
+    #
+    # When +--with-health-endpoint+ is passed, also writes
+    # config/initializers/standard_circuit_health.rb (which requires the
+    # opt-in HealthController) and prints the route line the host should
+    # add to config/routes.rb to expose the endpoint.
+    #
+    # Idempotent: re-running on an existing initializer logs and skips. Pass
+    # +--force+ to overwrite.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Installs StandardCircuit. By default this writes
+        config/initializers/standard_circuit.rb with commented-out examples
+        covering circuit registration, prefix registration, and notifier
+        wiring.
+
+        Pass --with-health-endpoint to also write
+        config/initializers/standard_circuit_health.rb (which requires the
+        opt-in HealthController) and print the route line to add to
+        config/routes.rb.
+
+        The generator is idempotent — already-installed initializers are
+        skipped with a clear message. Pass --force to overwrite.
+      DESC
+
+      class_option :with_health_endpoint, type: :boolean, default: false,
+        desc: "Also create config/initializers/standard_circuit_health.rb and print the route hint"
+
+      def create_initializer_file
+        path = "config/initializers/standard_circuit.rb"
+        if File.exist?(File.join(destination_root, path)) && !options[:force]
+          say_status("skip", "#{path} already present, skipping (use --force to overwrite)", :yellow)
+          return
+        end
+
+        template "initializer.rb.tt", path
+      end
+
+      def create_health_initializer_file
+        return unless options[:with_health_endpoint]
+
+        path = "config/initializers/standard_circuit_health.rb"
+        if File.exist?(File.join(destination_root, path)) && !options[:force]
+          say_status("skip", "#{path} already present, skipping (use --force to overwrite)", :yellow)
+        else
+          template "health_initializer.rb.tt", path
+        end
+      end
+
+      def print_health_route_hint
+        return unless options[:with_health_endpoint]
+
+        say ""
+        say "=" * 79
+        say "StandardCircuit health endpoint installed."
+        say ""
+        say "Add the following to config/routes.rb to expose the endpoint:"
+        say ""
+        say '  get "/health", to: "standard_circuit/health#show"'
+        say ""
+        say "The controller returns 503 when the rolled-up circuit health is"
+        say ":critical and 200 otherwise — wire it up to your load balancer."
+        say "=" * 79
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/standard_circuit/install/templates/health_initializer.rb.tt

@@ -0,0 +1,13 @@
+# StandardCircuit health-check controller
+# Generated by: rails g standard_circuit:install --with-health-endpoint
+#
+# The controller is opt-in: this require pulls it onto the autoload path so
+# the route below resolves. Add the matching route to config/routes.rb:
+#
+#   get "/health", to: "standard_circuit/health#show"
+#
+# The endpoint renders StandardCircuit.health_report as JSON and returns
+# 503 when the rolled-up status is :critical (so orchestrators pull the
+# instance out of rotation) and 200 otherwise.
+
+require "standard_circuit/health_controller"

data/lib/generators/standard_circuit/install/templates/initializer.rb.tt

@@ -0,0 +1,83 @@
+# StandardCircuit configuration
+# Generated by: rails g standard_circuit:install
+#
+# StandardCircuit wraps the upstream `stoplight` gem with an opinionated
+# error taxonomy, Sentry/metrics notifiers, ActiveStorage and ActionMailer
+# adapters, and a Rails-aware health rollup.
+#
+# All commented-out lines below show the public DSL — uncomment and edit
+# the ones that apply to your app.
+
+StandardCircuit.configure do |config|
+  # ---------------------------------------------------------------------------
+  # Global settings
+  # ---------------------------------------------------------------------------
+
+  # Send Sentry warnings on GREEN -> RED transitions.
+  # Default: true
+  # config.sentry_enabled = true
+
+  # Prefix used for emitted metrics (e.g. "<prefix>.circuit_breaker",
+  # "<prefix>.request"). Default: "external"
+  # config.metric_prefix = "external"
+
+  # Logger used by the built-in Logger notifier. Falls back to nil (no
+  # logging) when unset; assign Rails.logger or a custom logger to enable.
+  # Default: nil
+  # config.logger = Rails.logger
+
+  # Stoplight data store. Default: in-memory (per-process). Use a shared
+  # store (e.g. Stoplight::DataStore::Redis) when you want circuit state
+  # shared across processes/hosts.
+  # Default: Stoplight::DataStore::Memory.new
+  # config.data_store = Stoplight::DataStore::Redis.new(Redis.new)
+
+  # ---------------------------------------------------------------------------
+  # Circuit registration
+  # ---------------------------------------------------------------------------
+  # Each call to `register` declares a named circuit. Supported options:
+  #
+  #   threshold       — failures before tripping (default: 3)
+  #   cool_off_time   — seconds before half-open retry (default: 30)
+  #   window_size     — seconds for the rolling failure window (default: 60)
+  #   tracked_errors  — error classes that count toward the threshold
+  #                     (default: StandardCircuit::NetworkErrors.defaults)
+  #   skipped_errors  — error classes that bypass the circuit (re-raised
+  #                     without counting — typically caller/validation errors)
+  #   criticality     — :critical | :standard | :optional
+  #                     (affects health rollup; default: :standard)
+
+  # config.register(:stripe,
+  #   threshold: 5,
+  #   cool_off_time: 60,
+  #   tracked_errors: StandardCircuit::ErrorTaxonomies::Stripe.tracked,
+  #   skipped_errors: StandardCircuit::AdapterErrors::Stripe.caller_errors,
+  #   criticality: :critical)
+
+  # config.register(:smtp,
+  #   tracked_errors: StandardCircuit::ErrorTaxonomies::Smtp.tracked,
+  #   criticality: :standard)
+
+  # ---------------------------------------------------------------------------
+  # Prefix registration
+  # ---------------------------------------------------------------------------
+  # Use `register_prefix` to dynamically name circuits matching a pattern.
+  # The first matching prefix wins; the circuit name is "<prefix>_<suffix>".
+
+  # config.register_prefix(:s3,
+  #   threshold: 10,
+  #   tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked,
+  #   criticality: :standard)
+
+  # ---------------------------------------------------------------------------
+  # Extra notifiers
+  # ---------------------------------------------------------------------------
+  # Built-in subscribers (Logger / Sentry / Metrics) are wired up automatically.
+  # For most cases, prefer subscribing to the `standard_circuit.*` namespace
+  # directly via `Rails.event.subscribe` (Rails 8.1+) or
+  # `ActiveSupport::Notifications.subscribe`. `add_notifier` is a convenience
+  # for registering a callable that follows the same `call(event_name, payload)`
+  # contract as the built-in subscribers.
+
+  # config.add_notifier(->(name, payload) { MyTracer.record(name, payload) })
+end

data/lib/standard_circuit/config.rb

@@ -46,13 +46,6 @@ module StandardCircuit
       @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
@@ -60,14 +53,34 @@ module StandardCircuit
     end
 
     def register(name, **opts)
-      @circuits[name.to_sym] = CircuitSpec.build(**opts)
+      spec = CircuitSpec.build(**opts)
+      @circuits[name.to_sym] = spec
+      EventEmitter.emit("standard_circuit.circuit.registered",
+        circuit: name.to_s,
+        criticality: spec.criticality,
+        scope: :name)
+      spec
     end
 
     def register_prefix(prefix, **opts)
-      @prefixes[prefix.to_s] = CircuitSpec.build(**opts)
+      spec = CircuitSpec.build(**opts)
+      @prefixes[prefix.to_s] = spec
+      EventEmitter.emit("standard_circuit.circuit.registered",
+        circuit: prefix.to_s,
+        criticality: spec.criticality,
+        scope: :prefix)
+      spec
     end
 
+    # Register a host-supplied subscriber. Subscribers must respond to
+    # `call(event_name, payload)` — Stoplight-shaped 4-arg notifiers from the
+    # 0.1.x API are no longer accepted as extras (Logger / Sentry / Metrics
+    # demonstrate the new shape).
     def add_notifier(notifier)
+      unless notifier.respond_to?(:call)
+        raise ArgumentError,
+          "extra notifiers must respond to `call(event_name, payload)`; got #{notifier.class}"
+      end
       @extra_notifiers << notifier
     end
 

data/lib/standard_circuit/engine.rb

@@ -0,0 +1,16 @@
+module StandardCircuit
+  # Boot hook: register the internal Logger / Sentry / Metrics subscribers (and
+  # any `extra_notifiers` the host configured) against whichever event bus is
+  # live in this Rails version.
+  #
+  # We hook `after: :load_config_initializers` so any host-side
+  # `StandardCircuit.configure` block in `config/initializers/*` has finished
+  # running and `extra_notifiers` / `metric_prefix` / `logger` are in their
+  # final state when the subscriber set is built. This is independent of
+  # ActiveRecord — apps that don't load AR still need observability.
+  class Engine < ::Rails::Engine
+    initializer "standard_circuit.subscribers", after: :load_config_initializers do
+      StandardCircuit.subscribers.setup!
+    end
+  end
+end

data/lib/standard_circuit/event_emitter.rb

@@ -0,0 +1,35 @@
+module StandardCircuit
+  # Internal helper that emits StandardCircuit lifecycle events through whichever
+  # event reporter is live in the host process.
+  #
+  # - On Rails 8.1+, `Rails.event.notify(name, **payload)` is the canonical bus.
+  # - On older Rails (or any host without the structured reporter), we fall back
+  #   to `ActiveSupport::Notifications.instrument(name, payload)`.
+  #
+  # Detection is performed at *call time* — the gem is required before Rails has
+  # finished booting, so we cannot cache the decision at load time.
+  #
+  # @api private
+  module EventEmitter
+    module_function
+
+    # Emit a single event. Both backends are best-effort: any exception raised
+    # by a subscriber is swallowed so circuit-breaker observability never takes
+    # down a circuit-protected request.
+    def emit(event_name, payload)
+      if rails_event_available?
+        ::Rails.event.notify(event_name, **payload)
+      else
+        ::ActiveSupport::Notifications.instrument(event_name, payload)
+      end
+    rescue => e
+      warn "[StandardCircuit] event emit for #{event_name.inspect} failed: #{e.class}: #{e.message}"
+    end
+
+    def rails_event_available?
+      defined?(::Rails) &&
+        ::Rails.respond_to?(:event) &&
+        ::Rails.event.respond_to?(:notify)
+    end
+  end
+end

data/lib/standard_circuit/notifier_bridge.rb

@@ -0,0 +1,49 @@
+module StandardCircuit
+  # Stoplight-shaped notifier whose only job is to translate the upstream
+  # `notifier.notify(light, from_color, to_color, error)` callback into a
+  # StandardCircuit Rails event.
+  #
+  # Stoplight calls notifiers on every color transition (GREEN<->RED, RED->YELLOW
+  # for half-open recovery). We map each transition to a stable event name and
+  # forward a uniform payload to whichever event bus is live.
+  #
+  # This is the single Stoplight notifier StandardCircuit registers — Logger,
+  # Sentry, and Metrics are now subscribers, not direct notifiers.
+  #
+  # @api private
+  class NotifierBridge
+    EVENT_FOR_COLOR = {
+      Stoplight::Color::RED    => "standard_circuit.circuit.opened",
+      Stoplight::Color::GREEN  => "standard_circuit.circuit.closed",
+      Stoplight::Color::YELLOW => "standard_circuit.circuit.degraded"
+    }.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    def notify(light, from_color, to_color, error)
+      event_name = EVENT_FOR_COLOR[to_color]
+      return unless event_name
+
+      EventEmitter.emit(event_name, payload_for(light, from_color, to_color, error))
+    end
+
+    private
+
+    def payload_for(light, from_color, to_color, error)
+      spec = @config.spec_for(light.name)
+      payload = {
+        circuit: light.name,
+        from_color: from_color,
+        to_color: to_color,
+        criticality: spec&.criticality
+      }
+      if error
+        payload[:error_class] = error.class.name
+        payload[:error_message] = error.message
+      end
+      payload
+    end
+  end
+end

data/lib/standard_circuit/notifiers/logger.rb

@@ -2,23 +2,43 @@ require "logger"
 
 module StandardCircuit
   module Notifiers
+    # Subscribes to standard_circuit.circuit.* events and writes a human-readable
+    # log line for each transition. Always-on by default; pass a custom logger
+    # via `StandardCircuit.config.logger=`.
     class Logger
+      TRANSITION_EVENTS = %w[
+        standard_circuit.circuit.opened
+        standard_circuit.circuit.closed
+        standard_circuit.circuit.degraded
+      ].freeze
+
       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
+      def call(event_name, payload)
+        return unless TRANSITION_EVENTS.include?(event_name)
+
+        message = build_message(event_name, payload)
+        level = event_name == "standard_circuit.circuit.opened" ? :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
+      def build_message(event_name, payload)
+        words = [
+          "Stoplight",
+          payload[:circuit],
+          "switched from",
+          payload[:from_color],
+          "to",
+          payload[:to_color]
+        ]
+        if payload[:error_class]
+          words += [ "because", payload[:error_class], payload[:error_message] ]
+        end
         words.join(" ")
       end
     end

data/lib/standard_circuit/notifiers/metrics.rb

@@ -1,22 +1,26 @@
 module StandardCircuit
   module Notifiers
+    # Subscribes to all standard_circuit.circuit.{opened,closed,degraded} events
+    # and emits a Sentry::Metrics counter with the canonical state name.
     class Metrics
-      STATE_FOR_COLOR = {
-        Stoplight::Color::RED => "opened",
-        Stoplight::Color::GREEN => "closed",
-        Stoplight::Color::YELLOW => "half_open"
+      STATE_FOR_EVENT = {
+        "standard_circuit.circuit.opened"   => "opened",
+        "standard_circuit.circuit.closed"   => "closed",
+        "standard_circuit.circuit.degraded" => "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)
+      def call(event_name, payload)
+        state = STATE_FOR_EVENT[event_name]
+        return unless state
+
         ::Sentry::Metrics.count(
           "#{@metric_prefix}.circuit_breaker",
           value: 1,
-          attributes: { service: light.name, state: state }
+          attributes: { service: payload[:circuit], state: state }
         )
       end
     end

data/lib/standard_circuit/notifiers/sentry.rb

@@ -1,20 +1,23 @@
 module StandardCircuit
   module Notifiers
+    # Subscribes to standard_circuit.circuit.opened and forwards a warning-level
+    # message to Sentry. Other transitions are ignored — only RED matters for
+    # alerting.
     class Sentry
-      def notify(light, from_color, to_color, error)
-        return unless to_color == Stoplight::Color::RED
+      def call(event_name, payload)
+        return unless event_name == "standard_circuit.circuit.opened"
         return unless defined?(::Sentry) && ::Sentry.respond_to?(:capture_message)
 
-        message = "Circuit breaker opened: #{light.name}"
+        message = "Circuit breaker opened: #{payload[:circuit]}"
         ::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
+            circuit: payload[:circuit],
+            from_color: payload[:from_color],
+            to_color: payload[:to_color],
+            error_class: payload[:error_class],
+            error_message: payload[:error_message]
           }.compact
         )
         message

data/lib/standard_circuit/rspec.rb

@@ -5,14 +5,27 @@ require "standard_circuit"
 # - Clears the light cache so rebuilt lights pick up fresh config if a spec
 #   mutates it.
 # - Clears forced states (force_open / force_closed).
+# - Tears down all event subscribers so a spec that subscribes manually doesn't
+#   leak listeners into the next example. The internal Logger/Sentry/Metrics
+#   subscribers are re-registered if a spec calls `StandardCircuit.configure`
+#   or `StandardCircuit.subscribers.setup!`.
 # - 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.
 #
+# Circuit registrations are intentionally NOT cleared. Host apps usually
+# define circuits once in a `config/initializers/standard_circuit.rb`
+# initializer; clearing the registry between examples would force every spec
+# to re-`configure`. Specs that register circuits in `before(:each)` are
+# unaffected by leftover registrations from prior examples (the new register
+# call wins). If you do need a clean registry, call
+# `StandardCircuit.config.reset_registry!` explicitly in your own hook.
+#
 # 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!
+    StandardCircuit.subscribers.teardown!
   end
 end

data/lib/standard_circuit/runner.rb

@@ -86,21 +86,32 @@ module StandardCircuit
       light = light_for(name)
 
       result = fallback ? light.run(fallback, &block) : light.run(&block)
-      emit_request_metric(name, :success, duration_ms(started_at))
+      duration = duration_ms(started_at)
+      emit_request_metric(name, :success, duration)
+      emit_run_completed(name, status: :success, duration_ms: duration)
       result
     rescue Stoplight::Error::RedLight => e
-      emit_request_metric(name, :circuit_open, duration_ms(started_at))
+      duration = duration_ms(started_at)
+      emit_request_metric(name, :circuit_open, duration)
+      emit_run_completed(name, status: :circuit_open, duration_ms: duration, error: e)
       raise e unless fallback
 
+      emit_fallback_invoked(name, reason: :circuit_open)
       fallback.call(nil)
     rescue StandardError => e
-      emit_request_metric(name, :failure, duration_ms(started_at))
+      duration = duration_ms(started_at)
+      emit_request_metric(name, :failure, duration)
+      emit_run_completed(name, status: :failure, duration_ms: duration, error: e)
       raise e
     end
 
     def run_forced_open(name, fallback)
       emit_request_metric(name, :circuit_open, 0)
-      return fallback.call(nil) if fallback
+      emit_run_completed(name, status: :circuit_open, duration_ms: 0)
+      if fallback
+        emit_fallback_invoked(name, reason: :forced_open)
+        return fallback.call(nil)
+      end
 
       spec = @config.spec_for(name)
       raise Stoplight::Error::RedLight.new(
@@ -138,14 +149,10 @@ module StandardCircuit
         tracked_errors: spec.tracked_errors,
         skipped_errors: spec.skipped_errors,
         data_store: @config.data_store,
-        notifiers: notifiers
+        notifiers: [ NotifierBridge.new(@config) ]
       )
     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 }
@@ -153,6 +160,25 @@ module StandardCircuit
       ::Sentry::Metrics.distribution("#{prefix}.request.duration", duration, unit: "millisecond", attributes: attrs)
     end
 
+    def emit_fallback_invoked(name, reason:)
+      spec = @config.spec_for(name)
+      EventEmitter.emit("standard_circuit.circuit.fallback_invoked",
+        circuit: name.to_s,
+        reason: reason,
+        criticality: spec&.criticality)
+    end
+
+    def emit_run_completed(name, status:, duration_ms:, error: nil)
+      spec = @config.spec_for(name)
+      EventEmitter.emit("standard_circuit.run.completed",
+        circuit: name.to_s,
+        status: status,
+        duration_ms: duration_ms,
+        criticality: spec&.criticality,
+        error_class: error&.class&.name,
+        error_message: error&.message)
+    end
+
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/standard_circuit/subscribers.rb

@@ -0,0 +1,102 @@
+module StandardCircuit
+  # Registers internal and user-supplied subscribers against whichever event
+  # bus is live (Rails.event on 8.1+, ActiveSupport::Notifications elsewhere).
+  #
+  # Each subscriber must respond to `call(event_name, payload)`. Internal
+  # subscribers (Logger / Sentry / Metrics) are built from the live config so
+  # changes to `metric_prefix` / `logger` propagate when `setup!` is re-run.
+  #
+  # Subscriptions cover the namespace prefix `standard_circuit.`, so a single
+  # registration on each backend listens for every lifecycle event the gem
+  # emits — bridge color transitions plus runner-side fallback / registration.
+  #
+  # @api private
+  class Subscribers
+    EVENT_PATTERN = "standard_circuit."
+    EVENT_REGEXP = /\A#{Regexp.escape(EVENT_PATTERN)}/
+
+    def initialize
+      @rails_event_subscribers = []
+      @as_subscribers = []
+    end
+
+    def setup!
+      teardown!
+      register(internal_subscribers + extra_subscribers)
+    end
+
+    # Tear down both backends. Rails.event subscribers are unsubscribed
+    # unconditionally — we recorded them at registration time, so we must
+    # remove them even if Rails.event has since become unavailable (e.g. test
+    # `hide_const("Rails")`). Otherwise the wrappers would remain live in the
+    # bus while we believe they are gone.
+    def teardown!
+      @rails_event_subscribers.each do |subscriber|
+        ::Rails.event.unsubscribe(subscriber) if EventEmitter.rails_event_available?
+      rescue StandardError
+        # If Rails.event is gone (test isolation), we can do nothing more —
+        # clearing the array still releases our reference.
+      end
+      @rails_event_subscribers.clear
+
+      @as_subscribers.each do |subscriber|
+        ::ActiveSupport::Notifications.unsubscribe(subscriber)
+      end
+      @as_subscribers.clear
+    end
+
+    private
+
+    def register(subscribers)
+      subscribers.each do |subscriber|
+        register_one(subscriber)
+      end
+    end
+
+    # Register on whichever backend is live. We do not double-subscribe — if
+    # `Rails.event` is present, every emit goes through it (see EventEmitter),
+    # so the AS::Notifications side would never receive anything.
+    def register_one(subscriber)
+      if EventEmitter.rails_event_available?
+        wrapper = RailsEventAdapter.new(subscriber)
+        ::Rails.event.subscribe(wrapper)
+        @rails_event_subscribers << wrapper
+      else
+        handle = ::ActiveSupport::Notifications.subscribe(EVENT_REGEXP) do |name, _start, _finish, _id, payload|
+          subscriber.call(name, payload)
+        end
+        @as_subscribers << handle
+      end
+    end
+
+    def internal_subscribers
+      config = StandardCircuit.config
+      list = [ Notifiers::Logger.new(config.logger) ]
+      list << Notifiers::Sentry.new if config.sentry_enabled
+      list << Notifiers::Metrics.new(metric_prefix: config.metric_prefix)
+      list
+    end
+
+    # Config#add_notifier already enforces that every entry responds to :call,
+    # so we can hand the array straight through to register/1.
+    def extra_subscribers
+      StandardCircuit.config.extra_notifiers
+    end
+
+    # Adapts a `call(name, payload)` subscriber to the Rails.event#subscribe
+    # contract, which delivers a Hash event with :name / :payload / :context /
+    # :tags / :source_location.
+    class RailsEventAdapter
+      def initialize(subscriber)
+        @subscriber = subscriber
+      end
+
+      def emit(event)
+        name = event[:name]
+        return unless name&.start_with?(EVENT_PATTERN)
+
+        @subscriber.call(name, event[:payload] || {})
+      end
+    end
+  end
+end

data/lib/standard_circuit/version.rb

@@ -1,3 +1,3 @@
 module StandardCircuit
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/standard_circuit.rb

@@ -9,15 +9,19 @@ require "standard_circuit/adapter_errors/aws"
 require "standard_circuit/adapter_errors/faraday"
 require "standard_circuit/adapter_errors/smtp"
 require "standard_circuit/error_taxonomies"
+require "standard_circuit/event_emitter"
+require "standard_circuit/notifier_bridge"
 require "standard_circuit/notifiers/logger"
 require "standard_circuit/notifiers/sentry"
 require "standard_circuit/notifiers/metrics"
+require "standard_circuit/subscribers"
 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"
+require "standard_circuit/engine" if defined?(::Rails::Engine)
 
 module StandardCircuit
   class Error < StandardError; end
@@ -27,6 +31,7 @@ module StandardCircuit
     def configure
       yield config
       runner.apply_config!(config)
+      subscribers.setup!
       config
     end
 
@@ -38,6 +43,10 @@ module StandardCircuit
       @runner ||= Runner.new
     end
 
+    def subscribers
+      @subscribers ||= Subscribers.new
+    end
+
     def run(name, fallback: nil, &block)
       runner.run(name, fallback: fallback, &block)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_circuit
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -65,6 +65,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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.
@@ -79,6 +121,9 @@ files:
 - README.md
 - Rakefile
 - lib/active_storage/service/standard_circuit_s3_service.rb
+- lib/generators/standard_circuit/install/install_generator.rb
+- lib/generators/standard_circuit/install/templates/health_initializer.rb.tt
+- lib/generators/standard_circuit/install/templates/initializer.rb.tt
 - lib/standard_circuit.rb
 - lib/standard_circuit/active_storage/s3_service.rb
 - lib/standard_circuit/adapter_errors/aws.rb
@@ -87,17 +132,21 @@ files:
 - lib/standard_circuit/adapter_errors/stripe.rb
 - lib/standard_circuit/config.rb
 - lib/standard_circuit/controller_support.rb
+- lib/standard_circuit/engine.rb
 - 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/network_errors.rb
+- lib/standard_circuit/notifier_bridge.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/subscribers.rb
 - lib/standard_circuit/version.rb
 homepage: https://github.com/rarebit-one/standard_circuit
 licenses:
@@ -114,7 +163,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="