stoplight 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fba85e77b2b2c6569592f463080da2bca787dc65f12da00bf566b4bb7e56912
-  data.tar.gz: 4aaac27c0747de8a550575ecd8a93cc2391f3a73c008c543ee049db6f7fd01b7
+  metadata.gz: 4b9625eb129c8bbefdab0e3c9552bd6abe6d146c6ffaaab8f25edcb14ddf29db
+  data.tar.gz: db63d134926cceef9e46ed7b0dd72156fa1d55a883f116626a46ee1aaa7af9ff
 SHA512:
-  metadata.gz: acc5305b5da510feacb9584a60a6043eb4c7c7280bbf6f3d6c77db968a445aa45fcfaaaf41027684ff9dc7f4ebf615b1f27e0d53315eda932126b6c47b5ca514
-  data.tar.gz: 1ce0b8d4fea66779d6688c52a871ac10568184f796fc3d51a08c9d6fb45e2402b59da077cbcdd049b1dcdc9e2e748ebdde9ebd327b28aa810190b6bf8d17049c
+  metadata.gz: 7c59ce8f66fdf2871c2998e59adec143ad563e2815f3ebeaf7e8555a5ca39c65062fc0b067067067e1c7541c39db99d3724539eca6e26102abc5fd5f908a2326
+  data.tar.gz: 7c9c7a289d356acfbdbda23f0f28f32d0379999f644e7eae447a9f60b6a6ac05fc73c01af0118f05158802a53eabe449ec03ba5cbdad0de3b2b7148b2b91aa22

data/README.md

