standard_circuit 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8a58ef94e0f296c0e3b107fda1decfc29037324942c5326ec2fcfd1fdf19f2f
-  data.tar.gz: b3a78ae40f5a60c0e9754011eca3174ec4d489f61e51d41f81a6eb5a7efeb946
+  metadata.gz: 335a8efd1db9120747a00cd5b6fc331cb8f31e81b6b391638a6af5877f5c1728
+  data.tar.gz: f23e64bf48c6e5ad494674a68e456b5874aef0800c832841c1251e4f20a74e95
 SHA512:
-  metadata.gz: c9e4a015cf36e76ff7bece785930be035b323e4306897538750d5641237b0c34a931ba69f72aeb568456202b1472657d9e44c628967bbcd0bf2d240727c34a9b
-  data.tar.gz: 37a2b60ddb1488905ab5a01652ca41fd5f5452e55f689168041edb3dd46235503c31c23e92d51b154d86f1faaae3755aa506b05c15aef6f9e77a7463fff02ce3
+  metadata.gz: ec3442f7cf7d4d8efe3ef105fe8f404036691904f95826427fb5838441ff16f4d711e5041e0006f097b3c1c43a8b1426128faae75c4433b483d1a1849103a87f
+  data.tar.gz: d3fd9b73de2eea2a8b68f7863aff6328072ec6963e7f5d93a4654d27a82c856f86d99a6da96dd076e65757d4677fc9131d27246d9a39baf0028a62be74ac0530

data/CHANGELOG.md

