stoplight 5.3.5 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c930c989a3184cfc4fb254c720a854caf34fb56bbb550df150d65125969240b2
-  data.tar.gz: 3ca98448ca2a378d6101e4b10e4567adb24bc65c2747d77bccf4b9386aeba64c
+  metadata.gz: 2629a7cdd83dce508860ffe0c7fe3da4cad02eab605e0cb1b4f1e4c0f7db509d
+  data.tar.gz: 50f13d3625ab327dd07815fd3da1a9384a0cf0f1d75af2db853b098c3b90ba2e
 SHA512:
-  metadata.gz: caf3fbc0b32e823a3877525841ab46948fdedbda6791da8006ded3c194229aad7add1c01df82f60b406606a34481a40535662036b2f21caf1ea953ed58ae3eab
-  data.tar.gz: 0d372655a21b4f2ebf04973a6fa41ae4e24e1bab2851bfef69c6ba866a2e38231cdc2a13f4c3afb7a267f56c7a5e3040d88c4ce0602f6b4392b9216fd57d6f2a
+  metadata.gz: 9aa893f78f602c6d71f82f15deb41d6aa0bb4bc0ca37bf3756003699e2b158e1d3a857ee0f1fdd6cebcbb35fb787e5f515a36f89dd5560c000297302cd0e7e18
+  data.tar.gz: 772938b653645a1ad3c8ca5e9e5958871c1b8802da6ce947d38fd9d5390fa9e336d8838941571569aed102cd0656c58389224b417bcf059f4569295c42894d6d

data/README.md

@@ -99,6 +99,19 @@ light.run { 1 / 0 } #=> raises Stoplight::Error::RedLight: example-zero
 light.color # => "red"
 ```
 
+The `Stoplight::Error::RedLight` provides metadata about the error:
+
+```ruby
+def run_request
+  light = Stoplight("Example", cool_off_time: 10)
+  light.run { 1 / 0 }  #=> raises Stoplight::Error::RedLight
+rescue Stoplight::Error::RedLight => error
+  puts error.light_name #=> "Example"
+  puts error.cool_off_time #=> 10
+  puts error.retry_after   #=> Absolute Time after which a recovery attempt can occur (e.g., "2025-10-21 15:39:50.672414 +0600")
+end
+```
+
 After one minute, the light transitions to yellow, allowing a test execution:
 
 ```ruby
@@ -131,6 +144,8 @@ receives `nil`. In both cases, the return value of the fallback becomes the retu
 
 Stoplight comes with a built-in Admin Panel that can track all active Lights and manually lock them in the desired state (`Green` or `Red`). Locking lights in certain states might be helpful in scenarios like E2E testing.
 