@@ -13,10 +13,10 @@ Stoplight is traffic control for code. It's an implementation of the circuit bre
 the documentation of the previous version 4.x, you can find it [here](https://github.com/bolshakov/stoplight/tree/v4.1.1).
 
 Stoplight helps your application gracefully handle failures in external dependencies
-(like flaky databases, unreliable APIs, or spotty web services). By wrapping these unreliable 
+(like flaky databases, unreliable APIs, or spotty web services). By wrapping these unreliable
 calls, Stoplight prevents cascading failures from affecting your entire application.
 
-**The best part?** Stoplight works with zero configuration out of the box, while offering deep customization when you 
+**The best part?** Stoplight works with zero configuration out of the box, while offering deep customization when you
 need it.
 
 ## Installation
@@ -41,10 +41,10 @@ Stoplight operates like a traffic light with three states:
 
 ```mermaid
 stateDiagram
-    Green --> Red: Failures reach threshold
+    Green --> Red: Errors reach threshold
     Red --> Yellow: After cool_off_time
-    Yellow --> Green: Successful attempt
-    Yellow --> Red: Failed attempt
+    Yellow --> Green: Successful recovery
+    Yellow --> Red: Failed recovery
     Green --> Green: Success
     
     classDef greenState fill:#28a745,stroke:#1e7e34,stroke-width:2px,color:#fff
@@ -60,11 +60,15 @@ stateDiagram
 - **Red**: Failure state. Fast-fails without running the code. (Circuit open)
 - **Yellow**: Recovery state. Allows a test execution to see if the problem is resolved. (Circuit half-open)
 
-Stoplight's behavior is controlled by three primary parameters:
+Stoplight's behavior is controlled by two main parameters:
 
-1. **Threshold** (default: `3`): Number of failures required to transition from green to red.
-2. **Cool Off Time** (default: `60` seconds): Time to wait in the red state before transitioning to yellow.
-3. **Window Size** (default: `nil`): Time window in which failures are counted toward the threshold. By default, all failures are counted.
+1. **Window Size** (default: `nil`): Time window in which errors are counted toward the threshold. By default, all errors are counted.
+2. **Threshold** (default: `3`): Number of errors required to transition from green to red.
+
+Additionally, two other parameters control how Stoplight behaves after it turns red:
+ 
+1. **Cool Off Time** (default: `60` seconds): Time to wait in the red state before transitioning to yellow.
+2. **Recovery Threshold** (default: `1`): Number of successful attempts required to transition from yellow back to green.
 
 ## Basic Usage
 
@@ -78,7 +82,7 @@ light = Stoplight("Payment Service")
 result = light.run { payment_gateway.process(order) }
 ```
 
-When everything works, the light stays green and your code runs normally. If the code fails repeatedly, the 
+When everything works, the light stays green and your code runs normally. If the code fails repeatedly, the
 light turns red and raises a `Stoplight::Error::RedLight` exception to prevent further calls.
 
 ```ruby
@@ -112,7 +116,7 @@ light.color #=> "green"
 
 ### Using Fallbacks
 
-Provide fallbacks to gracefully handle failures:
+Provide fallbacks to gracefully handle errors:
 
 ```ruby
 fallback = ->(error) { error ? "Failed: #{error.message}" : "Service unavailable" }
@@ -121,7 +125,7 @@ light = Stoplight('example-fallback')
 result = light.run(fallback) { external_service.call }
 ```
 
-If the light is green but the call fails, the fallback receives the `error`. If the light is red, the fallback 
+If the light is green but the call fails, the fallback receives the `error`. If the light is red, the fallback
 receives `nil`. In both cases, the return value of the fallback becomes the return value of the `run` method.
 
 ## Admin Panel
@@ -172,8 +176,7 @@ docker run --net=host bolshakov/stoplight-admin
 docker run -e REDIS_URL=redis://localhost:6378  --net=host bolshakov/stoplight-admin
 ```
 
-
-## Configuration 
+## Configuration
 
 ### Global Configuration
 
@@ -182,9 +185,11 @@ Stoplight allows you to set default values for all lights in your application:
 ```ruby
 Stoplight.configure do |config|
   # Set default behavior for all stoplights
-  config.threshold = 5
+  config.traffic_control = :error_rate
+  config.window_size = 300
+  config.threshold = 0.5
   config.cool_off_time = 30
-  config.window_size = 60
+  config.recovery_threshold = 5
   
   # Set up default data store and notifiers
   config.data_store = Stoplight::DataStore::Redis.new(redis)
@@ -209,10 +214,11 @@ You can also provide settings during creation:
 ```ruby
 data_store = Stoplight::DataStore::Redis.new(Redis.new)
 
-light = Stoplight("Payment Service", 
-  threshold: 5,                           # 5 failures before turning red
+light = Stoplight("Payment Service",
+  window_size: 300,                       # Only count errors in the last five minutes
+  threshold: 5,                           # 5 errors before turning red
   cool_off_time: 60,                      # Wait 60 seconds before attempting recovery
-  window_size: 300,                       # Only count failures in the last five minutes
+  recovery_threshold: 1,                  # 1 successful attempt to turn green again
   data_store: data_store,                 # Use Redis for persistence
   tracked_errors: [TimeoutError],         # Only count TimeoutError
   skipped_errors: [ValidationError]       # Ignore ValidationError
@@ -233,7 +239,7 @@ users_api = base_api.with(
 )
 ```
 
-The `#with` method creates a new stoplight instance without modifying the original, making it ideal for creating 
+The `#with` method creates a new stoplight instance without modifying the original, making it ideal for creating
 specialized stoplights from a common configuration.
 
 ## Error Handling
@@ -259,6 +265,117 @@ When both methods are used, `skipped_errors` takes precedence over `tracked_erro
 
 ## Advanced Configuration
 
+### Traffic Control Strategies
+
+You've seen how Stoplight transitions from green to red when errors reach the threshold. But **how exactly does it 
+decide when that threshold is reached?** That's where traffic control strategies come in.
+
+Stoplight offers two built-in strategies for counting errors:
+
+#### Consecutive Errors (Default)
+
+Stops traffic when a specified number of consecutive errors occur. Works with or without time sliding windows.
+
+```ruby
+light = Stoplight(
+  "Payment API", 
+  traffic_control: :consecutive_errors, 
+  threshold: 5,
+)
+```
+
+Counts consecutive errors regardless of when they occurred. Once 5 consecutive errors happen, the stoplight 
+turns red and stops traffic.
+
+```ruby
+light = Stoplight(
+  "Payment API", 
+  traffic_control: :consecutive_errors, 
+  threshold: 5, 
+  window_size: 300,
+)
+```
+
+Counts consecutive errors within a 5-minute sliding window. Both conditions must be met: 5 consecutive errors 
+AND at least 5 total errors within the window.
+
+_This is Stoplight's default strategy when no `traffic_control` is specified._ You can omit `traffic_control` parameter 
+in the above examples:
+
+```ruby
+light = Stoplight(
+  "Payment API",
+  threshold: 5,
+)
+```
+
+#### Error Rate
+
+Stops traffic when the error rate exceeds a percentage within a sliding time window. Requires `window_size` to be 
+configured:
+
+
+```ruby
+light = Stoplight(
+  "Payment API", 
+  traffic_control: :error_rate, 
+  window_size: 300, 
+  threshold: 0.5,
+)
+```
+
+Monitors error rate over a 5-minute sliding window. The stoplight turns red when error rate exceeds 50%.
+
+```ruby
+light = Stoplight(
+  "Payment API", 
+  traffic_control: {
+    error_rate: { min_requests: 20 },
+  }, 
+  window_size: 300, 
+  threshold: 0.5,
+)
+```
+
+Only evaluates error rate after at least 20 requests within the window. Default `min_requests` is 10.
+
+
+#### When to use:
+
+* **Consecutive Errors**: Low-medium traffic, simple behavior, occasional spikes expected
+* **Error Rate**: High traffic, percentage-based SLAs, variable traffic patterns
+
+### Traffic Recovery Strategies
+
+In the yellow state, Stoplight behaves differently from normal (green) operation. Instead of
+blocking all traffic, it allows a limited number of real requests to pass through to
+the underlying service to determine if it has recovered. These aren't synthetic probes -
+they're actual user requests that will execute normally if the service is healthy.
+
+After collecting the necessary data from these requests, Stoplight decides whether to
+return to green or red state.
+
+Traffic Recovery strategies control how Stoplight evaluates these requests during
+the recovery phase.
+
+#### Consecutive Successes (Default)
+
+Returns to green after a specified number of consecutive successful recovery attempts. This is the default behavior.
+
+```ruby
+light = Stoplight(
+  "Payment API", 
+  traffic_recovery: :consecutive_successes, 
+  recovery_threshold: 3,
+)
+```
+
+This configuration requires 3 consecutive successful recovery probes before resuming normal traffic. If any probe 
+fails during recovery, the stoplight immediately returns to red and waits for another cool-off period before trying again.
+
+**Default behavior**: If no `recovery_threshold` is specified, Stoplight uses a conservative default of 1, meaning a 
+single successful recovery probe will resume traffic flow.
+
 ### Data Store
 
 Stoplight uses an in-memory data store out of the box:
@@ -284,7 +401,7 @@ end
 
 #### Connection Pooling with Redis
 
-For high-traffic applications or when you want to control a number of opened connections to Redis: 
+For high-traffic applications or when you want to control a number of opened connections to Redis:
 
 ```ruby
 require "connection_pool"
@@ -329,7 +446,7 @@ the [notifier interface documentation] for detailed instructions. Pull requests
 
 ### Error Notifiers
 
-Stoplight is built for resilience. If the Redis data store fails, Stoplight automatically falls back to the in-memory 
+Stoplight is built for resilience. If the Redis data store fails, Stoplight automatically falls back to the in-memory
 data store. To get notified about such errors, you can configure an error notifier:
 
 ```ruby
@@ -340,7 +457,7 @@ end
 
 ### Locking
 
-Sometimes you need to override Stoplight's automatic behavior. Locking allows you to manually control the state of 
+Sometimes you need to override Stoplight's automatic behavior. Locking allows you to manually control the state of
 a stoplight, which is useful for:
 
 * **Maintenance periods**: Lock to red when a service is known to be unavailable
@@ -424,7 +541,7 @@ stoplight = Stoplight("test-#{rand}")
 ## Maintenance Policy
 
 Stoplight supports the latest three minor versions of Ruby, which currently are: `3.2.x`, `3.3.x`, and `3.4.x`. Changing
-the minimum supported Ruby version is not considered a breaking change. We support the current stable Redis 
+the minimum supported Ruby version is not considered a breaking change. We support the current stable Redis
 version (`7.4.x`) and the latest release of the previous major version (`6.2.x`)
 
 ## Development

data/lib/stoplight/admin.rb

@@ -25,7 +25,7 @@ module Stoplight
     helpers Helpers
 
     set :protection, except: %i[json_csrf]
-    set :data_store, proc { Stoplight.config_provider.data_store }
+    set :data_store, proc { Stoplight.default_config.data_store }
     set :views, File.join(__dir__, "admin", "views")
 
     get "/" do

data/lib/stoplight/config/compatibility_result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Config
+    # The +CompatibilityResult+ class represents the result of a compatibility check
+    # for a strategy. It provides methods to determine if the strategy is compatible
+    # and to retrieve error messages when it is not.
+    class CompatibilityResult
+      class << self
+        # Creates a new +CompatibilityResult+ instance representing a compatible strategy.
+        #
+        # @return [CompatibilityResult] An instance with no errors.
+        def compatible
+          new(errors: [])
+        end
+
+        # Creates a new +CompatibilityResult+ instance representing an incompatible strategy.
+        #
+        # @param errors [Array<String>] List of error messages indicating incompatibility.
+        # @return [CompatibilityResult] An instance with the provided errors.
+        def incompatible(*errors)
+          new(errors:)
+        end
+      end
+
+      # Initializes a new `CompatibilityResult` instance.
+      # @param errors [Array<String>] List of error messages if the strategy is not compatible.
+      def initialize(errors: [])
+        @errors = errors.freeze
+      end
+
+      # Checks if the strategy is compatible.
+      # @return [Boolean] `true` if there are no errors, `false` otherwise.
+      def compatible?
+        @errors.empty?
+      end
+
+      def incompatible? = !compatible?
+
+      # Retrieves the list of error messages.
+      # @return [Array<String>] The list of error messages.
+      attr_reader :errors
+
+      # Retrieves a concatenated error message string.
+      # @return [String, nil] A string containing all error messages joined by "; ",
+      #   or `nil` if the strategy is compatible.
+      def error_messages
+        unless compatible?
+          @errors.join("; ")
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/config/dsl.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Config
+    # This is a DSL for configuring Stoplight settings. It is responsible for
+    # transforming the provided settings into a format that can be used by Stoplight.
+    #
+    # @api private
+    class DSL
+      def transform(settings)
+        if settings.has_key?(:data_store)
+          settings[:data_store] = build_data_store(settings[:data_store])
+        end
+
+        if settings.has_key?(:notifiers)
+          settings[:notifiers] = build_notifiers(settings[:notifiers])
+        end
+
+        if settings.has_key?(:tracked_errors)
+          settings[:tracked_errors] = build_tracked_errors(settings[:tracked_errors])
+        end
+
+        if settings.has_key?(:skipped_errors)
+          settings[:skipped_errors] = build_skipped_errors(settings[:skipped_errors])
+        end
+
+        if settings.has_key?(:cool_off_time)
+          settings[:cool_off_time] = build_cool_off_time(settings[:cool_off_time])
+        end
+
+        if settings.has_key?(:traffic_control)
+          settings[:traffic_control] = build_traffic_control(settings[:traffic_control])
+        end
+
+        if settings.has_key?(:traffic_recovery)
+          settings[:traffic_recovery] = build_traffic_recovery(settings[:traffic_recovery])
+        end
+        settings
+      end
+
+      private
+
+      def build_data_store(data_store)
+        DataStore::FailSafe.wrap(data_store)
+      end
+
+      def build_notifiers(notifiers)
+        notifiers.map { |notifier| Notifier::FailSafe.wrap(notifier) }
+      end
+
+      def build_tracked_errors(tracked_error)
+        Array(tracked_error)
+      end
+
+      def build_skipped_errors(skipped_errors)
+        Array(skipped_errors)
+      end
+
+      def build_cool_off_time(cool_off_time)
+        cool_off_time.to_i
+      end
+
+      def build_traffic_control(traffic_control)
+        case traffic_control
+        in Stoplight::TrafficControl::Base
+          traffic_control
+        in :consecutive_errors
+          Stoplight::TrafficControl::ConsecutiveErrors.new
+        in :error_rate
+          Stoplight::TrafficControl::ErrorRate.new
+        in {error_rate: error_rate_settings}
+          Stoplight::TrafficControl::ErrorRate.new(**error_rate_settings)
+        else
+          raise Error::ConfigurationError, <<~ERROR
+            unsupported traffic_control strategy provided (`#{traffic_control}`). Supported options:
+              * Stoplight::TrafficControl::ConsecutiveErrors
+              * Stoplight::TrafficControl::ErrorRate
+          ERROR
+        end
+      end
+
+      def build_traffic_recovery(traffic_recovery)
+        case traffic_recovery
+        in Stoplight::TrafficRecovery::Base
+          traffic_recovery
+        in :consecutive_successes
+          Stoplight::TrafficRecovery::ConsecutiveSuccesses.new
+        else
+          raise Error::ConfigurationError, <<~ERROR
+            unsupported traffic_recovery strategy provided (`#{traffic_recovery}`). Supported options:
+              * Stoplight::TrafficRecovery::ConsecutiveSuccesses
+          ERROR
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/config/library_default_config.rb

@@ -4,26 +4,18 @@ module Stoplight
   module Config
     # Provides default settings for the Stoplight library.
     # @api private
-    class LibraryDefaultConfig
-      DEFAULT_SETTINGS = {
-        cool_off_time: Stoplight::Default::COOL_OFF_TIME,
-        data_store: Stoplight::Default::DATA_STORE,
-        error_notifier: Stoplight::Default::ERROR_NOTIFIER,
-        notifiers: Stoplight::Default::NOTIFIERS,
-        threshold: Stoplight::Default::THRESHOLD,
-        window_size: Stoplight::Default::WINDOW_SIZE,
-        tracked_errors: Stoplight::Default::TRACKED_ERRORS,
-        skipped_errors: Stoplight::Default::SKIPPED_ERRORS,
-        traffic_control: Stoplight::Default::TRAFFIC_CONTROL,
-        traffic_recovery: Stoplight::Default::TRAFFIC_RECOVERY
-      }.freeze
-      private_constant :DEFAULT_SETTINGS
-
-      # Returns library default settings.
-      # @return [Hash]
-      def to_h
-        DEFAULT_SETTINGS
-      end
-    end
+    LibraryDefaultConfig = Light::Config.empty.with(
+      cool_off_time: Stoplight::Default::COOL_OFF_TIME,
+      data_store: Stoplight::Default::DATA_STORE,
+      error_notifier: Stoplight::Default::ERROR_NOTIFIER,
+      notifiers: Stoplight::Default::NOTIFIERS,
+      threshold: Stoplight::Default::THRESHOLD,
+      recovery_threshold: Stoplight::Default::RECOVERY_THRESHOLD,
+      window_size: Stoplight::Default::WINDOW_SIZE,
+      tracked_errors: Stoplight::Default::TRACKED_ERRORS,
+      skipped_errors: Stoplight::Default::SKIPPED_ERRORS,
+      traffic_control: Stoplight::Default::TRAFFIC_CONTROL,
+      traffic_recovery: Stoplight::Default::TRAFFIC_RECOVERY
+    )
   end
 end

data/lib/stoplight/config/system_config.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Config
+    SystemConfig = LibraryDefaultConfig
+  end
+end

data/lib/stoplight/config/user_default_config.rb

@@ -25,9 +25,13 @@ module Stoplight
       attr_accessor :notifiers
 
       # @!attribute [w] threshold
-      #   @return [Integer, nil] The default failure threshold to trip the circuit breaker.
+      #   @return [Integer, Float, nil] The default failure threshold to trip the circuit breaker.
       attr_writer :threshold
 
+      # @!attribute [w] recovery_threshold
+      #  @return [Integer, nil] The default recovery threshold for the circuit breaker.
+      attr_writer :recovery_threshold
+
       # @!attribute [w] window_size
       #   @return [Integer, nil] The default size of the rolling window for failure tracking.
       attr_writer :window_size
@@ -44,6 +48,10 @@ module Stoplight
       #   @return [Stoplight::DataStore::Base] The default data store instance.
       attr_writer :data_store
 
+      # @!attribute [w] traffic_control
+      #   @return [Stoplight::TrafficControl::Base, Symbol, Hash] The traffic control strategy.
+      attr_writer :traffic_control
+
       def initialize
         # This allows users appending notifiers to the default list,
         # while still allowing them to override the default list.
@@ -61,9 +69,11 @@ module Stoplight
           error_notifier: @error_notifier,
           notifiers: @notifiers,
           threshold: @threshold,
+          recovery_threshold: @recovery_threshold,
           window_size: @window_size,
           tracked_errors: @tracked_errors,
-          skipped_errors: @skipped_errors
+          skipped_errors: @skipped_errors,
+          traffic_control: @traffic_control
         }.compact
       end
 

data/lib/stoplight/data_store/fail_safe.rb

@@ -33,6 +33,12 @@ module Stoplight
       # @param data_store [Stoplight::DataStore::Base]
       def initialize(data_store)
         @data_store = data_store
+        @circuit_breaker = Stoplight(
+          "stoplight:data_store:fail_safe:#{data_store.class.name}",
+          data_store: Default::DATA_STORE,
+          traffic_control: TrafficControl::ConsecutiveErrors.new,
+          threshold: Default::THRESHOLD
+        )
       end
 
       def names
@@ -98,10 +104,9 @@ module Stoplight
         circuit_breaker.run(fallback, &code)
       end
 
-      # @!attribute [r] circuit_breaker
-      #   @return [Stoplight] The circuit breaker used to handle failures.
+      # @return [Stoplight::Light] The circuit breaker used to handle failures.
       private def circuit_breaker
-        @circuit_breaker ||= Stoplight("stoplight:data_store:fail_safe:#{data_store.class.name}", data_store: Default::DATA_STORE)
+        @circuit_breaker ||= Stoplight.system_light("stoplight:data_store:fail_safe:#{data_store.class.name}")
       end
     end
   end

data/lib/stoplight/data_store/memory.rb

@@ -202,6 +202,11 @@ module Stoplight
         state
       end
 
+      # @return [String]
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
       # Combined method that performs the state transition based on color
       #
       # @param config [Stoplight::Light::Config] The light configuration

data/lib/stoplight/data_store/redis.rb

@@ -228,6 +228,10 @@ module Stoplight
         state
       end
 
+      def inspect
+        "#<#{self.class.name} redis=#{@redis.inspect}>"
+      end
+
       # Combined method that performs the state transition based on color
       #
       # @param config [Stoplight::Light::Config] The light configuration

data/lib/stoplight/default.rb

@@ -17,13 +17,14 @@ module Stoplight
     NOTIFIERS = [Notifier::IO.new($stderr)].freeze
 
     THRESHOLD = 3
+    RECOVERY_THRESHOLD = 1
 
     WINDOW_SIZE = nil
 
     TRACKED_ERRORS = [StandardError].freeze
     SKIPPED_ERRORS = [].freeze
 
-    TRAFFIC_CONTROL = TrafficControl::ConsecutiveFailures.new
-    TRAFFIC_RECOVERY = TrafficRecovery::SingleSuccess.new
+    TRAFFIC_CONTROL = TrafficControl::ConsecutiveErrors.new
+    TRAFFIC_RECOVERY = TrafficRecovery::ConsecutiveSuccesses.new
   end
 end

data/lib/stoplight/light/config.rb

@@ -44,12 +44,21 @@ module Stoplight
       :error_notifier,
       :notifiers,
       :threshold,
+      :recovery_threshold,
       :window_size,
       :tracked_errors,
       :skipped_errors,
       :traffic_control,
       :traffic_recovery
     ) do
+      class << self
+        # Creates a new NULL configuration object.
+        # @return [Stoplight::Light::Config]
+        def empty
+          new(**members.map { |key| [key, nil] }.to_h)
+        end
+      end
+
       # Checks if the given error should be tracked
       #
       # @param error [#==] The error to check, e.g. an Exception, Class or Proc
@@ -60,6 +69,43 @@ module Stoplight
 
         !skip && track
       end
+
+      # This method applies configuration dsl and revalidates the configuration
+      # @return [Stoplight::Light::Config]
+      def with(**settings)
+        super(**CONFIG_DSL.transform(settings)).then do |config|
+          config.validate_config!
+        end
+      end
+
+      # @raise [Stoplight::Error::ConfigurationError]
+      # @return [Stoplight::Light::Config] The validated configuration object.
+      def validate_config!
+        validate_traffic_control_compatibility!
+        self
+      end
+
+      private
+
+      def validate_traffic_control_compatibility!
+        traffic_control.check_compatibility(self).then do |compatibility_result|
+          if compatibility_result.incompatible?
+            raise Stoplight::Error::ConfigurationError.new(
+              "#{traffic_control.class.name} strategy is incompatible with the Stoplight configuration: #{compatibility_result.error_messages}"
+            )
+          end
+        end
+      end
+
+      def validate_traffic_recovery_compatibility!
+        traffic_recovery.check_compatibility(self).then do |compatibility_result|
+          if compatibility_result.incompatible?
+            raise Stoplight::Error::ConfigurationError.new(
+              "#{traffic_control.class.name} strategy is incompatible with the Stoplight configuration: #{compatibility_result.error_messages}"
+            )
+          end
+        end
+      end
     end
   end
 end

data/lib/stoplight/light.rb

@@ -150,9 +150,7 @@ module Stoplight
     #   payment_light.run(->(error) { nil }) { call_payment_api }
     # @see +Stoplight()+
     def with(**settings)
-      reconfigure(
-        Stoplight.config_provider.from_prototype(config, settings)
-      )
+      reconfigure(config.with(**settings))
     end
 
     private

data/lib/stoplight/metadata.rb

@@ -67,5 +67,21 @@ module Stoplight
         Color::GREEN
       end
     end
+
+    # Calculates the error rate based on the number of successes and errors.
+    #
+    # @return [Float]
+    def error_rate
+      if successes.nil? || errors.nil? || (successes + errors).zero?
+        0.0
+      else
+        errors.fdiv(successes + errors)
+      end
+    end
+
+    # @return [Integer]
+    def requests
+      successes + errors
+    end
   end
 end

data/lib/stoplight/notifier/fail_safe.rb

@@ -58,9 +58,12 @@ module Stoplight
         other.is_a?(FailSafe) && notifier == other.notifier
       end
 
-      # @return [Stoplight] The circuit breaker used to handle failures.
+      # @return [Stoplight::Light] The circuit breaker used to handle failures.
       private def circuit_breaker
-        @circuit_breaker ||= Stoplight("stoplight:notifier:fail_safe:#{notifier.class.name}", data_store: Default::DATA_STORE, notifiers: [])
+        @circuit_breaker ||= Stoplight.system_light(
+          "stoplight:notifier:fail_safe:#{notifier.class.name}",
+          notifiers: []
+        )
       end
     end
   end

data/lib/stoplight/traffic_control/base.rb

@@ -9,6 +9,14 @@ module Stoplight
     #
     # @example Creating a custom strategy
     #   class ErrorRateStrategy < Stoplight::TrafficControl::Base
+    #     def check_compatibility(config)
+    #       if config.window_size.nil?
+    #         incompatible("`window_size` should be set")
+    #       else
+    #         compatible
+    #       end
+    #     end
+    #
     #     def stop_traffic?(config, metadata)
     #       total = metadata.successes + metadata.failures
     #       return false if total < 10 # Minimum sample size
@@ -21,6 +29,16 @@ module Stoplight
     # @abstract
     # @api private
     class Base
+      # Checks if the strategy is compatible with the given Stoplight configuration.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Config::CompatibilityResult]
+      # :nocov:
+      def check_compatibility(config)
+        raise NotImplementedError
+      end
+      # :nocov:
+
       # Determines whether traffic should be stopped based on the Stoplight's
       # current state and metrics.
       #
@@ -36,6 +54,17 @@ module Stoplight
       def ==(other)
         other.is_a?(self.class)
       end
+
+      # Returns a compatibility result indicating the strategy is compatible.
+      #
+      # @return [Stoplight::Config::CompatibilityResult] A compatible result.
+      private def compatible = Config::CompatibilityResult.compatible
+
+      # Returns a compatibility result indicating the strategy is incompatible.
+      #
+      # @param errors [Array<String>] The list of error messages describing incompatibility.
+      # @return [Stoplight::Config::CompatibilityResult] An incompatible result.
+      private def incompatible(*errors) = Config::CompatibilityResult.incompatible(*errors)
     end
   end
 end

data/lib/stoplight/traffic_control/{consecutive_failures.rb → consecutive_errors.rb}

@@ -14,18 +14,30 @@ module Stoplight
     #    reach the threshold.
     #
     # @example With window-based configuration
-    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: 60)
-    #   strategy = Stoplight::TrafficControlStrategy::ConsecutiveFailures.new
+    #   traffic_control = Stoplight::TrafficControlStrategy::ConsecutiveErrors.new
+    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: 60, traffic_control:)
     #
     # Will switch to red if 5 consecutive failures occur within the 60-second window
     #
     # @example With total number of consecutive failures configuration