@@ -2,8 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-24
+
+Two behaviour changes — both are bug fixes, but both change numbers or breaker behaviour you may be alerting on.
+
+### Fixed
+- **Circuit-open requests were counted twice in `<metric_prefix>.request`.** `Runner` already emits `<metric_prefix>.request{status: circuit_open}` when a call is rejected by a tripped or forced-open circuit; `ControllerSupport#handle_circuit_open` then emitted the same metric again when the `Stoplight::Error::RedLight` reached a controller. The controller-side emission (and the private `emit_circuit_open_metric` helper) is removed; fallback dispatch is unchanged. **Behaviour change:** `circuit_open` request counts for rejections that reach a controller drop by half, back to the true value — dashboards and alert thresholds tuned against the doubled number should be revisited.
+- **S3 caller errors tripped the S3 breaker.** `ErrorTaxonomies::Aws.tracked` includes `Aws::Errors::ServiceError`, which is the superclass of `Aws::S3::Errors::AccessDenied` and `NoSuchKey` as well as of the dynamically generated 5xx errors, so a burst of missing-key lookups or permission errors opened the circuit. New `ErrorTaxonomies.default_skipped_for(tracked)` returns the AWS caller errors whenever the tracked list covers them, and `register` / `register_prefix` now use it as the default `skipped_errors`. **Behaviour change:** AWS circuits registered without `skipped_errors:` no longer count `AccessDenied` / `NoSuchKey` toward the threshold; 5xx (`ServiceUnavailable` etc.) and `Seahorse::Client::NetworkingError` still trip. An explicit `skipped_errors:` — including `[]` — always wins, and circuits for other adapters keep defaulting to `[]`.
+
+### Added
+- Specs for `NetworkErrors` and the Stripe / AWS / Faraday / SMTP `AdapterErrors` modules.
+- README section on error taxonomies and the AWS `skipped_errors` default; the initializer template notes it too.
+
+### Documentation
+- **Consumer list corrected in `CLAUDE.md`: this gem has five consumers, not four.** `sidekick-web` was missing. The same entry also claimed the `workspace-os` → `jumpdrive-web` directory rename "was deferred" and pointed at `~/Workspace/rarebit-one/workspace-os`; that rename completed 2026-07-14 and the old husk is gone, so an agent following the note was looking in a directory that no longer exists. Verified against the canonical matrix in the workspace's `rollout-gem/SKILL.md`, which the new advisory `check-gem-family-drift.sh` now diffs this list against on every sweep.
+
+## [0.3.0] - 2026-07-30
+
+### Added
+- `config.sentry_criticality_levels` — opt in to criticality-aware Sentry reporting for the built-in Sentry subscriber. Accepts `true` (the recommended map `{ critical: :error, standard: :warning, optional: :info }`), a partial Hash merged over that map, or `nil` / `false` for the previous flat behaviour. In criticality-aware mode a circuit-open report also gains `circuit` / `circuit_criticality` tags and a stable `["circuit-open", <circuit>]` fingerprint, so Sentry alert rules can page on `circuit_criticality:critical` and group one issue per breaker. Invalid criticalities and non-symbolizable levels raise `ArgumentError` at configure time rather than failing silently at alert time.
+
+  **This is opt-in, and deliberately not the new default.** Both the level and the fingerprint feed Sentry's alerting and issue grouping, so flipping the map on at gem-upgrade time would silently re-page and re-group live issues in apps that never asked for it. Apps that leave `sentry_criticality_levels` unset get the 0.2.x report byte-for-byte — same `:warning` level, same message, no tags, no fingerprint. Host apps that hand-rolled this by setting `sentry_enabled = false` and registering their own alerter can now delete that class and set `sentry_enabled = true` + `sentry_criticality_levels = true` instead.
+- `isolate_namespace StandardCircuit` on the engine, bringing it in line with every other engine gem in the family. Verified non-breaking for the aggregate health route every consumer draws (`get "/health", to: "standard_circuit/health#show"`): that path is resolved by the *application's* route set through constant lookup, which isolation does not touch, and the new `spec/integration/health_route_boot_spec.rb` boots a real Rails app and requests the route end to end so a regression fails here rather than in a consumer after release. Safe specifically because this engine is library-only — no `config/routes.rb` for the isolated `default_scope` to scope, and no ActiveRecord models for the `standard_circuit_` `table_name_prefix` to apply to.
+
+  One consequence to know about: `StandardCircuit::HealthController` now picks up the engine's (empty) url helpers instead of the application's, so app path helpers used inside it — or inside a host subclass of it — need a `main_app.` prefix. The gem's controller only renders JSON, so nothing in-gem is affected.
+- README section on `data_store`, previously undocumented. Spells out that the `Stoplight::DataStore::Memory` default is **per-process** — thresholds count per worker, `/health` reports the serving process's view, and `force_open` / `reset!` are process-local — plus the shared-store alternative for apps that want cross-process state.
+- README section on Sentry reporting covering `sentry_enabled`, the new `sentry_criticality_levels` opt-in, and the "subscribe yourself" escape hatch.
+
+### Changed
+- The install generator now warns that the aggregate `get "/health", to: "standard_circuit/health#show"` route must be drawn **before** `mount StandardHealth::Engine => "/health"`. `StandardHealth::Engine` registers sub-paths only (`/alive`, `/ready`, `/diagnostics/env`) and never serves the aggregate tier itself, so an app that mounts it and assumes `/health` is covered silently has no aggregate tier — with no boot error and no failing route spec to reveal it. The warning appears in the initializer template, in the `--with-health-endpoint` health initializer next to the route line, and in the hint the generator prints. Same note added to the README's health-endpoint section.
+- `.github/workflows/ci.yml` follows the shared reusable workflow at `@v2` again, matching the rest of the gem family. The previous SHA pin carried a stale rationale: it claimed to restore pre-`rarebit-one/.github#14` job names for branch protection, but `main`'s protection now requires the *post*-#14 names (`ci / lint`, `ci / test-matrix (4.0.x)`) and the pinned revision's `reusable-gem-ci.yml` is byte-identical to `@v2` — so it was neither restoring old names nor changing any check name. It did honour `extra-lint-commands`, so the brakeman / bundler-audit gate was live throughout.
+
 ## [0.2.0] - 2026-04-28
 
 ### Added

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
+
+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