+![Admin Panel Screenshot](assets/admin.png)
+
 To add Admin Panel protected by basic authentication to your Rails project, add this configuration to your `config/routes.rb` file.
 
 ```ruby

data/lib/generators/stoplight/install/templates/stoplight.rb.erb

@@ -12,7 +12,9 @@ require "redis"
 #   "redis://admin:p4ssw0rd@10.0.1.1:6380/15"
 redis = Redis.new
 data_store = Stoplight::DataStore::Redis.new(redis)
+error_notifier = Rails.error.method(:report)
 
 Stoplight.configure do |config|
   config.data_store = data_store
+  config.error_notifier = error_notifier
 end

data/lib/stoplight/config/system_config.rb

@@ -2,6 +2,9 @@
 
 module Stoplight
   module Config
-    SystemConfig = LibraryDefaultConfig
+    SystemConfig = LibraryDefaultConfig.with(
+      traffic_recovery: :consecutive_successes,
+      recovery_threshold: 3
+    )
   end
 end

data/lib/stoplight/data_store/fail_safe.rb

@@ -10,10 +10,6 @@ module Stoplight
     #
     # @api private
     class FailSafe < Base
-      # @!attribute [r] data_store
-      #   @return [Stoplight::DataStore::Base] The underlying data store being wrapped.
-      protected attr_reader :data_store
-
       class << self
         # Wraps a data store with fail-safe mechanisms.
         #
@@ -30,62 +26,70 @@ module Stoplight
         end
       end
 
+      # @!attribute data_store
+      #  @return [Stoplight::DataStore::Base] The underlying primary data store being used
+      protected attr_reader :data_store
+
+      # @!attribute failover_data_store
+      #   @return [Stoplight::DataStore::Base] The fallback data store used when the primary fails.
+      private attr_reader :failover_data_store
+
+      # @!attribute circuit_breaker
+      #   @return [Stoplight::Light] The circuit breaker used to handle data store failures.
+      private attr_reader :circuit_breaker
+
       # @param data_store [Stoplight::DataStore::Base]
-      def initialize(data_store)
+      def initialize(data_store, failover_data_store: Default::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
-        )
+        @failover_data_store = failover_data_store
+        @circuit_breaker = Stoplight.system_light("stoplight:data_store:fail_safe:#{data_store.class.name}")
       end
 
       def names
-        with_fallback([]) do
+        with_fallback(:names) do
           data_store.names
         end
       end
 
-      def get_metadata(config)
-        with_fallback(EmptyMetadata, config) do
-          data_store.get_metadata(config)
+      def get_metadata(config, *args, **kwargs)
+        with_fallback(:get_metadata, config, *args, **kwargs) do
+          data_store.get_metadata(config, *args, **kwargs)
         end
       end
 
-      def record_failure(config, failure)
-        with_fallback(EmptyMetadata, config) do
-          data_store.record_failure(config, failure)
+      def record_failure(config, *args, **kwargs)
+        with_fallback(:record_failure, config, *args, **kwargs) do
+          data_store.record_failure(config, *args, **kwargs)
         end
       end
 
-      def record_success(config, **args)
-        with_fallback(nil, config) do
-          data_store.record_success(config, **args)
+      def record_success(config, *args, **kwargs)
+        with_fallback(:record_success, config, *args, **kwargs) do
+          data_store.record_success(config, *args, **kwargs)
         end
       end
 
-      def record_recovery_probe_success(config, **args)
-        with_fallback(EmptyMetadata, config) do
-          data_store.record_recovery_probe_success(config, **args)
+      def record_recovery_probe_success(config, *args, **kwargs)
+        with_fallback(:record_recovery_probe_success, config, *args, **kwargs) do
+          data_store.record_recovery_probe_success(config, *args, **kwargs)
         end
       end
 
-      def record_recovery_probe_failure(config, failure)
-        with_fallback(EmptyMetadata, config) do
-          data_store.record_recovery_probe_failure(config, failure)
+      def record_recovery_probe_failure(config, *args, **kwargs)
+        with_fallback(:record_recovery_probe_failure, config, *args, **kwargs) do
+          data_store.record_recovery_probe_failure(config, *args, **kwargs)
         end
       end
 
-      def set_state(config, state)
-        with_fallback(State::UNLOCKED, config) do
-          data_store.set_state(config, state)
+      def set_state(config, *args, **kwargs)
+        with_fallback(:set_state, config, *args, **kwargs) do
+          data_store.set_state(config, *args, **kwargs)
         end
       end
 
-      def transition_to_color(config, color)
-        with_fallback(false, config) do
-          data_store.transition_to_color(config, color)
+      def transition_to_color(config, *args, **kwargs)
+        with_fallback(:transition_to_color, config, *args, **kwargs) do
+          data_store.transition_to_color(config, *args, **kwargs)
         end
       end
 
@@ -93,21 +97,16 @@ module Stoplight
         other.is_a?(self.class) && other.data_store == data_store
       end
 
-      # @param default [Object, nil]
-      # @param config [Stoplight::Light::Config]
-      private def with_fallback(default = nil, config = nil, &code)
+      # @param method_name [Symbol] protected method name
+      private def with_fallback(method_name, *args, **kwargs, &code)
         fallback = proc do |error|
+          config = args.first
           config.error_notifier.call(error) if config && error
-          default
+          @failover_data_store.public_send(method_name, *args, **kwargs)
         end
 
         circuit_breaker.run(fallback, &code)
       end
-
-      # @return [Stoplight::Light] The circuit breaker used to handle failures.
-      private def circuit_breaker
-        @circuit_breaker ||= Stoplight.system_light("stoplight:data_store:fail_safe:#{data_store.class.name}")
-      end
     end
   end
 end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module DataStore
+    class Memory < Base
+      # 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

data/lib/stoplight/data_store/memory.rb

@@ -7,14 +7,15 @@ module Stoplight
     # @see Base
     class Memory < Base
       include MonitorMixin
+
       KEY_SEPARATOR = ":"
 
       def initialize
-        @errors = Hash.new { |h, k| h[k] = [] }
-        @successes = Hash.new { |h, k| h[k] = [] }
+        @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 { |h, k| h[k] = [] }
-        @recovery_probe_successes = Hash.new { |h, k| h[k] = [] }
+        @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 { |h, k| h[k] = Metadata.new }
         super # MonitorMixin
@@ -29,66 +30,41 @@ module Stoplight
       # @return [Stoplight::Metadata]
       def get_metadata(config)
         light_name = config.name
-        window_end = Time.now
-        recovery_window = (window_end - config.cool_off_time + 1)..window_end
 
         synchronize do
+          current_time = self.current_time
+          recovery_window_start = (current_time - config.cool_off_time)
           recovered_at = @metadata[light_name].recovered_at
-          window = if config.window_size
-            window_start = [recovered_at, (window_end - config.window_size + 1)].compact.max
-            (window_start..window_end)
+          window_start = if config.window_size
+            [recovered_at, (current_time - config.window_size)].compact.max
           else
-            (..window_end)
-          end
-
-          errors = @errors[config.name].count do |request_time|
-            window.cover?(request_time)
-          end
-
-          successes = @successes[config.name].count do |request_time|
-            window.cover?(request_time)
-          end
-
-          recovery_probe_errors = @recovery_probe_errors[config.name].count do |request_time|
-            recovery_window.cover?(request_time)
-          end
-          recovery_probe_successes = @recovery_probe_successes[config.name].count do |request_time|
-            recovery_window.cover?(request_time)
+            current_time
           end
 
           @metadata[light_name].with(
-            errors:,
-            successes:,
-            recovery_probe_errors:,
-            recovery_probe_successes:
+            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 metrics [<Time>]
-      # @param window_size [Numeric, nil]
-      # @return [void]
-      def cleanup(metrics, window_size:)
-        min_age = Time.now - [window_size&.*(3), METRICS_RETENTION_TIME].compact.min
-
-        metrics.reject! { _1 < min_age }
-      end
-
       # @param config [Stoplight::Light::Config]
       # @param failure [Stoplight::Failure]
       # @return [Stoplight::Metadata]
       def record_failure(config, failure)
+        current_time = self.current_time
         light_name = config.name
 
         synchronize do
-          @errors[light_name].unshift(failure.time) if config.window_size
-
-          cleanup(@errors[light_name], window_size: config.window_size)
+          @errors[light_name].increment if config.window_size
 
           metadata = @metadata[light_name]
-          @metadata[light_name] = if metadata.last_error_at.nil? || failure.time > metadata.last_error_at
+          @metadata[light_name] = if metadata.last_error_at.nil? || current_time > metadata.last_error_at
             metadata.with(
-              last_error_at: failure.time,
+              last_error_at: current_time,
               last_error: failure,
               consecutive_errors: metadata.consecutive_errors.succ,
               consecutive_successes: 0
@@ -104,20 +80,18 @@ module Stoplight
       end
 
       # @param config [Stoplight::Light::Config]
-      # @param request_id [String]
-      # @param request_time [Time]
       # @return [void]
-      def record_success(config, request_time: Time.now, request_id: SecureRandom.hex(12))
+      def record_success(config)
         light_name = config.name
+        current_time = self.current_time
 
         synchronize do
-          @successes[light_name].unshift(request_time) if config.window_size
-          cleanup(@successes[light_name], window_size: config.window_size)
+          @successes[light_name].increment if config.window_size
 
           metadata = @metadata[light_name]
-          @metadata[light_name] = if metadata.last_success_at.nil? || request_time > metadata.last_success_at
+          @metadata[light_name] = if metadata.last_success_at.nil? || current_time > metadata.last_success_at
             metadata.with(
-              last_success_at: request_time,
+              last_success_at: current_time,
               consecutive_errors: 0,
               consecutive_successes: metadata.consecutive_successes.succ
             )
@@ -135,15 +109,15 @@ module Stoplight
       # @return [Stoplight::Metadata]
       def record_recovery_probe_failure(config, failure)
         light_name = config.name
+        current_time = self.current_time
 
         synchronize do
-          @recovery_probe_errors[light_name].unshift(failure.time)
-          cleanup(@recovery_probe_errors[light_name], window_size: config.cool_off_time)
+          @recovery_probe_errors[light_name].increment
 
           metadata = @metadata[light_name]
-          @metadata[light_name] = if metadata.last_error_at.nil? || failure.time > metadata.last_error_at
+          @metadata[light_name] = if metadata.last_error_at.nil? || current_time > metadata.last_error_at
             metadata.with(
-              last_error_at: failure.time,
+              last_error_at: current_time,
               last_error: failure,
               consecutive_errors: metadata.consecutive_errors.succ,
               consecutive_successes: 0
@@ -159,28 +133,23 @@ module Stoplight
       end
 
       # @param config [Stoplight::Light::Config]
-      # @param request_id [String]
-      # @param request_time [Time]
       # @return [Stoplight::Metadata]
-      def record_recovery_probe_success(config, request_time: Time.now, request_id: SecureRandom.hex(12))
+      def record_recovery_probe_success(config)
         light_name = config.name
+        current_time = self.current_time
 
         synchronize do
-          @recovery_probe_successes[light_name].unshift(request_time)
-          cleanup(@recovery_probe_successes[light_name], window_size: config.cool_off_time)
+          @recovery_probe_successes[light_name].increment
 
           metadata = @metadata[light_name]
-          recovery_started_at = metadata.recovery_started_at || request_time
-          @metadata[light_name] = if metadata.last_success_at.nil? || request_time > metadata.last_success_at
+          @metadata[light_name] = if metadata.last_success_at.nil? || current_time > metadata.last_success_at
             metadata.with(
-              last_success_at: request_time,
-              recovery_started_at:,
+              last_success_at: current_time,
               consecutive_errors: 0,
               consecutive_successes: metadata.consecutive_successes.succ
             )
           else
             metadata.with(
-              recovery_started_at:,
               consecutive_errors: 0,
               consecutive_successes: metadata.consecutive_successes.succ
             )
@@ -211,16 +180,15 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config] The light configuration
       # @param color [String] The color to transition to ("GREEN", "YELLOW", or "RED")
-      # @param current_time [Time]
       # @return [Boolean] true if this is the first instance to detect this transition
-      def transition_to_color(config, color, current_time: Time.now)
+      def transition_to_color(config, color)
         case color
         when Color::GREEN
           transition_to_green(config)
         when Color::YELLOW
-          transition_to_yellow(config, current_time:)
+          transition_to_yellow(config)
         when Color::RED
-          transition_to_red(config, current_time:)
+          transition_to_red(config)
         else
           raise ArgumentError, "Invalid color: #{color}"
         end
@@ -230,8 +198,9 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config] The light configuration
       # @return [Boolean] true if this is the first instance to detect this transition
-      private def transition_to_green(config, current_time: Time.now)
+      private def transition_to_green(config)
         light_name = config.name
+        current_time = self.current_time
 
         synchronize do
           metadata = @metadata[light_name]
@@ -252,16 +221,14 @@ module Stoplight
       # Transitions to YELLOW (recovery) state and ensures only one notification
       #
       # @param config [Stoplight::Light::Config] The light configuration
-      # @param current_time [Time]
       # @return [Boolean] true if this is the first instance to detect this transition
-      private def transition_to_yellow(config, current_time: Time.now)
+      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
-            false
-          else
+          if metadata.recovery_started_at.nil?
             @metadata[light_name] = metadata.with(
               recovery_started_at: current_time,
               recovery_scheduled_after: nil,
@@ -269,6 +236,13 @@ module Stoplight
               breached_at: nil
             )
             true
+          else
+            @metadata[light_name] = metadata.with(
+              recovery_scheduled_after: nil,
+              recovered_at: nil,
+              breached_at: nil
+            )
+            false
           end
         end
       end
@@ -276,10 +250,10 @@ module Stoplight
       # Transitions to RED state and ensures only one notification
       #
       # @param config [Stoplight::Light::Config] The light configuration
-      # @param current_time [Time]
       # @return [Boolean] true if this is the first instance to detect this transition
-      private def transition_to_red(config, current_time: Time.now)
+      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
@@ -302,6 +276,10 @@ module Stoplight
           end
         end
       end
+
+      private def current_time
+        Time.now
+      end
     end
   end
 end

data/lib/stoplight/data_store/redis.rb

@@ -94,8 +94,7 @@ module Stoplight
       def get_metadata(config)
         detect_clock_skew
 
-        window_end = Time.now
-        window_end_ts = window_end.to_i
+        window_end_ts = current_time.to_i
         window_start_ts = window_end_ts - [config.window_size, Base::METRICS_RETENTION_TIME].compact.min.to_i
         recovery_window_start_ts = window_end_ts - config.cool_off_time.to_i
 
@@ -133,10 +132,11 @@ module Stoplight
         last_error = normalize_failure(last_error_json, config.error_notifier) if last_error_json
 
         Metadata.new(
-          successes: successes,
-          errors: errors,
-          recovery_probe_successes: recovery_probe_successes,
-          recovery_probe_errors: recovery_probe_errors,
+          current_time:,
+          successes:,
+          errors:,
+          recovery_probe_successes:,
+          recovery_probe_errors:,
           last_error:,
           **meta_hash
         )
@@ -146,7 +146,7 @@ module Stoplight
       # @param failure [Stoplight::Failure] The failure to record.
       # @return [Stoplight::Metadata] The updated metadata after recording the failure.
       def record_failure(config, failure)
-        current_ts = failure.time.to_i
+        current_ts = current_time.to_i
         failure_json = failure.to_json
 
         @redis.then do |client|
@@ -162,16 +162,16 @@ module Stoplight
         get_metadata(config)
       end
 
-      def record_success(config, request_id: SecureRandom.hex(12), request_time: Time.now)
-        request_ts = request_time.to_i
+      def record_success(config, request_id: SecureRandom.hex(12))
+        current_ts = current_time.to_i
 
         @redis.then do |client|
           client.evalsha(
             record_success_sha,
-            argv: [request_ts, request_id, metrics_ttl, metadata_ttl],
+            argv: [current_ts, request_id, metrics_ttl, metadata_ttl],
             keys: [
               metadata_key(config),
-              config.window_size && successes_key(config, time: request_ts)
+              config.window_size && successes_key(config, time: current_ts)
             ].compact
           )
         end
@@ -183,7 +183,7 @@ module Stoplight
       # @param failure [Failure] The failure to record.
       # @return [Stoplight::Metadata] The updated metadata after recording the failure.
       def record_recovery_probe_failure(config, failure)
-        current_ts = failure.time.to_i
+        current_ts = current_time.to_i
         failure_json = failure.to_json
 
         @redis.then do |client|
@@ -203,18 +203,17 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config] The light configuration.
       # @param request_id [String] The unique identifier for the request
-      # @param request_time [Time] The time of the request
       # @return [Stoplight::Metadata] The updated metadata after recording the success.
-      def record_recovery_probe_success(config, request_id: SecureRandom.hex(12), request_time: Time.now)
-        request_ts = request_time.to_i
+      def record_recovery_probe_success(config, request_id: SecureRandom.hex(12))
+        current_ts = current_time.to_i
 
         @redis.then do |client|
           client.evalsha(
             record_success_sha,
-            argv: [request_ts, request_id, metrics_ttl, metadata_ttl],
+            argv: [current_ts, request_id, metrics_ttl, metadata_ttl],
             keys: [
               metadata_key(config),
-              recovery_probe_successes_key(config, time: request_ts)
+              recovery_probe_successes_key(config, time: current_ts)
             ].compact
           )
         end
@@ -236,18 +235,15 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config] The light configuration
       # @param color [String] The color to transition to ("green", "yellow", or "red")
-      # @param current_time [Time] Current timestamp
       # @return [Boolean] true if this is the first instance to detect this transition
-      def transition_to_color(config, color, current_time: Time.now)
-        current_time.to_i
-
+      def transition_to_color(config, color)
         case color
         when Color::GREEN
           transition_to_green(config)
         when Color::YELLOW
-          transition_to_yellow(config, current_time:)
+          transition_to_yellow(config)
         when Color::RED
-          transition_to_red(config, current_time:)
+          transition_to_red(config)
         else
           raise ArgumentError, "Invalid color: #{color}"
         end
@@ -257,7 +253,7 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config] The light configuration
       # @return [Boolean] true if this is the first instance to detect this transition
-      private def transition_to_green(config, current_time: Time.now)
+      private def transition_to_green(config)
         current_ts = current_time.to_i
         meta_key = metadata_key(config)
 
@@ -274,9 +270,8 @@ module Stoplight
       # Transitions to YELLOW (recovery) state and ensures only one notification
       #
       # @param config [Stoplight::Light::Config] The light configuration
-      # @param current_time [Time] Current timestamp
       # @return [Boolean] true if this is the first instance to detect this transition
-      private def transition_to_yellow(config, current_time: Time.now)
+      private def transition_to_yellow(config)
         current_ts = current_time.to_i
         meta_key = metadata_key(config)
 
@@ -293,9 +288,8 @@ module Stoplight
       # Transitions to RED state and ensures only one notification
       #
       # @param config [Stoplight::Light::Config] The light configuration
-      # @param current_time [Time] Current timestamp
       # @return [Boolean] true if this is the first instance to detect this transition
-      private def transition_to_red(config, current_time: Time.now)
+      private def transition_to_red(config)
         current_ts = current_time.to_i
         meta_key = metadata_key(config)
         recovery_scheduled_after_ts = current_ts + config.cool_off_time
@@ -398,7 +392,7 @@ module Stoplight
         return unless should_sample?(0.01) # 1% chance
 
         redis_seconds, _redis_millis = @redis.then(&:time)
-        app_seconds = Time.now.to_i
+        app_seconds = current_time.to_i
         if (redis_seconds - app_seconds).abs > SKEW_TOLERANCE
           warn("Detected clock skew between Redis and the application server. Redis time: #{redis_seconds}, Application time: #{app_seconds}. See https://github.com/bolshakov/stoplight/wiki/Clock-Skew-and-Stoplight-Reliability")
         end
@@ -443,6 +437,10 @@ module Stoplight
           client.script("load", Lua::RECORD_FAILURE)
         end
       end
+
+      private def current_time
+        Time.now
+      end
     end
   end
 end

data/lib/stoplight/error.rb

@@ -5,6 +5,35 @@ module Stoplight
     Base = Class.new(StandardError)
     ConfigurationError = Class.new(Base)
     IncorrectColor = Class.new(Base)
-    RedLight = Class.new(Base)
+    class RedLight < Base
+      # @!attribute light_name
+      #   @return [String] The light's name
+      attr_reader :light_name
+
+      # @!attribute cool_off_time
+      #   @return [Numeric] Cool-off period in seconds
+      attr_reader :cool_off_time
+
+      # @!attribute retry_after
+      #   @return [Time] Absolute Time after which a recovery attempt can occur
+      attr_reader :retry_after
+
+      # Initializes a new RedLight error.
+      #
+      # @param light_name [String] The light's name
+      #
+      # @option cool_off_time [Numeric] Cool-off period in seconds
+      #
+      # @option retry_after [Time] Absolute Time after which a recovery attempt can occur
+      #
+      # @return [Stoplight::Error::RedLight]
+      def initialize(light_name, cool_off_time:, retry_after:)
+        @light_name = light_name
+        @cool_off_time = cool_off_time
+        @retry_after = retry_after
+
+        super(light_name)
+      end
+    end
   end
 end

data/lib/stoplight/light/config.rb

@@ -82,6 +82,7 @@ module Stoplight
       # @return [Stoplight::Light::Config] The validated configuration object.
       def validate_config!
         validate_traffic_control_compatibility!
+        validate_traffic_recovery_compatibility!
         self
       end
 

data/lib/stoplight/light/green_run_strategy.rb

@@ -12,10 +12,11 @@ module Stoplight
       # Executes the provided code block when the light is in the green state.
       #
       # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
+      # @param metadata [Stoplight::Metadata] Metadata capturing the current state of the light.
       # @yield The code block to execute.
       # @return [Object] The result of the code block if successful.
       # @raise [Exception] Re-raises the error if it is not tracked or no fallback is provided.
-      def execute(fallback, &code)
+      def execute(fallback, metadata:, &code)
         # TODO: Consider implementing sampling rate to limit the memory footprint
         code.call.tap { record_success }
       rescue => error

data/lib/stoplight/light/red_run_strategy.rb

@@ -12,13 +12,18 @@ module Stoplight
       # Executes the fallback proc when the light is in the red state.
       #
       # @param fallback [Proc, nil] A fallback proc to execute instead of the code block.
+      # @param metadata [Stoplight::Metadata] Metadata capturing the current state of the light.
       # @return [Object, nil] The result of the fallback proc if provided.
       # @raise [Stoplight::Error::RedLight] Raises an error if no fallback is provided.
-      def execute(fallback)
+      def execute(fallback, metadata:)
         if fallback
           fallback.call(nil)
         else
-          raise Error::RedLight, config.name
+          raise Error::RedLight.new(
+            config.name,
+            cool_off_time: config.cool_off_time,
+            retry_after: metadata.recovery_scheduled_after
+          )
         end
       end
     end

data/lib/stoplight/light/run_strategy.rb

@@ -22,7 +22,9 @@ module Stoplight
         @data_store = config.data_store
       end
 
-      def execute(fallback, &code)
+      # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
+      # @param metadata [Stoplight::Metadata] Metadata capturing the current state of the light.
+      def execute(fallback, metadata:, &code)
         raise NotImplementedError, "Subclasses must implement the execute method"
       end
     end

data/lib/stoplight/light/yellow_run_strategy.rb

@@ -13,10 +13,12 @@ module Stoplight
       # Executes the provided code block when the light is in the yellow state.
       #
       # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
+      # @param metadata [Stoplight::Metadata] Metadata capturing the current state of the light.
       # @yield The code block to execute.
       # @return [Object] The result of the code block if successful.
       # @raise [Exception] Re-raises the error if it is not tracked or no fallback is provided.
-      def execute(fallback, &code)
+      def execute(fallback, metadata:, &code)
+        transition_to_yellow(metadata:)
         # TODO: We need to employ a probabilistic approach here to avoid "thundering herd" problem
         code.call.tap { record_recovery_probe_success }
       rescue => error
@@ -47,6 +49,18 @@ module Stoplight
         recover(metadata)
       end
 
+      # @param metadata [Stoplight::Metadata]
+      # @return [void]
+      def transition_to_yellow(metadata:)
+        return unless metadata.color == Color::YELLOW
+
+        if metadata.recovery_scheduled_after && config.data_store.transition_to_color(config, Color::YELLOW)
+          config.notifiers.each do |notifier|
+            notifier.notify(config, Color::RED, Color::YELLOW, nil)
+          end
+        end
+      end
+
       private def recover(metadata)
         recovery_result = config.traffic_recovery.determine_color(config, metadata)
 
@@ -60,7 +74,7 @@ module Stoplight
         when TrafficRecovery::YELLOW
           if data_store.transition_to_color(config, Color::YELLOW)
             config.notifiers.each do |notifier|
-              notifier.notify(config, Color::GREEN, Color::YELLOW, nil)
+              notifier.notify(config, Color::RED, Color::YELLOW, nil)
             end
           end
         when TrafficRecovery::RED

data/lib/stoplight/light.rb

@@ -32,10 +32,7 @@ module Stoplight
     #
     # @return [String]
     def state
-      config
-        .data_store
-        .get_metadata(config)
-        .locked_state
+      metadata.locked_state
     end
 
     # Returns current color:
@@ -49,10 +46,7 @@ module Stoplight
     #
     # @return [String] returns current light color
     def color
-      config
-        .data_store
-        .get_metadata(config)
-        .color
+      metadata.color
     end
 
     # Runs the given block of code with this circuit breaker
@@ -72,8 +66,10 @@ module Stoplight
     def run(fallback = nil, &code)
       raise ArgumentError, "nothing to run. Please, pass a block into `Light#run`" unless block_given?
 