-    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: nil)
-    #   strategy = Stoplight::TrafficControlStrategy::ConsecutiveFailures.new
+    #   traffic_control = Stoplight::TrafficControlStrategy::ConsecutiveErrors.new
+    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: nil, traffic_control:)
     #
     # Will switch to red only if 5 consecutive failures occur regardless of the time window
     # @api private
-    class ConsecutiveFailures < Base
+    class ConsecutiveErrors < Base
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Config::CompatibilityResult]
+      def check_compatibility(config)
+        if config.threshold <= 0
+          incompatible("`threshold` should be bigger than 0")
+        elsif !config.threshold.is_a?(Integer)
+          incompatible("`threshold` should be an integer")
+        else
+          compatible
+        end
+      end
+
       # Determines if traffic should be stopped based on failure counts.
       #
       # @param config [Stoplight::Light::Config]

data/lib/stoplight/traffic_control/error_rate.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module TrafficControl
+    # A strategy that stops the traffic based on error rate.
+    #
+    # @example
+    #   traffic_control = Stoplight::TrafficControlStrategy::ErrorRate.new
+    #   config = Stoplight::Light::Config.new(threshold: 0.6, window_size: 300, traffic_control:)
+    #
+    # Will switch to red if 60% error rate reached within the 5-minute (300 seconds) sliding window.
+    # By default this traffic control strategy starts evaluating only after 10 requests have been made. You can
+    # adjust this by passing a different value for `min_requests` when initializing the strategy.
+    #
+    #   traffic_control = Stoplight::TrafficControlStrategy::ErrorRate.new(min_requests: 100)
+    #
+    # @api private
+    class ErrorRate < Base
+      # @!attribute min_requests
+      #   @return [Integer]
+      attr_reader :min_requests
+
+      # @param min_requests [Integer] Minimum number of requests before traffic control is applied.
+      #   until this number of requests is reached, the error rate will not be considered.
+      def initialize(min_requests: 10)
+        @min_requests = min_requests
+      end
+
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Config::CompatibilityResult]
+      def check_compatibility(config)
+        if config.window_size.nil?
+          incompatible("`window_size` should be set")
+        elsif config.threshold < 0 || config.threshold > 1
+          incompatible("`threshold` should be between 0 and 1")
+        else
+          compatible
+        end
+      end
+
+      # @param config [Stoplight::Light::Config]
+      # @param metadata [Stoplight::Metadata]
+      # @return [Boolean]
+      def stop_traffic?(config, metadata)
+        metadata.requests >= min_requests && metadata.error_rate >= config.threshold
+      end
+    end
+  end
+end