@@ -58,6 +58,64 @@ StandardCircuit.run(:stripe) do
 end
 ```
 
+## 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`, and `Faraday`; `StandardCircuit::AdapterErrors::<Adapter>.caller_errors` lists the adapter's caller-side (4xx-style) errors.
+
+When `skipped_errors:` is omitted it defaults to `[]` — except when the tracked list covers the AWS caller errors. AWS 5xx responses are dynamically generated `Aws::Errors::ServiceError` subclasses, so `ErrorTaxonomies::Aws.tracked` has to track `ServiceError` itself, which is also the superclass of `Aws::S3::Errors::AccessDenied` and `NoSuchKey`. So for such circuits `skipped_errors` defaults to `AdapterErrors::Aws.caller_errors` (via `ErrorTaxonomies.default_skipped_for`), and a burst of missing-key lookups or permission errors no longer trips the S3 breaker:
+
+```ruby
+StandardCircuit.configure do |c|
+  # skipped_errors defaults to [Aws::S3::Errors::NoSuchKey, Aws::S3::Errors::AccessDenied]
+  c.register_prefix(:s3, tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked)
+
+  # An explicit skipped_errors — even [] — always wins over the default.
+  # c.register(:s3_strict, tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked, skipped_errors: [])
+end
+```
+
+## Circuit state storage (`data_store`)
+
+Circuit state (failure counts, colors, locks) lives in a Stoplight data store. StandardCircuit defaults to `Stoplight::DataStore::Memory.new`, which is **per-process**: each Puma worker, Sidekiq/SolidQueue worker, and console gets its own independent view of every circuit.
+
+That is the deliberate default for a Redis-free deployment, and it is usually the right one — a circuit exists to stop *this* process from hammering a dead upstream, and per-process thresholds mean one unlucky worker can't trip the breaker for everyone. But be explicit about what it implies:
+
+- Thresholds are counted per process, so an app with 4 web workers tolerates roughly 4× the configured `threshold` in aggregate before every worker has tripped.
+- `/health` reports the circuit colors of **the process that served the request**, so two consecutive probes can legitimately disagree while a circuit is tripping.
+- `force_open` / `force_closed` and `reset!` affect only the calling process — they are test and console tools, not an operational kill switch.
+
+Point `data_store` at a shared store if you want cross-process state instead:
+
+```ruby
+StandardCircuit.configure do |c|
+  # Default — per-process, no external dependency.
+  c.data_store = Stoplight::DataStore::Memory.new
+
+  # Shared across processes and hosts (requires the redis gem + a Redis server).
+  # c.data_store = Stoplight::DataStore::Redis.new(Redis.new(url: ENV["REDIS_URL"]))
+end
+```
+
+## Sentry reporting
+
+The built-in Sentry subscriber is on by default (`c.sentry_enabled = true`) and reports every circuit-open transition at a flat `:warning`, with the circuit name, colors, and error in `extra`.
+
+Set `sentry_criticality_levels` to derive the level from the circuit's registered `criticality` instead. That also adds `circuit` / `circuit_criticality` tags and a stable `["circuit-open", <circuit>]` fingerprint, so Sentry alert rules can route on criticality (e.g. page on `circuit_criticality:critical`) and group per circuit:
+
+```ruby
+StandardCircuit.configure do |c|
+  # { critical: :error, standard: :warning, optional: :info }
+  c.sentry_criticality_levels = true
+
+  # Or override part of that map — unlisted criticalities keep the default.
+  # c.sentry_criticality_levels = { optional: :debug }
+end
+```
+
+This is **opt-in, not the default**. Both the level and the fingerprint feed Sentry's alerting and issue grouping, so turning it on for existing apps at gem-upgrade time would silently change what pages and re-group open issues. Leaving `sentry_criticality_levels` unset keeps the flat `:warning` shape byte-for-byte.
+
+If you want something else entirely, set `c.sentry_enabled = false` and subscribe to `standard_circuit.circuit.opened` yourself — the payload carries `criticality`.
+
 ## 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.