-      strategy = state_strategy_factory(color)
-      strategy.execute(fallback, &code)
+      metadata.then do |metadata|
+        strategy = state_strategy_factory(metadata.color)
+        strategy.execute(fallback, metadata:, &code)
+      end
     end
 
     # Locks light in either +State::LOCKED_RED+ or +State::LOCKED_GREEN+
@@ -186,5 +182,10 @@ module Stoplight
     def reconfigure(config)
       self.class.new(config)
     end
+
+    # @return [Stoplight::Metadata]
+    def metadata
+      config.data_store.get_metadata(config)
+    end
   end
 end

data/lib/stoplight/metadata.rb

@@ -16,9 +16,11 @@ module Stoplight
     :locked_state,
     :recovery_scheduled_after,
     :recovery_started_at,
-    :recovered_at
+    :recovered_at,
+    :current_time
   ) do
     def initialize(
+      current_time: Time.now,
       successes: 0,
       errors: 0,
       recovery_probe_successes: 0,
@@ -49,6 +51,7 @@ module Stoplight
         recovery_scheduled_after: (Time.at(Integer(recovery_scheduled_after)) if recovery_scheduled_after),
         recovery_started_at: (Time.at(Integer(recovery_started_at)) if recovery_started_at),
         recovered_at: (Time.at(Integer(recovered_at)) if recovered_at),
+        current_time:,
       )
     end
 