data/lib/stoplight/traffic_recovery/base.rb

@@ -34,6 +34,16 @@ module Stoplight
     # @abstract
     # @api private
     class Base
+      # Checks if the strategy is compatible with the given Stoplight configuration.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Config::CompatibilityResult]
+      # :nocov:
+      def check_compatibility(config)
+        raise NotImplementedError
+      end
+      # :nocov:
+
       # Determines the appropriate recovery state based on the Stoplight's
       # current metrics and recovery progress.
       #
@@ -46,6 +56,23 @@ module Stoplight
       def determine_color(config, metadata)
         raise NotImplementedError
       end
+
+      # @param other [any]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class)
+      end
+
+      # Returns a compatibility result indicating the strategy is compatible.
+      #
+      # @return [Stoplight::Config::CompatibilityResult] A compatible result.
+      private def compatible = Config::CompatibilityResult.compatible
+
+      # Returns a compatibility result indicating the strategy is incompatible.
+      #
+      # @param errors [Array<String>] The list of error messages describing incompatibility.
+      # @return [Stoplight::Config::CompatibilityResult] An incompatible result.
+      private def incompatible(*errors) = Config::CompatibilityResult.incompatible(*errors)
     end
   end
 end

data/lib/stoplight/traffic_recovery/consecutive_successes.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module TrafficRecovery
+    # A conservative strategy that requires multiple consecutive successful probes
+    # before resuming traffic flow.
+    #
+    # The strategy immediately returns to RED state if any failure occurs during
+    # the recovery process, ensuring that only truly stable services resume
+    # full traffic flow.
+    #
+    # @example Basic usage with 3 consecutive successes required
+    #   config = Stoplight::Light::Config.new(
+    #     cool_off_time: 60,
+    #     recovery_threshold: 3
+    #   )
+    #   strategy = Stoplight::TrafficRecovery::ConsecutiveSuccesses.new
+    #
+    # Recovery behavior:
+    # - After cool-off period, Stoplight enters YELLOW (recovery) state
+    # - Requires 3 consecutive successful probes to transition to GREEN
+    # - Any failure during recovery immediately returns to RED state
+    # - Process repeats after another cool-off period
+    #
+    # Configuration requirements:
+    # - `recovery_threshold`: Integer > 0, specifies required consecutive successes
+    #
+    # Failure behavior:
+    # Unlike some circuit breaker implementations that tolerate occasional failures
+    # during recovery, this strategy takes a zero-tolerance approach: any failure
+    # during the recovery phase immediately transitions back to RED state. This
+    # conservative approach prioritizes stability over recovery speed.
+    #
+    # @api private
+    class ConsecutiveSuccesses < Base
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Config::CompatibilityResult]
+      def check_compatibility(config)
+        if config.recovery_threshold <= 0
+          incompatible("`recovery_threshold` should be bigger than 0")
+        elsif !config.recovery_threshold.is_a?(Integer)
+          incompatible("`recovery_threshold` should be an integer")
+        else
+          compatible
+        end
+      end
+
+      # Determines if traffic should be resumed based on successes counts.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @param metadata [Stoplight::Metadata]
+      # @return [String]
+      def determine_color(config, metadata)
+        recovery_started_at = metadata.recovery_started_at || metadata.recovery_scheduled_after
+
+        if metadata.last_error_at && metadata.last_error_at >= recovery_started_at
+          Color::RED
+        elsif [metadata.consecutive_successes, metadata.recovery_probe_successes].min >= config.recovery_threshold
+          Color::GREEN
+        else
+          Color::YELLOW
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stoplight
-  VERSION = Gem::Version.new("5.1.0")
+  VERSION = Gem::Version.new("5.2.0")
 end

