stoplight 5.4.0 → 5.5.0

data/lib/stoplight/domain/traffic_control/consecutive_errors.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module TrafficControl
+      # A strategy that stops the traffic based on consecutive failures number.
+      #
+      # This strategy implements two distinct behaviors based on whether a window size
+      # is configured:
+      #
+      # 1. When window_size is set: The Stoplight turns red when the total number of
+      #    failures within the window reaches the threshold.
+      #
+      # 2. When window_size is not set: The Stoplight turns red when consecutive failures
+      #    reach the threshold.
+      #
+      # @example With window-based configuration
+      #   traffic_control = Stoplight::Domain::TrafficControl::ConsecutiveErrors.new
+      #   config = Stoplight::Domain::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
+      #   traffic_control = Stoplight::Domain::TrafficControl::ConsecutiveErrors.new
+      #   config = Stoplight::Domain::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 ConsecutiveErrors < Base
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Domain::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::Domain::Config]
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [Boolean] true if failures have reached the threshold, false otherwise
+        def stop_traffic?(config, metadata)
+          if config.window_size
+            [metadata.consecutive_errors, metadata.errors].min >= config.threshold
+          else
+            metadata.consecutive_errors >= config.threshold
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/traffic_control/error_rate.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module TrafficControl
+      # A strategy that stops the traffic based on error rate.
+      #
+      # @example
+      #   traffic_control = Stoplight::Domain::TrafficControl::ErrorRate.new
+      #   config = Stoplight::Domain::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::Domain::TrafficControl::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::Domain::Config]
+        # @return [Stoplight::Domain::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::Domain::Config]
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [Boolean]
+        def stop_traffic?(config, metadata)
+          metadata.requests >= min_requests && metadata.error_rate >= config.threshold
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/traffic_recovery/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module TrafficRecovery
+      # Strategies for determining how to recover traffic flow through the Stoplight.
+      # These strategies evaluate recovery metrics to decide which color the Stoplight should
+      # transition to during the recovery process.
+      #
+      # @example Creating a custom traffic recovery strategy
+      #   class GradualRecovery < Stoplight::Domain::TrafficRecovery::Base
+      #     def initialize(min_success_rate: 0.8, min_samples: 100)
+      #       @min_success_rate = min_success_rate
+      #       @min_samples = min_samples
+      #     end
+      #
+      #     def determine_color(config, metadata)
+      #       total_probes = metadata.recovery_probe_successes + metadata.recovery_probe_errors
+      #
+      #       if total_probes < @min_samples
+      #         return Color::YELLOW # Keep recovering, not enough samples
+      #       end
+      #
+      #       success_rate = metadata.recovery_probe_successes.fdiv(total_probes)
+      #       if success_rate >= @min_success_rate
+      #         Color::GREEN # Recovery successful
+      #       elsif success_rate <= 0.2
+      #         Color::RED # Recovery failed, too many errors
+      #       else
+      #         Color::YELLOW # Continue recovery
+      #       end
+      #     end
+      #   end
+      #
+      # @abstract
+      # @api private
+      class Base
+        # Checks if the strategy is compatible with the given Stoplight configuration.
+        #
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Domain::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.
+        #
+        # @param config [Stoplight::Domain::Config]
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [TrafficRecovery::Decision]
+        # :nocov:
+        def determine_color(config, metadata)
+          raise NotImplementedError
+        end
+        # :nocov:
+
+        # @param other [any]
+        # @return [Boolean]
+        def ==(other)
+          other.is_a?(self.class)
+        end
+
+        # Returns a compatibility result indicating the strategy is compatible.
+        #
+        # @return [Stoplight::Domain::CompatibilityResult] A compatible result.
+        private def compatible = CompatibilityResult.compatible
+
+        # Returns a compatibility result indicating the strategy is incompatible.
+        #
+        # @param errors [Array<String>] The list of error messages describing incompatibility.
+        # @return [Stoplight::Domain::CompatibilityResult] An incompatible result.
+        private def incompatible(*errors) = CompatibilityResult.incompatible(*errors)
+      end
+    end
+  end
+end