@@ -59,17 +62,16 @@ module Stoplight
     # @param kwargs [Hash{Symbol => Object}]
     # @return [Metadata]
     def with(**kwargs)
-      self.class.new(**to_h.merge(kwargs))
+      self.class.new(**to_h.merge(current_time: Time.now, **kwargs))
     end
 
-    # @param at [Time] (Time.now) the moment of time when the color is determined
     # @return [String] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
-    def color(at: Time.now)
+    def color
       if locked_state == State::LOCKED_GREEN
         Color::GREEN
       elsif locked_state == State::LOCKED_RED
         Color::RED
-      elsif (recovery_scheduled_after && recovery_scheduled_after < at) || recovery_started_at
+      elsif (recovery_scheduled_after && recovery_scheduled_after < current_time) || recovery_started_at
         Color::YELLOW
       elsif breached_at
         Color::RED

data/lib/stoplight/traffic_control/consecutive_errors.rb

@@ -14,13 +14,13 @@ module Stoplight
     #    reach the threshold.
     #
     # @example With window-based configuration
-    #   traffic_control = Stoplight::TrafficControlStrategy::ConsecutiveErrors.new
+    #   traffic_control = Stoplight::TrafficControl::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
-    #   traffic_control = Stoplight::TrafficControlStrategy::ConsecutiveErrors.new
+    #   traffic_control = Stoplight::TrafficControl::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