data/lib/stoplight.rb

@@ -3,7 +3,7 @@
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("io" => "IO")
+loader.inflector.inflect("io" => "IO", "dsl" => "DSL")
 loader.do_not_eager_load(
   "#{__dir__}/stoplight/data_store",
   "#{__dir__}/stoplight/admin",
@@ -14,6 +14,9 @@ loader.ignore("#{__dir__}/stoplight/rspec.rb", "#{__dir__}/stoplight/rspec")
 loader.setup
 
 module Stoplight # rubocop:disable Style/Documentation
+  CONFIG_DSL = Config::DSL.new
+  private_constant :CONFIG_DSL
+
   CONFIG_MUTEX = Mutex.new
   private_constant :CONFIG_MUTEX
 
@@ -47,7 +50,7 @@ module Stoplight # rubocop:disable Style/Documentation
     #   produces a warning:
     #
     #     "Stoplight reconfigured. Existing circuit breakers will not see the new configuration. New
-    #       configuration: #<Stoplight::Config::ConfigProvider cool_off_time=32, threshold=3, window_size=94, tracked_errors=StandardError, skipped_errors=NoMemoryError,ScriptError,SecurityError,SignalException,SystemExit,SystemStackError, data_store=Stoplight::DataStore::Memory>\n"
+    #       configuration: ...f
     #
     #   If you really know what you are doing, you can pass the +trust_me_im_an_engineer+ parameter as +true+ to
     #   suppress this warning, which could be useful in test environments.
@@ -56,28 +59,47 @@ module Stoplight # rubocop:disable Style/Documentation
       user_defaults = Config::UserDefaultConfig.new
       yield(user_defaults) if block_given?
 
-      reconfigured = !@config_provider.nil?
+      reconfigured = !@default_config.nil?
 
-      @config_provider = Config::ConfigProvider.new(
-        user_default_config: user_defaults.freeze,
-        library_default_config: Config::LibraryDefaultConfig.new
-      ).tap do
+      @default_config = Config::LibraryDefaultConfig.with(**user_defaults.to_h).tap do
         if reconfigured && !trust_me_im_an_engineer
           warn(
             "Stoplight reconfigured. Existing circuit breakers will not see new configuration. " \
-              "New configuration: #{@config_provider.inspect}"
+              "New configuration: #{@default_config.inspect}"
           )
         end
       end
     end
 
+    # Creates a Light for internal use.
+    #
+    # @param name [String]
+    # @param settings [Hash]
+    # @return [Stoplight::Light]
+    # @api private
+    def system_light(name, **settings)
+      config = Config::SystemConfig.with(name:, **settings)
+      Stoplight::Light.new(config)
+    end
+
+    # Create a Light with the user default configuration.
+    #
+    # @param name [String]
+    # @param settings [Hash]
+    # @return [Stoplight::Light]
+    # @api private
+    def light(name, **settings)
+      config = Stoplight.default_config.with(name:, **settings)
+      Stoplight::Light.new(config)
+    end
+
     # Retrieves the current configuration provider.
     #
-    # @return [Stoplight::Config::ConfigProvider]
+    # @return [Stoplight::Light::Config]
     # @api private
-    def config_provider
+    def default_config
       CONFIG_MUTEX.synchronize do
-        @config_provider ||= configure
+        @default_config ||= configure
       end
     end
   end
@@ -95,6 +117,8 @@ end
 #   @option settings [Numeric] :window_size The size of the rolling window for failure tracking.
 #   @option settings [Array<StandardError>] :tracked_errors A list of errors to track.
 #   @option settings [Array<Exception>] :skipped_errors A list of errors to skip.
+#   @option settings [Stoplight::TrafficControl::Base, Symbol, {Symbol, Hash{Symbol, any}}] :traffic_control The
+#     traffic control strategy to use.
 #
 # @return [Stoplight::Light] A new circuit breaker instance.
 # @raise [ArgumentError] If an unknown option is provided in the settings.
@@ -118,7 +142,14 @@ end
 # @example configure skipped errors
 #   light = Stoplight("Payment API", skipped_errors: [ActiveRecord::RecordNotFound])
 #
+# @example configure traffic control to trip using consecutive failures method
+#   # When 5 consecutive failures occur, the circuit breaker will trip.
+#   light = Stoplight("Payment API", traffic_control: :consecutive_errors, threshold: 5)
+#
+# @example configure traffic control to trip using error rate method
+#   # When 66.6% error rate reached withing a sliding 5 minute window, the circuit breaker will trip.
+#   light = Stoplight("Payment API", traffic_control: :error_rate, threshold: 0.666, window_size: 300)
+#
 def Stoplight(name, **settings) # rubocop:disable Naming/MethodName
-  config = Stoplight.config_provider.provide(name, settings)
-  Stoplight::Light.new(config)
+  Stoplight.light(name, **settings)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Cameron Desautels
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-27 00:00:00.000000000 Z
+date: 2025-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -59,8 +59,10 @@ files:
 - lib/stoplight/admin/views/index.erb
 - lib/stoplight/admin/views/layout.erb
 - lib/stoplight/color.rb
-- lib/stoplight/config/config_provider.rb
+- lib/stoplight/config/compatibility_result.rb
+- lib/stoplight/config/dsl.rb
 - lib/stoplight/config/library_default_config.rb
+- lib/stoplight/config/system_config.rb
 - lib/stoplight/config/user_default_config.rb
 - lib/stoplight/data_store.rb
 - lib/stoplight/data_store/base.rb
@@ -94,9 +96,10 @@ files:
 - lib/stoplight/rspec/generic_notifier.rb
 - lib/stoplight/state.rb
 - lib/stoplight/traffic_control/base.rb
-- lib/stoplight/traffic_control/consecutive_failures.rb
+- lib/stoplight/traffic_control/consecutive_errors.rb
+- lib/stoplight/traffic_control/error_rate.rb
 - lib/stoplight/traffic_recovery/base.rb
-- lib/stoplight/traffic_recovery/single_success.rb
+- lib/stoplight/traffic_recovery/consecutive_successes.rb
 - lib/stoplight/version.rb
 homepage: https://github.com/bolshakov/stoplight
 licenses:

data/lib/stoplight/config/config_provider.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Config
-    # Provides configuration for a Stoplight light by its name.
-    #
-    # It combines settings from three sources in the following order of precedence:
-    # 1. **Settings Overrides**: Explicit settings passed as arguments to +#provide+ method.
-    # 2. **User-level Default Settings**: Settings defined using the +Stoplight.configure+ method.
-    # 4. **Library-Level Default Settings**: Default settings defined in the +Stoplight::Config::UserDefaultConfig+ module.
-    #
-    # The settings are merged in this order, with higher-precedence settings overriding lower-precedence ones.
-    # After merging settings, the configuration transformations are applied such as wrapping data stores and notifiers
-    # with fail-safe mechanism, type conversion, etc. Each transformation must be idempotent.
-    #
-    # @api private
-    class ConfigProvider
-      # @!attribute [r] default_settings
-      #   @return [Hash]
-      private attr_reader :default_settings
-
-      # @param user_default_config [Stoplight::Config::UserDefaultConfig]
-      # @param library_default_config [Stoplight::Config::LibraryDefaultConfig]
-      # @raise [Error::ConfigurationError] if both user_default_config and legacy_config are not empty
-      def initialize(user_default_config:, library_default_config:)
-        @default_settings = library_default_config.to_h.merge(
-          user_default_config.to_h
-        )
-      end
-
-      # @return [Stoplight::DataStore::Base]
-      def data_store
-        default_settings.fetch(:data_store)
-      end
-
-      # Returns a configuration for a specific light with the given name and settings overrides.
-      #
-      # @param light_name [Symbol, String] The name of the light.
-      # @param settings_overrides [Hash] The settings to override.
-      #   @see +Stoplight()+
-      # @return [Stoplight::Light::Config] The configuration for the specified light.
-      # @raise [Error::ConfigurationError]
-      def provide(light_name, settings_overrides = {})
-        raise Error::ConfigurationError, <<~ERROR if settings_overrides.has_key?(:name)
-          The +name+ setting cannot be overridden in the configuration.
-        ERROR
-
-        settings = default_settings.merge(settings_overrides, {name: light_name})
-        Light::Config.new(**transform_settings(settings))
-      end
-
-      # Creates a configuration from a given +Stoplight::Light::Config+ object extending it
-      # with additional settings overrides.
-      #
-      # @param config [Stoplight::Light::Config] The configuration object to extend.
-      # @param settings_overrides [Hash] The settings to override.
-      # @return [Stoplight::Light::Config] The new extended configuration object.
-      def from_prototype(config, settings_overrides)
-        config.to_h.then do |settings|
-          current_name = settings.delete(:name)
-          name = settings_overrides.delete(:name) || current_name
-
-          provide(name, **settings.merge(settings_overrides))
-        end
-      end
-
-      def inspect
-        "#<#{self.class.name} " \
-          "cool_off_time=#{default_settings[:cool_off_time]}, " \
-          "threshold=#{default_settings[:threshold]}, " \
-          "window_size=#{default_settings[:window_size]}, " \
-          "tracked_errors=#{default_settings[:tracked_errors].join(",")}, " \
-          "skipped_errors=#{default_settings[:skipped_errors].join(",")}, " \
-          "data_store=#{default_settings[:data_store].class.name}" \
-        ">"
-      end
-
-      private
-
-      def transform_settings(settings)
-        settings.merge(
-          data_store: build_data_store(settings.fetch(:data_store)),
-          notifiers: build_notifiers(settings.fetch(:notifiers)),
-          tracked_errors: build_tracked_errors(settings.fetch(:tracked_errors)),
-          skipped_errors: build_skipped_errors(settings.fetch(:skipped_errors)),
-          cool_off_time: build_cool_off_time(settings.fetch(:cool_off_time))
-        )
-      end
-
-      def build_data_store(data_store)
-        DataStore::FailSafe.wrap(data_store)
-      end
-
-      def build_notifiers(notifiers)
-        notifiers.map { |notifier| Notifier::FailSafe.wrap(notifier) }
-      end
-
-      def build_tracked_errors(tracked_error)
-        Array(tracked_error)
-      end
-
-      def build_skipped_errors(skipped_errors)
-        Array(skipped_errors)
-      end
-
-      def build_cool_off_time(cool_off_time)
-        cool_off_time.to_i
-      end
-    end
-  end
-end

data/lib/stoplight/traffic_recovery/single_success.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficRecovery
-    # A basic strategy that recovers traffic flow after a successful recovery probe.
-    #
-    # This strategy allows traffic to resume when a single successful probe
-    # occurs after the Stoplight has been in red state. It's a simple "one success and we're back"
-    # approach.
-    #
-    # @example Basic usage
-    #   config = Stoplight::Light::Config.new(cool_off_time: 60)
-    #   strategy = Stoplight::TrafficRecovery::SingleSuccess.new
-    #
-    # After the Stoplight turns red:
-    # - The Stoplight will wait for the cool-off period (60 seconds)
-    # - Then enter the recovery phase (YELLOW color)
-    # - The first successful probe will resume normal traffic flow (green color)
-    # @api private
-    class SingleSuccess < Base
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [String]
-      def determine_color(config, metadata)
-        recovery_started_at = metadata.recovery_started_at || metadata.recovery_scheduled_after
-        last_success_at = metadata.last_success_at
-        if last_success_at && recovery_started_at <= last_success_at
-          Color::GREEN
-        else
-          Color::RED
-        end
-      end
-    end
-  end
-end