data/lib/stoplight/domain/traffic_recovery/consecutive_successes.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    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::Domain::Config.new(
+      #     cool_off_time: 60,
+      #     recovery_threshold: 3
+      #   )
+      #   strategy = Stoplight::Domain::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::Domain::Config]
+        # @return [Stoplight::Domain::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::Domain::Config]
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [TrafficRecovery::Decision]
+        def determine_color(config, metadata)
+          return TrafficRecovery::PASS if metadata.color != Color::YELLOW
+
+          recovery_started_at = metadata.recovery_started_at || metadata.recovery_scheduled_after
+
+          if metadata.last_error_at && metadata.last_error_at >= recovery_started_at
+            TrafficRecovery::RED
+          elsif [metadata.consecutive_successes, metadata.recovery_probe_successes].min >= config.recovery_threshold
+            TrafficRecovery::GREEN
+          else
+            TrafficRecovery::YELLOW
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/traffic_recovery.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module TrafficRecovery
+      Decision = Data.define(:decision)
+      GREEN = Decision.new("green")
+      YELLOW = Decision.new("yellow")
+      RED = Decision.new("red")
+      PASS = Decision.new("pass")
+    end
+  end
+end

data/lib/stoplight/infrastructure/data_store/memory/sliding_window.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      class Memory < Domain::DataStore
+        # Hash-based sliding window for O(1) amortized operations.
+        #
+        # Maintains a running sum and stores per-second counts in a Hash. Ruby's Hash
+        # preserves insertion order (FIFO), allowing efficient removal of expired
+        # buckets from the front via +Hash#shift+, with their counts subtracted from
+        # the running sum.
+        #
+        # Performance: O(1) amortized for both reads and writes
+        # Memory: Bounded to the number of buckets
+        #
+        # @note Not thread-safe; synchronization must be handled externally
+        # @api private
+        class SlidingWindow
+          # @!attribute buckets
+          #   @return [Hash<Integer, Integer>] A hash mapping time buckets to their counts
+          private attr_reader :buckets
+
+          # @!attribute running_sum
+          #   @return [Integer] The running sum of all increments in the current window
+          private attr_accessor :running_sum
+
+          def initialize
+            @buckets = Hash.new { |buckets, bucket| buckets[bucket] = 0 }
+            @running_sum = 0
+          end
+
+          # Increment the count at a given timestamp
+          def increment
+            buckets[current_bucket] += 1
+            self.running_sum += 1
+          end
+
+          # @param window_start [Time]
+          # @return [Integer]
+          def sum_in_window(window_start)
+            slide_window!(window_start)
+            self.running_sum
+          end
+
+          private def slide_window!(window_start)
+            window_start_ts = window_start.to_i
+
+            loop do
+              timestamp, sum = buckets.first
+              if timestamp.nil? || timestamp >= window_start_ts
+                break
+              else
+                self.running_sum -= sum
+                buckets.shift
+              end
+            end
+          end
+
+          private def current_bucket
+            bucket_for_time(current_time)
+          end
+
+          private def bucket_for_time(time)
+            time.to_i
+          end
+
+          private def current_time
+            Time.now
+          end
+
+          def inspect
+            "#<#{self.class.name} #{buckets}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/data_store/memory.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      # @see +Domain::DataStore+
+      class Memory < Domain::DataStore
+        include MonitorMixin
+
+        KEY_SEPARATOR = ":"
+
+        def initialize
+          @errors = Hash.new { |errors, light_name| errors[light_name] = SlidingWindow.new }
+          @successes = Hash.new { |successes, light_name| successes[light_name] = SlidingWindow.new }
+
+          @recovery_probe_errors = Hash.new { |recovery_probe_errors, light_name| recovery_probe_errors[light_name] = SlidingWindow.new }
+          @recovery_probe_successes = Hash.new { |recovery_probe_successes, light_name| recovery_probe_successes[light_name] = SlidingWindow.new }
+
+          @metadata = Hash.new do |metadata, light_name|
+            metadata[light_name] = Domain::Metadata.new(
+              current_time: Time.now,
+              successes: 0,
+              errors: 0,
+              recovery_probe_successes: 0,
+              recovery_probe_errors: 0,
+              last_error: nil,
+              last_error_at: nil,
+              last_success_at: nil,
+              consecutive_errors: 0,
+              consecutive_successes: 0,
+              breached_at: nil,
+              locked_state: Domain::State::UNLOCKED,
+              recovery_scheduled_after: nil,
+              recovery_started_at: nil,
+              recovered_at: nil
+            )
+          end
+          super # MonitorMixin
+        end
+
+        # @return [Array<String>]
+        def names
+          synchronize { @metadata.keys }
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Domain::Metadata]
+        def get_metadata(config)
+          light_name = config.name
+
+          synchronize do
+            current_time = self.current_time
+            recovery_window_start = (current_time - config.cool_off_time)
+            recovered_at = @metadata[light_name].recovered_at
+            window_start = if config.window_size
+              [recovered_at, (current_time - config.window_size)].compact.max
+            else
+              current_time
+            end
+
+            @metadata[light_name].with(
+              current_time:,
+              errors: @errors[config.name].sum_in_window(window_start),
+              successes: @successes[config.name].sum_in_window(window_start),
+              recovery_probe_errors: @recovery_probe_errors[config.name].sum_in_window(recovery_window_start),
+              recovery_probe_successes: @recovery_probe_successes[config.name].sum_in_window(recovery_window_start)
+            )
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @param exception [Exception]
+        # @return [Stoplight::Domain::Metadata]
+        def record_failure(config, exception)
+          current_time = self.current_time
+          light_name = config.name
+          failure = Domain::Failure.from_error(exception, time: current_time)
+
+          synchronize do
+            @errors[light_name].increment if config.window_size
+
+            metadata = @metadata[light_name]
+            @metadata[light_name] = if metadata.last_error_at.nil? || current_time > metadata.last_error_at
+              metadata.with(
+                last_error_at: current_time,
+                last_error: failure,
+                consecutive_errors: metadata.consecutive_errors.succ,
+                consecutive_successes: 0
+              )
+            else
+              metadata.with(
+                consecutive_errors: metadata.consecutive_errors.succ,
+                consecutive_successes: 0
+              )
+            end
+            get_metadata(config)
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [void]
+        def record_success(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            @successes[light_name].increment if config.window_size
+
+            metadata = @metadata[light_name]
+            @metadata[light_name] = if metadata.last_success_at.nil? || current_time > metadata.last_success_at
+              metadata.with(
+                last_success_at: current_time,
+                consecutive_errors: 0,
+                consecutive_successes: metadata.consecutive_successes.succ
+              )
+            else
+              metadata.with(
+                consecutive_errors: 0,
+                consecutive_successes: metadata.consecutive_successes.succ
+              )
+            end
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @param exception [Exception]
+        # @return [Stoplight::Domain::Metadata]
+        def record_recovery_probe_failure(config, exception)
+          light_name = config.name
+          current_time = self.current_time
+          failure = Domain::Failure.from_error(exception, time: current_time)
+
+          synchronize do
+            @recovery_probe_errors[light_name].increment
+
+            metadata = @metadata[light_name]
+            @metadata[light_name] = if metadata.last_error_at.nil? || current_time > metadata.last_error_at
+              metadata.with(
+                last_error_at: current_time,
+                last_error: failure,
+                consecutive_errors: metadata.consecutive_errors.succ,
+                consecutive_successes: 0
+              )
+            else
+              metadata.with(
+                consecutive_errors: metadata.consecutive_errors.succ,
+                consecutive_successes: 0
+              )
+            end
+            get_metadata(config)
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Domain::Metadata]
+        def record_recovery_probe_success(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            @recovery_probe_successes[light_name].increment
+
+            metadata = @metadata[light_name]
+            @metadata[light_name] = if metadata.last_success_at.nil? || current_time > metadata.last_success_at
+              metadata.with(
+                last_success_at: current_time,
+                consecutive_errors: 0,
+                consecutive_successes: metadata.consecutive_successes.succ
+              )
+            else
+              metadata.with(
+                consecutive_errors: 0,
+                consecutive_successes: metadata.consecutive_successes.succ
+              )
+            end
+            get_metadata(config)
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @param state [String]
+        # @return [String]
+        def set_state(config, state)
+          light_name = config.name
+
+          synchronize do
+            metadata = @metadata[light_name]
+            @metadata[light_name] = metadata.with(locked_state: state)
+          end
+          state
+        end
+
+        # @return [String]
+        def inspect
+          "#<#{self.class.name}>"
+        end
+
+        # Combined method that performs the state transition based on color
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @param color [String] The color to transition to ("GREEN", "YELLOW", or "RED")
+        # @return [Boolean] true if this is the first instance to detect this transition
+        def transition_to_color(config, color)
+          case color
+          when Domain::Color::GREEN
+            transition_to_green(config)
+          when Domain::Color::YELLOW
+            transition_to_yellow(config)
+          when Domain::Color::RED
+            transition_to_red(config)
+          else
+            raise ArgumentError, "Invalid color: #{color}"
+          end
+        end
+
+        # Transitions to GREEN state and ensures only one notification
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @return [Boolean] true if this is the first instance to detect this transition
+        private def transition_to_green(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            metadata = @metadata[light_name]
+            if metadata.recovered_at
+              false
+            else
+              @metadata[light_name] = metadata.with(
+                recovered_at: current_time,
+                recovery_started_at: nil,
+                breached_at: nil,
+                recovery_scheduled_after: nil
+              )
+              true
+            end
+          end
+        end
+
+        # Transitions to YELLOW (recovery) state and ensures only one notification
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @return [Boolean] true if this is the first instance to detect this transition
+        private def transition_to_yellow(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            metadata = @metadata[light_name]
+            if metadata.recovery_started_at.nil?
+              @metadata[light_name] = metadata.with(
+                recovery_started_at: current_time,
+                recovery_scheduled_after: nil,
+                recovered_at: nil,
+                breached_at: nil
+              )
+              true
+            else
+              @metadata[light_name] = metadata.with(
+                recovery_scheduled_after: nil,
+                recovered_at: nil,
+                breached_at: nil
+              )
+              false
+            end
+          end
+        end
+
+        # Transitions to RED state and ensures only one notification
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @return [Boolean] true if this is the first instance to detect this transition
+        private def transition_to_red(config)
+          light_name = config.name
+          current_time = self.current_time
+          recovery_scheduled_after = current_time + config.cool_off_time
+
+          synchronize do
+            metadata = @metadata[light_name]
+            if metadata.breached_at
+              @metadata[light_name] = metadata.with(
+                recovery_scheduled_after: recovery_scheduled_after,
+                recovery_started_at: nil,
+                recovered_at: nil
+              )
+              false
+            else
+              @metadata[light_name] = metadata.with(
+                breached_at: current_time,
+                recovery_scheduled_after: recovery_scheduled_after,
+                recovery_started_at: nil,
+                recovered_at: nil
+              )
+              true
+            end
+          end
+        end
+
+        private def current_time
+          Time.now
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/data_store/redis/lua.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      class Redis
+        # @api private
+        module Lua
+          class << self
+            def read_lua_file(name_without_extension)
+              File.read(File.join(__dir__, "#{name_without_extension}.lua"))
+            end
+          end
+
+          RECORD_FAILURE = read_lua_file("record_failure")
+          RECORD_SUCCESS = read_lua_file("record_success")
+          GET_METADATA = read_lua_file("get_metadata")
+          TRANSITION_TO_YELLOW = read_lua_file("transition_to_yellow")
+          TRANSITION_TO_RED = read_lua_file("transition_to_red")
+          TRANSITION_TO_GREEN = read_lua_file("transition_to_green")
+        end
+      end
+    end
+  end
+end