@@ -147,7 +205,14 @@ 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.
+**If your app also mounts `StandardHealth::Engine` at `/health`, draw the aggregate route first:**
+
+```ruby
+get "/health", to: "standard_circuit/health#show"        # aggregate — FIRST
+mount StandardHealth::Engine => "/health", as: :standard_health
+```
+
+`StandardHealth::Engine` registers sub-paths only (`/alive`, `/ready`, `/diagnostics/env`) — it never serves the aggregate tier itself. An app that mounts the engine and assumes `/health` is covered silently has no aggregate tier at all, with no boot error and no failing route spec to reveal it. The ordering is load-bearing; draw the aggregate route explicitly, first.
 
 ## License
 

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

@@ -67,6 +67,12 @@ module StandardCircuit
         say ""
         say '  get "/health", to: "standard_circuit/health#show"'
         say ""
+        say "If you also mount StandardHealth::Engine at \"/health\", draw the"
+        say "line above BEFORE the mount. That engine serves sub-paths only"
+        say "(/alive, /ready, /diagnostics/env), never the aggregate tier — so"
+        say "an app that mounts it and assumes \"/health\" is covered silently has"
+        say "no aggregate tier, with no boot error to warn you."
+        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

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

@@ -6,6 +6,18 @@
 #
 #   get "/health", to: "standard_circuit/health#show"
 #
+# ORDERING IS LOAD-BEARING: if your app also mounts StandardHealth::Engine at
+# "/health", draw this aggregate route BEFORE the mount —
+#
+#   get "/health", to: "standard_circuit/health#show"        # aggregate — FIRST
+#   mount StandardHealth::Engine => "/health", as: :standard_health
+#
+# StandardHealth::Engine registers sub-paths only ("/alive", "/ready",
+# "/diagnostics/env") — it never serves the aggregate tier itself. So an app
+# that mounts the engine and assumes "/health" is covered has no aggregate tier
+# at all, and nothing says so: no boot error, and no failing route spec unless
+# one already exists. Draw this route explicitly, first.
+#
 # 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.

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

@@ -17,6 +17,17 @@ StandardCircuit.configure do |config|
   # Default: true
   # config.sentry_enabled = true
 
+  # Report circuit-open events at a Sentry level chosen from the circuit's
+  # criticality, and add `circuit` / `circuit_criticality` tags plus a stable
+  # ["circuit-open", <circuit>] fingerprint so Sentry alert rules can route and
+  # group by circuit. Opt-in: leaving this unset keeps the flat :warning
+  # reporting (no tags, no fingerprint) that earlier versions used.
+  #   true  -> { critical: :error, standard: :warning, optional: :info }
+  #   Hash  -> the above, merged with your overrides
+  # Default: nil (flat :warning)
+  # config.sentry_criticality_levels = true
+  # config.sentry_criticality_levels = { optional: :debug }
+
   # Prefix used for emitted metrics (e.g. "<prefix>.circuit_breaker",
   # "<prefix>.request"). Default: "external"
   # config.metric_prefix = "external"
@@ -43,7 +54,10 @@ StandardCircuit.configure do |config|
   #   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)
+  #                     without counting — typically caller/validation errors;
+  #                     default: [], or the AWS caller errors (NoSuchKey,
+  #                     AccessDenied) when tracked_errors covers them — see
+  #                     StandardCircuit::ErrorTaxonomies.default_skipped_for)
   #   criticality     — :critical | :standard | :optional
   #                     (affects health rollup; default: :standard)
 
@@ -64,6 +78,8 @@ StandardCircuit.configure do |config|
   # Use `register_prefix` to dynamically name circuits matching a pattern.
   # The first matching prefix wins; the circuit name is "<prefix>_<suffix>".
 
+  # AWS caller errors (NoSuchKey, AccessDenied) are skipped by default here,
+  # so missing keys and permission errors don't trip the S3 breaker.
   # config.register_prefix(:s3,
   #   threshold: 10,
   #   tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked,
@@ -80,4 +96,14 @@ StandardCircuit.configure do |config|
   # contract as the built-in subscribers.
 
   # config.add_notifier(->(name, payload) { MyTracer.record(name, payload) })
