stoplight 5.0.3 → 5.2.0

data/lib/stoplight/config/user_default_config.rb

@@ -20,14 +20,18 @@ module Stoplight
       #   @return [Proc, nil] The default error notifier (callable object).
       attr_writer :error_notifier
 
-      # @!attribute [r] notifiers
+      # @!attribute [rw] notifiers
       #   @return [Array<Stoplight::Notifier::Base>] The default list of notifiers.
-      attr_reader :notifiers
+      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
@@ -40,24 +44,20 @@ module Stoplight
       #   @return [Array<Class>, nil] The default list of errors to skip.
       attr_writer :skipped_errors
 
+      # @!attribute [w] data_store
+      #   @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.
         @notifiers = Default::NOTIFIERS
       end
 
-      # @param value [Stoplight::DataStore::Base]
-      # @return [Stoplight::DataStore::Base] The default data store instance.
-      def data_store=(value)
-        @data_store = DataStore::FailSafe.wrap(value)
-      end
-
-      # @param value [Array<Stoplight::Notifier::Base>]
-      # @return [Array<Stoplight::Notifier::FailSafe>]
-      def notifiers=(value)
-        @notifiers = value.map { |notifier| Notifier::FailSafe.wrap(notifier) }
-      end
-
       # Converts the user-defined configuration to a hash.
       #
       # @return [Hash] A hash representation of the configuration, excluding nil values.
@@ -67,11 +67,13 @@ module Stoplight
           cool_off_time: @cool_off_time,
           data_store: @data_store,
           error_notifier: @error_notifier,
-          notifiers: (@notifiers == Default::NOTIFIERS) ? nil : @notifiers, # This is to avoid conflicts with legacy config
+          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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Stoplight
   module DataStore
     # A wrapper around a data store that provides fail-safe mechanisms using a
@@ -31,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
@@ -96,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

@@ -14,18 +14,17 @@ module Stoplight
       words.join(" ")
     end
 
-    NOTIFIERS = [
-      Notifier::FailSafe.wrap(Notifier::IO.new($stderr))
-    ].freeze
+    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

@@ -3,85 +3,65 @@
 module Stoplight
   class Light
     # A +Stoplight::Light+ configuration object.
+    #
+    # # @!attribute [r] name
+    #   @return [String]
+    #
+    # @!attribute [r] cool_off_time
+    #   @return [Numeric]
+    #
+    # @!attribute [r] data_store
+    #   @return [Stoplight::DataStore::Base]
+    #
+    # @!attribute [r] error_notifier
+    #   @return [StandardError => void]
+    #
+    # @!attribute [r] notifiers
+    #   @return [Array<Stoplight::Notifier::Base>]
+    #
+    # @!attribute [r] threshold
+    #   @return [Numeric]
+    #
+    # @!attribute [r] window_size
+    #   @return [Numeric]
+    #
+    # @!attribute [r] tracked_errors
+    #   @return [Array<StandardError>]
+    #
+    # @!attribute [r] skipped_errors
+    #  @return [Array<Exception>]
+    #
+    # @!attribute [r] traffic_control
+    #  @return [Stoplight::TrafficControl::Base]
+    #
+    # @!attribute [r] traffic_recovery
+    #   @return [Stoplight::TrafficRecovery::Base]
     # @api private
-    class Config
-      # @!attribute [r] name
-      #   @return [String]
-      attr_reader :name
-
-      # @!attribute [r] cool_off_time
-      #   @return [Numeric]
-      attr_reader :cool_off_time
-
-      # @!attribute [r] data_store
-      #   @return [Stoplight::DataStore::Base]
-      attr_reader :data_store
-
-      # @!attribute [r] error_notifier
-      #   @return [StandardError => void]
-      attr_reader :error_notifier
-
-      # @!attribute [r] notifiers
-      #   @return [Array<Stoplight::Notifier::Base>]
-      attr_reader :notifiers
-
-      # @!attribute [r] threshold
-      #   @return [Numeric]
-      attr_reader :threshold
-
-      # @!attribute [r] window_size
-      #   @return [Numeric]
-      attr_reader :window_size
-
-      # @!attribute [r] tracked_errors
-      #   @return [Array<StandardError>]
-      attr_reader :tracked_errors
-
-      # @!attribute [r] skipped_errors
-      #  @return [Array<Exception>]
-      attr_reader :skipped_errors
-
-      # @!attribute [r] traffic_control
-      #  @return [Stoplight::TrafficControl::Base]
-      attr_reader :traffic_control
-
-      # @!attribute [r] traffic_recovery
-      #   @return [Stoplight::TrafficRecovery::Base]
-      attr_reader :traffic_recovery
-
-      # @param name [String]
-      # @param cool_off_time [Numeric]
-      # @param data_store [Stoplight::DataStore::Base]
-      # @param error_notifier [Proc]
-      # @param notifiers [Array<Stoplight::Notifier::Base>]
-      # @param threshold [Numeric]
-      # @param window_size [Numeric]
-      # @param tracked_errors [Array<StandardError>]
-      # @param skipped_errors [Array<Exception>]
-      # @param traffic_control [Stoplight::TrafficControl::Base]
-      # @param traffic_recovery [Stoplight::TrafficRecovery::Base]
-      def initialize(name:, cool_off_time:, data_store:, error_notifier:, notifiers:, threshold:, window_size:,
-        tracked_errors:, skipped_errors:, traffic_control:, traffic_recovery:)
-        @name = name
-        @cool_off_time = cool_off_time.to_i
-        @data_store = DataStore::FailSafe.wrap(data_store)
-        @error_notifier = error_notifier
-        @notifiers = notifiers.map { |notifier| Notifier::FailSafe.wrap(notifier) }
-        @threshold = threshold
-        @window_size = window_size
-        @tracked_errors = Array(tracked_errors)
-        @skipped_errors = Array(skipped_errors)
-        @traffic_control = traffic_control
-        @traffic_recovery = traffic_recovery
+    Config = Data.define(
+      :name,
+      :cool_off_time,
+      :data_store,
+      :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
 
-      # @param other [any]
-      # @return [Boolean]
-      def ==(other)
-        other.is_a?(self.class) && to_h == other.to_h
-      end
-
-      # @param error [Exception]
+      # Checks if the given error should be tracked
+      #
+      # @param error [#==] The error to check, e.g. an Exception, Class or Proc
       # @return [Boolean]
       def track_error?(error)
         skip = skipped_errors.any? { |klass| klass === error }
@@ -90,28 +70,41 @@ module Stoplight
         !skip && track
       end
 
-      # Updates the configuration with new settings and returns a new instance.
-      #
+      # This method applies configuration dsl and revalidates the configuration
       # @return [Stoplight::Light::Config]
       def with(**settings)
-        self.class.new(**to_h.merge(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
 
-      # @return [Hash]
-      def to_h
-        {
-          cool_off_time:,
-          data_store:,
-          error_notifier:,
-          name:,
-          notifiers:,
-          threshold:,
-          window_size:,
-          tracked_errors:,
-          skipped_errors:,
-          traffic_control:,
-          traffic_recovery:
-        }
+      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

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.
       #
@@ -30,6 +48,23 @@ module Stoplight
       def stop_traffic?(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_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.0.3")
+  VERSION = Gem::Version.new("5.2.0")
 end