data/lib/stoplight/traffic_control/error_rate.rb

@@ -5,14 +5,14 @@ module Stoplight
     # A strategy that stops the traffic based on error rate.
     #
     # @example
-    #   traffic_control = Stoplight::TrafficControlStrategy::ErrorRate.new
+    #   traffic_control = Stoplight::TrafficControl::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)
+    #   traffic_control = Stoplight::TrafficControl::ErrorRate.new(min_requests: 100)
     #
     # @api private
     class ErrorRate < Base

data/lib/stoplight/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 5.3.5
+  version: 5.4.0
 platform: ruby
 authors:
 - Cameron Desautels
@@ -67,6 +67,7 @@ files:
 - lib/stoplight/data_store/base.rb
 - lib/stoplight/data_store/fail_safe.rb
 - lib/stoplight/data_store/memory.rb
+- lib/stoplight/data_store/memory/sliding_window.rb
 - lib/stoplight/data_store/redis.rb
 - lib/stoplight/data_store/redis/get_metadata.lua
 - lib/stoplight/data_store/redis/lua.rb
@@ -76,7 +77,6 @@ files:
 - lib/stoplight/data_store/redis/transition_to_red.lua
 - lib/stoplight/data_store/redis/transition_to_yellow.lua
 - lib/stoplight/default.rb
-- lib/stoplight/empty_metadata.rb
 - lib/stoplight/error.rb
 - lib/stoplight/failure.rb
 - lib/stoplight/light.rb

data/lib/stoplight/empty_metadata.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  EmptyMetadata = Metadata.new
-end