+
+  # ---------------------------------------------------------------------------
+  # Health endpoint (see --with-health-endpoint)
+  # ---------------------------------------------------------------------------
+  # The aggregate route is `get "/health", to: "standard_circuit/health#show"`.
+  # If your app also mounts StandardHealth::Engine at "/health", draw the
+  # aggregate route BEFORE the mount. That engine registers sub-paths only
+  # ("/alive", "/ready", "/diagnostics/env") and never serves the aggregate tier
+  # itself, so an app that mounts it and assumes "/health" is covered silently
+  # has no aggregate tier — no boot error, no failing route spec.
 end

data/lib/standard_circuit/config.rb

@@ -22,22 +22,28 @@ module StandardCircuit
             "invalid criticality #{criticality.inspect}; must be one of #{CRITICALITIES.inspect}"
         end
 
+        tracked_errors = opts.fetch(:tracked_errors, NetworkErrors.defaults)
+
         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, []),
+          tracked_errors: tracked_errors,
+          # An explicit `skipped_errors:` (including `[]`) always wins; the
+          # default only kicks in when the key is absent. See
+          # ErrorTaxonomies.default_skipped_for for why AWS needs one.
+          skipped_errors: opts.fetch(:skipped_errors) { ErrorTaxonomies.default_skipped_for(tracked_errors) },
           criticality: criticality
         )
       end
     end
 
     attr_accessor :sentry_enabled, :metric_prefix, :data_store, :logger
-    attr_reader :circuits, :prefixes, :extra_notifiers
+    attr_reader :circuits, :prefixes, :extra_notifiers, :sentry_criticality_levels
 
     def initialize
       @sentry_enabled = true
+      @sentry_criticality_levels = nil
       @metric_prefix = "external"
       @data_store = Stoplight::DataStore::Memory.new
       @logger = nil
@@ -46,6 +52,22 @@ module StandardCircuit
       @extra_notifiers = []
     end
 
+    # Opt in to criticality-aware Sentry reporting for the built-in Sentry
+    # subscriber. Accepts:
+    #
+    #   nil / false  — (default) flat :warning for every circuit, no tags and
+    #                  no fingerprint. The 0.2.x behaviour.
+    #   true         — Notifiers::Sentry::DEFAULT_LEVELS
+    #                  ({ critical: :error, standard: :warning, optional: :info })
+    #   Hash         — DEFAULT_LEVELS merged with the given criticality => level
+    #                  pairs, so a partial map is enough.
+    #
+    # Stored normalized: the reader returns either nil or a frozen, complete
+    # criticality => level Hash.
+    def sentry_criticality_levels=(value)
+      @sentry_criticality_levels = normalize_sentry_criticality_levels(value)
+    end
+
     def reset_registry!
       @circuits.clear
       @prefixes.clear
@@ -90,6 +112,39 @@ module StandardCircuit
 
     private
 
+    def normalize_sentry_criticality_levels(value)
+      case value
+      when nil, false then nil
+      when true       then Notifiers::Sentry::DEFAULT_LEVELS
+      when Hash       then merge_sentry_criticality_levels(value)
+      else
+        raise ArgumentError,
+          "sentry_criticality_levels must be nil, true, false, or a Hash of " \
+          "criticality => Sentry level; got #{value.class}"
+      end
+    end
+
+    def merge_sentry_criticality_levels(map)
+      normalized = map.to_h do |criticality, level|
+        # Check symbolizability before coercing: a key like 42 would otherwise
+        # raise NoMethodError instead of the ArgumentError this setter promises.
+        criticality = criticality.to_sym if criticality.respond_to?(:to_sym)
+        unless CRITICALITIES.include?(criticality)
+          raise ArgumentError,
+            "invalid criticality #{criticality.inspect} in sentry_criticality_levels; " \
+            "must be one of #{CRITICALITIES.inspect}"
+        end
+        unless level.respond_to?(:to_sym)
+          raise ArgumentError,
+            "invalid Sentry level #{level.inspect} for criticality #{criticality.inspect}; " \
+            "must be a Symbol or String"
+        end
+        [ criticality, level.to_sym ]
+      end
+
+      Notifiers::Sentry::DEFAULT_LEVELS.merge(normalized).freeze
+    end
+
     def spec_for_prefix(name)
       key = name.to_s
       _matched_prefix, spec = @prefixes.find { |prefix, _| key.start_with?("#{prefix}_") }

