standard_circuit 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac355e3881c42900c272ba14d433216f4d8e6019e003e4b5bd52f84545c11c79
-  data.tar.gz: ffdb732b389d5b752deef02d6cdc82fd148af38e3e861d046876cce329e50d36
+  metadata.gz: 335a8efd1db9120747a00cd5b6fc331cb8f31e81b6b391638a6af5877f5c1728
+  data.tar.gz: f23e64bf48c6e5ad494674a68e456b5874aef0800c832841c1251e4f20a74e95
 SHA512:
-  metadata.gz: e2ffa97cfc68660ca8e32bd606df2251700f619f728969ce0e27ed485b6887eb6d8ecd6f1b641a0cea9d22c4842c3a5041a25b00bac97a84c37ea00ca78adf48
-  data.tar.gz: 8f245331cafaeb355b33e0ddd515bb23824713826d908544533959cd1f2dcb6c21d0160887370dadeef566a495d0474f66603095c0e1d93d1275f67c35f9f27d
+  metadata.gz: ec3442f7cf7d4d8efe3ef105fe8f404036691904f95826427fb5838441ff16f4d711e5041e0006f097b3c1c43a8b1426128faae75c4433b483d1a1849103a87f
+  data.tar.gz: d3fd9b73de2eea2a8b68f7863aff6328072ec6963e7f5d93a4654d27a82c856f86d99a6da96dd076e65757d4677fc9131d27246d9a39baf0028a62be74ac0530

data/CHANGELOG.md

@@ -2,8 +2,26 @@
 
 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

data/README.md

@@ -58,6 +58,22 @@ 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.

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

@@ -54,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)
 
@@ -75,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,

data/lib/standard_circuit/config.rb

@@ -22,12 +22,17 @@ 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

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/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/version.rb

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