stoplight 5.3.8 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14702003b76fde01b28e5266b392f5d55b2924c83365a0ab122f11aebf2e4a7
-  data.tar.gz: e9c1b348b2637aa66408de62a2bbbc24b9b73927ca9712a8b4137446e336cd0a
+  metadata.gz: 2629a7cdd83dce508860ffe0c7fe3da4cad02eab605e0cb1b4f1e4c0f7db509d
+  data.tar.gz: 50f13d3625ab327dd07815fd3da1a9384a0cf0f1d75af2db853b098c3b90ba2e
 SHA512:
-  metadata.gz: 1601dd8a7fae2e9c8f89a52556c8f931d3712d71648300aef0e3dae226c9998b7b1fa35e7fa0ce151d943e961473e012ca382b718bb50b44000f5a43e4d667b8
-  data.tar.gz: 7c4e9696009e01bea1908cd3212d4625cc0ac3e03205d1cd69e4471f9aec4f3add7f101e58b393df210658e6be2c2d42b5d4a2ddedd954f832053505e291f232
+  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(Metadata.new, 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(Metadata.new, 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(Metadata.new, 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(Metadata.new, 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

@@ -11,11 +11,11 @@ module Stoplight
       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
@@ -32,65 +32,39 @@ module Stoplight
         light_name = config.name
 
         synchronize do
-          current_time = Time.now
-          recovery_window = (current_time - config.cool_off_time)..current_time
+          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, (current_time - config.window_size)].compact.max
-            (window_start..current_time)
+          window_start = if config.window_size
+            [recovered_at, (current_time - config.window_size)].compact.max
           else
-            (..current_time)
-          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(
             current_time:,
-            errors:,
-            successes:,
-            recovery_probe_errors:,
-            recovery_probe_successes:
+            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
@@ -106,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
             )
@@ -137,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
@@ -161,20 +133,18 @@ 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]
-          @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
             )
@@ -210,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
@@ -229,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]
@@ -251,10 +221,10 @@ 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]
@@ -280,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
@@ -306,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,7 +94,6 @@ module Stoplight
       def get_metadata(config)
         detect_clock_skew
 
-        current_time = Time.now
         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
@@ -147,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|
@@ -163,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
@@ -184,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|
@@ -204,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
@@ -237,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
@@ -258,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)
 
@@ -275,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)
 
@@ -294,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
@@ -399,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
@@ -444,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/red_run_strategy.rb

@@ -19,7 +19,11 @@ module Stoplight
         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/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.8")
+  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.8
+  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