stoplight 5.3.8 → 5.5.0

data/lib/stoplight/domain/tracker/recovery_probe.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Tracker
+      class RecoveryProbe < Base
+        # @!attribute [r] data_store
+        #   @return [Stoplight::DataStore::Base] The data store associated with the light.
+        protected attr_reader :data_store
+
+        # @!attribute [r] traffic_recovery
+        #   @return [Stoplight::Domain::TrafficRecovery::Base]
+        protected attr_reader :traffic_recovery
+
+        # @!attribute [r] traffic_control
+        #   @return [Stoplight::Domain::TrafficControl::Base]
+        protected attr_reader :notifiers
+
+        # @!attribute [r] config
+        #   @return [Stoplight::Domain::Config] The configuration for the light.
+        protected attr_reader :config
+
+        # @param data_store [Stoplight::Domain::DataStore]
+        # @param traffic_recovery [Stoplight::Domain::TrafficRecovery::Base]
+        # @param notifiers [<Stoplight::Domain::StateTransitionNotifier>]
+        # @param config [Stoplight::Domain::Config]
+        def initialize(data_store:, traffic_recovery:, notifiers:, config:)
+          @data_store = data_store
+          @traffic_recovery = traffic_recovery
+          @notifiers = notifiers
+          @config = config
+        end
+
+        # @param exception [Exception]
+        def record_failure(exception)
+          metadata = data_store.record_recovery_probe_failure(config, exception)
+
+          recover(metadata)
+        end
+
+        def record_success
+          metadata = data_store.record_recovery_probe_success(config)
+
+          recover(metadata)
+        end
+        RECOVERY_TRANSITIONS = {
+          TrafficRecovery::GREEN => [Color::YELLOW, Color::GREEN],
+          TrafficRecovery::YELLOW => [Color::RED, Color::YELLOW],
+          TrafficRecovery::RED => [Color::YELLOW, Color::RED]
+        }.freeze
+
+        private def recover(metadata)
+          recovery_result = traffic_recovery.determine_color(config, metadata)
+
+          return if recovery_result == TrafficRecovery::PASS
+
+          from_color, to_color = RECOVERY_TRANSITIONS.fetch(recovery_result) do
+            raise "recovery strategy returned unexpected color: #{recovery_result}"
+          end
+
+          transition_and_notify(from_color, to_color, nil)
+        end
+
+        # @param other [any]
+        # @return [bool]
+        def ==(other)
+          super && traffic_recovery == other.traffic_recovery
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/tracker/request.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Tracker
+      # Tracks request outcomes (success/failure) and manages state transitions
+      # for normal traffic.
+      #
+      # Used by +GreenRunStrategy+ to track failures and potentially open the circuit.
+      #
+      # @api private
+      class Request < Base
+        # @!attribute [r] data_store
+        #   @return [Stoplight::DataStore::Base] The data store associated with the light.
+        protected attr_reader :data_store
+
+        # @!attribute [r] traffic_control
+        #   @return [Stoplight::Domain::TrafficControl::Base]
+        protected attr_reader :traffic_control
+
+        # @!attribute [r] traffic_control
+        #   @return [Stoplight::Domain::TrafficControl::Base]
+        protected attr_reader :notifiers
+
+        # @!attribute [r] config
+        #   @return [Stoplight::Domain::Config] The configuration for the light.
+        protected attr_reader :config
+
+        # @param data_store [Stoplight::Domain::DataStore]
+        # @param traffic_control [Stoplight::Domain::TrafficControl::Base]
+        # @param notifiers [<Stoplight::Domain::StateTransitionNotifier>]
+        # @param config [Stoplight::Domain::Config]
+        def initialize(data_store:, traffic_control:, notifiers:, config:)
+          @data_store = data_store
+          @traffic_control = traffic_control
+          @notifiers = notifiers
+          @config = config
+        end
+
+        # @param exception [Exception]
+        # @return [void]
+        def record_failure(exception)
+          metadata = data_store.record_failure(config, exception)
+
+          transition_to_red(exception, metadata:)
+        end
+
+        # @return [void]
+        def record_success
+          data_store.record_success(config)
+        end
+
+        private def transition_to_red(exception, metadata:)
+          if traffic_control.stop_traffic?(config, metadata)
+            transition_and_notify(Color::GREEN, Color::RED, exception)
+          end
+        end
+
+        # @param other [any]
+        # @return [bool]
+        def ==(other)
+          super && traffic_control == other.traffic_control
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module TrafficControl
+      # Strategies for determining when a Stoplight should change color to red.
+      #
+      # These strategies evaluate the current state and metrics of a Stoplight to decide
+      # if traffic should be stopped (i.e., if the light should turn RED).
+      #
+      # @example Creating a custom strategy
+      #   class ErrorRateStrategy < Stoplight::Domain::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
+      #
+      #       error_rate = metadata.failures.fdiv(total)
+      #       error_rate >= 0.5 # Stop traffic when error rate reaches 50%
+      #     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 whether traffic should be stopped based on the Stoplight's
+        # current state and metrics.
+        #
+        # @param config [Stoplight::Domain::Config]
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [Boolean] true if traffic should be stopped (rec), false otherwise (green)
+        # :nocov:
+        def stop_traffic?(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_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