data/lib/standard_circuit/controller_support.rb

@@ -47,9 +47,10 @@ module StandardCircuit
 
     private
 
-    def handle_circuit_open(error)
+    def handle_circuit_open(_error)
+      # No metric here: Runner already counted this rejection as
+      # `<metric_prefix>.request{status: circuit_open}` before re-raising.
       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]
@@ -61,14 +62,5 @@ module StandardCircuit
     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/engine.rb

@@ -9,6 +9,26 @@ module StandardCircuit
   # 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
+    # Brings StandardCircuit in line with the other engine gems in the family.
+    # Safe here specifically because this engine is library-only:
+    #
+    # * No `config/routes.rb`, so the `default_scope` isolate_namespace applies
+    #   to the engine's own route set has nothing to scope.
+    # * No ActiveRecord models, so the `standard_circuit_` table_name_prefix it
+    #   defines on the StandardCircuit module applies to nothing.
+    # * The host-drawn route the convention prescribes —
+    #   `get "/health", to: "standard_circuit/health#show"` — resolves through
+    #   the *application's* route set by constant lookup, which isolation does
+    #   not touch. Verified by booting a real Rails app both ways (see
+    #   spec/integration/health_route_boot_spec.rb, which fails if this ever
+    #   regresses).
+    #
+    # One real consequence: `StandardCircuit::HealthController` now picks up the
+    # engine's (empty) url_helpers instead of the application's, so app path
+    # helpers inside it — or inside a host subclass of it — need a `main_app.`
+    # prefix. The controller only renders JSON, so nothing in-gem is affected.
+    isolate_namespace StandardCircuit
+
     initializer "standard_circuit.subscribers", after: :load_config_initializers do
       StandardCircuit.subscribers.setup!
     end

data/lib/standard_circuit/error_taxonomies.rb

@@ -16,6 +16,24 @@ module StandardCircuit
   # `AdapterErrors::*` because the right `skipped_errors` set is usually
   # app-specific and a shared taxonomy would over-skip.
   module ErrorTaxonomies
+    # Default `skipped_errors` for a circuit registered without an explicit
+    # `skipped_errors:`. Most adapters default to `[]`, but AWS can't: its 5xx
+    # errors are dynamically generated `Aws::Errors::ServiceError` subclasses
+    # (e.g. `Aws::S3::Errors::ServiceUnavailable`), so `Aws.tracked` has to
+    # track `ServiceError` itself — which is also the superclass of caller
+    # errors like `AccessDenied` and `NoSuchKey`. Without a skip list, a burst
+    # of missing-key lookups or permission errors would trip the S3 breaker.
+    #
+    # Returns the AWS caller errors that some entry of +tracked+ covers (is the
+    # same class or an ancestor of), or `[]` when none are covered. Returns a
+    # fresh array each call.
+    def self.default_skipped_for(tracked)
+      trackable = Array(tracked).grep(Module)
+      AdapterErrors::Aws.caller_errors.select do |caller_error|
+        trackable.any? { |klass| caller_error <= klass }
+      end
+    end
+
     module Stripe
       def self.tracked
         NetworkErrors.defaults + AdapterErrors::Stripe.server_errors

data/lib/standard_circuit/notifiers/sentry.rb

@@ -1,27 +1,88 @@
 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.
+    # Subscribes to standard_circuit.circuit.opened and forwards a message to
+    # Sentry. Other transitions are ignored — only RED matters for alerting.
+    #
+    # Two reporting shapes:
+    #
+    # * **Flat** (default, and the only 0.2.x behaviour): every circuit reports
+    #   at `:warning` with the circuit's colors and error in `extra`. No tags,
+    #   no fingerprint.
+    # * **Criticality-aware** (opt in via `config.sentry_criticality_levels`):
+    #   the level is chosen from the circuit's registered criticality, and the
+    #   report gains `circuit` / `circuit_criticality` tags plus a stable
+    #   `["circuit-open", circuit]` fingerprint so Sentry alert rules can route
+    #   and group by circuit.
+    #
+    # Flat stays the default deliberately. Both the level and the fingerprint
+    # feed Sentry's alerting and grouping, so a gem bump must not silently
+    # re-page or re-group a host app's existing issues — see CHANGELOG.
     class Sentry
+      OPENED_EVENT = "standard_circuit.circuit.opened".freeze
+
+      # Level used in flat mode, and the fallback for an unrecognised
+      # criticality in criticality-aware mode.
+      DEFAULT_LEVEL = :warning
+
+      # The recommended criticality -> Sentry level mapping, used when
+      # `config.sentry_criticality_levels = true`. :critical is loud enough to
+      # page; :optional stays informational so a flapping nice-to-have
+      # upstream doesn't cry wolf.
+      DEFAULT_LEVELS = {
+        critical: :error,
+        standard: :warning,
+        optional: :info
+      }.freeze
+
+      # @param levels [Hash{Symbol=>Symbol}, nil] criticality -> level map.
+      #   nil (the default) selects flat :warning reporting.
+      def initialize(levels: nil)
+        @levels = levels
+      end
+
       def call(event_name, payload)
-        return unless event_name == "standard_circuit.circuit.opened"
+        return unless event_name == OPENED_EVENT
         return unless defined?(::Sentry) && ::Sentry.respond_to?(:capture_message)
 
+        @levels ? capture_criticality_aware(payload) : capture_flat(payload)
+      end
+
+      private
+
+      def capture_flat(payload)
         message = "Circuit breaker opened: #{payload[:circuit]}"
         ::Sentry.capture_message(
           message,
-          level: :warning,
-          extra: {
-            circuit: payload[:circuit],
-            from_color: payload[:from_color],
-            to_color: payload[:to_color],
-            error_class: payload[:error_class],
-            error_message: payload[:error_message]
-          }.compact
+          level: DEFAULT_LEVEL,
+          extra: base_extra(payload)
         )
         message
       end
+
+      def capture_criticality_aware(payload)
+        circuit = payload[:circuit].to_s
+        criticality = (payload[:criticality] || Config::DEFAULT_CRITICALITY).to_sym
+        message = "Circuit breaker opened: #{circuit} (#{criticality})"
+
+        ::Sentry.capture_message(
+          message,
+          level: @levels.fetch(criticality, DEFAULT_LEVEL),
+          tags: { circuit: circuit, circuit_criticality: criticality.to_s },
+          fingerprint: [ "circuit-open", circuit ],
+          extra: base_extra(payload).merge(circuit: circuit, criticality: criticality)
+        )
+        message
+      end
+
+      def base_extra(payload)
+        {
+          circuit: payload[:circuit],
+          from_color: payload[:from_color],
+          to_color: payload[:to_color],
+          error_class: payload[:error_class],
+          error_message: payload[:error_message]
+        }.compact
+      end
     end
   end
 end

data/lib/standard_circuit/subscribers.rb

@@ -72,7 +72,7 @@ module StandardCircuit
     def internal_subscribers
       config = StandardCircuit.config
       list = [ Notifiers::Logger.new(config.logger) ]
-      list << Notifiers::Sentry.new if config.sentry_enabled
+      list << Notifiers::Sentry.new(levels: config.sentry_criticality_levels) if config.sentry_enabled
       list << Notifiers::Metrics.new(metric_prefix: config.metric_prefix)
       list
     end

data/lib/standard_circuit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_circuit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -117,7 +117,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - lib/active_storage/service/standard_circuit_s3_service.rb

data/MIT-LICENSE

@@ -1,21 +0,0 @@
-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.