stoplight 5.7.0 → 5.8.2

data/lib/stoplight/infrastructure/fail_safe/storage/metrics.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      module Storage
+        # A wrapper around a store that provides fail-safe mechanisms using a
+        # circuit breaker. It ensures that operations on the store can gracefully
+        # handle failures by falling back to default values when necessary.
+        #
+        # @api private
+        class Metrics
+          # The underlying primary store being used
+          attr_reader :primary_store
+          attr_reader :error_notifier
+          # The fallback store used when the primary fails.
+          attr_reader :failover_store
+
+          def initialize(primary_store:, error_notifier:, failover_store:, circuit_breaker:)
+            @primary_store = primary_store
+            @error_notifier = error_notifier
+            @failover_store = failover_store
+            @circuit_breaker = circuit_breaker
+          end
+
+          def metrics_snapshot
+            circuit_breaker.run(fallback { failover_store.metrics_snapshot }) do
+              primary_store.metrics_snapshot
+            end
+          end
+
+          def record_success
+            circuit_breaker.run(fallback { failover_store.record_success }) do
+              primary_store.record_success
+            end
+          end
+
+          def record_failure(exception)
+            circuit_breaker.run(fallback { failover_store.record_failure(exception) }) do
+              primary_store.record_failure(exception)
+            end
+          end
+
+          def clear
+            circuit_breaker.run(fallback { failover_store.clear }) do
+              primary_store.clear
+            end
+          end
+
+          private
+
+          # The circuit breaker used to handle store failures.
+          attr_reader :circuit_breaker
+
+          def fallback(&fallback)
+            ->(error) {
+              error_notifier.call(error) if error
+              fallback.call
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/fail_safe/storage/recovery_lock.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      module Storage
+        # A wrapper around a store that provides fail-safe mechanisms using a
+        # circuit breaker. It ensures that operations on the store can gracefully
+        # handle failures by falling back to default values when necessary.
+        #
+        # @api private
+        class RecoveryLock
+          # The underlying primary store being used
+          attr_reader :primary_store
+          attr_reader :error_notifier
+          # The fallback store used when the primary fails.
+          attr_reader :failover_store
+
+          def initialize(primary_store:, error_notifier:, failover_store:, circuit_breaker:)
+            @primary_store = primary_store
+            @error_notifier = error_notifier
+            @failover_store = failover_store
+            @circuit_breaker = circuit_breaker
+          end
+
+          def acquire_lock
+            fallback = ->(error) {
+              error_notifier.call(error) if error
+              wrap_token(:failover, failover_store.acquire_lock)
+            }
+            circuit_breaker.run(fallback) do
+              wrap_token(:primary, primary_store.acquire_lock)
+            end
+          end
+
+          # Routes release to correct store based on token type.
+          # Redis tokens release via primary (with error notification on failure).
+          # Memory tokens release via failover directly.
+          #
+          def release_lock(recovery_lock_token)
+            case recovery_lock_token.origin
+            in :primary
+              fallback = ->(error) {
+                error_notifier.call(error) if error
+              }
+
+              circuit_breaker.run(fallback) do
+                primary_store.release_lock(recovery_lock_token.underlying_token)
+              end
+            in :failover
+              failover_store.release_lock(recovery_lock_token.underlying_token)
+            end
+          end
+
+          private
+
+          # The circuit breaker used to handle store failures.
+          attr_reader :circuit_breaker
+
+          def wrap_token(origin, token)
+            RecoveryLockToken.new(origin:, underlying_token: token) if token
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/fail_safe/storage/recovery_lock_token.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      module Storage
+        class RecoveryLockToken
+          attr_reader :underlying_token
+          attr_reader :origin
+
+          def initialize(underlying_token:, origin:)
+            @underlying_token = underlying_token
+            @origin = origin
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/fail_safe/storage/state.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      module Storage
+        # A wrapper around a store that provides fail-safe mechanisms using a
+        # circuit breaker. It ensures that operations on the store can gracefully
+        # handle failures by falling back to default values when necessary.
+        #
+        # @api private
+        class State
+          attr_reader :primary_store
+          attr_reader :error_notifier
+          attr_reader :failover_store
+          attr_reader :circuit_breaker
+
+          def initialize(primary_store:, error_notifier:, failover_store:, circuit_breaker:)
+            @primary_store = primary_store
+            @error_notifier = error_notifier
+            @failover_store = failover_store
+            @circuit_breaker = circuit_breaker
+          end
+
+          def set_state(state)
+            circuit_breaker.run(fallback { failover_store.set_state(state) }) do
+              primary_store.set_state(state)
+            end
+          end
+
+          # @return [Stoplight::Domain::StateSnapshot]
+          def state_snapshot
+            circuit_breaker.run(fallback { failover_store.state_snapshot }) do
+              primary_store.state_snapshot
+            end
+          end
+
+          # @param color [String]
+          # @return [Boolean]
+          def transition_to_color(color)
+            circuit_breaker.run(fallback { failover_store.transition_to_color(color) }) do
+              primary_store.transition_to_color(color)
+            end
+          end
+
+          def clear
+            circuit_breaker.run(fallback { failover_store.clear }) do
+              primary_store.clear
+            end
+          end
+
+          private def fallback(&fallback)
+            ->(error) {
+              error_notifier.call(error) if error
+              fallback.call
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/{data_store/memory → memory/data_store}/metrics.rb

@@ -2,8 +2,8 @@
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Memory
+    module Memory
+      class DataStore
         class Metrics
           attr_accessor :consecutive_errors
           attr_accessor :consecutive_successes

data/lib/stoplight/infrastructure/{data_store/memory → memory/data_store}/recovery_lock_store.rb

@@ -4,8 +4,8 @@ require "concurrent/map"
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Memory
+    module Memory
+      class DataStore
         # Process-local recovery lock using Ruby's Thread::Mutex.
         #
         # This only serializes recovery within a single Ruby process.
@@ -17,31 +17,29 @@ module Stoplight
         # - Mutexes persist for process lifetime (never GC'd)
         #
         class RecoveryLockStore
-          # @!attribute locks
-          #   Stores one mutex per unique light_name for the lifetime of the process.
-          #   Mutexes are never garbage collected.
-          #   @return [Concurrent::Map<Thread::Mutex>]
-          private attr_reader :locks
-
           def initialize
             @locks = Concurrent::Map.new
           end
 
           # @param light_name [String]
-          # @return [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockToken, nil]
+          # @return [Stoplight::Infrastructure::Memory::DataStore::RecoveryLockToken, nil]
           def acquire_lock(light_name)
             lock = lock_for(light_name)
             RecoveryLockToken.new(light_name:) if lock.try_lock
           end
 
-          # @param recovery_lock_token [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockToken]
+          # @param recovery_lock_token [Stoplight::Infrastructure::Memory::DataStore::RecoveryLockToken]
           # @return [void]
           def release_lock(recovery_lock_token)
             lock_for(recovery_lock_token.light_name).unlock
           end
 
-          # @param light_name [String]
-          # @return [Thread::Mutex]
+          private
+
+          # Stores one mutex per unique light_name for the lifetime of the process.
+          # Mutexes are never garbage collected.
+          attr_reader :locks
+
           private def lock_for(light_name)
             locks.compute_if_absent(light_name) do
               Thread::Mutex.new

data/lib/stoplight/infrastructure/{data_store/memory → memory/data_store}/recovery_lock_token.rb

@@ -2,14 +2,11 @@
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Memory
-        class RecoveryLockToken < Domain::RecoveryLockToken
-          # @!attribute light_name
-          #   @return [String]
+    module Memory
+      class DataStore
+        class RecoveryLockToken
           attr_reader :light_name
 
-          # @param light_name [String]
           def initialize(light_name:)
             @light_name = light_name
           end

data/lib/stoplight/infrastructure/{data_store/memory → memory/data_store}/sliding_window.rb

@@ -2,8 +2,8 @@
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Memory < Domain::DataStore
+    module Memory
+      class 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
@@ -17,17 +17,10 @@ module Stoplight
         # @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
+          def initialize(clock:)
             @buckets = Hash.new { |buckets, bucket| buckets[bucket] = 0 }
             @running_sum = 0
+            @clock = clock
           end
 
           # Increment the count at a given timestamp
@@ -36,14 +29,24 @@ module Stoplight
             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)
+          def inspect
+            "#<#{self.class.name} #{buckets}>"
+          end
+
+          private
+
+          # A hash mapping time buckets to their counts
+          attr_reader :buckets
+          # The running sum of all increments in the current window
+          attr_accessor :running_sum
+          attr_reader :clock
+
+          def slide_window!(window_start)
             window_start_ts = window_start.to_i
 
             loop do
@@ -51,27 +54,19 @@ module Stoplight
               if timestamp.nil? || timestamp >= window_start_ts
                 break
               else
-                self.running_sum -= sum
+                self.running_sum -= sum.to_i
                 buckets.shift
               end
             end
           end
 
-          private def current_bucket
-            bucket_for_time(current_time)
+          def current_bucket
+            bucket_for_time(clock.current_time)
           end
 
-          private def bucket_for_time(time)
+          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

data/lib/stoplight/infrastructure/{data_store/memory → memory/data_store}/state.rb

@@ -2,8 +2,8 @@
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Memory
+    module Memory
+      class DataStore
         class State
           attr_accessor :recovered_at
           attr_accessor :locked_state
@@ -12,7 +12,7 @@ module Stoplight
           attr_accessor :breached_at
 
           def initialize
-            @locked_state = Domain::State::UNLOCKED
+            @locked_state = Stoplight::State::UNLOCKED
           end
         end
       end

data/lib/stoplight/infrastructure/{data_store/memory.rb → memory/data_store.rb}

@@ -4,23 +4,30 @@ require "monitor"
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      # @see +Domain::DataStore+
-      class Memory < Domain::DataStore
+    module Memory
+      # steep:ignore:start
+      # @see +Domain::_DataStore+
+      class DataStore
         include MonitorMixin
 
         KEY_SEPARATOR = ":"
 
         # @!attribute recovery_lock_store
-        #   @return [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockStore]
+        #   @return [Stoplight::Infrastructure::Memory::DataStore::RecoveryLockStore]
         #   @api private
         private attr_reader :recovery_lock_store
 
-        # @param recovery_lock_store [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockStore]
-        def initialize(recovery_lock_store:)
+        # @!attribute clock
+        #   @return [Stoplight::Domain::_Clock]
+        private attr_reader :clock
+
+        # @param recovery_lock_store [Stoplight::Infrastructure::Memory::DataStore::RecoveryLockStore]
+        # @param clock [Stoplight::Domain::_Clock]
+        def initialize(recovery_lock_store:, clock:)
+          @clock = clock
           @recovery_lock_store = recovery_lock_store
-          @errors = Hash.new { |errors, light_name| errors[light_name] = SlidingWindow.new }
-          @successes = Hash.new { |successes, light_name| successes[light_name] = SlidingWindow.new }
+          @errors = Hash.new { |errors, light_name| errors[light_name] = SlidingWindow.new(clock:) }
+          @successes = Hash.new { |successes, light_name| successes[light_name] = SlidingWindow.new(clock:) }
           @metrics = Hash.new { |metrics, light_name| metrics[light_name] = Metrics.new }
 
           @recovery_metrics = Hash.new { |metrics, light_name| metrics[light_name] = Metrics.new }
@@ -36,12 +43,12 @@ module Stoplight
         end
 
         # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Domain::Metrics]
+        # @return [Stoplight::Domain::MetricsSnapshot]
         def get_metrics(config)
           light_name = config.name
 
           synchronize do
-            current_time = self.current_time
+            current_time = clock.current_time
             window_start = if config.window_size
               (current_time - config.window_size)
             else
@@ -55,7 +62,7 @@ module Stoplight
             consecutive_errors = config.window_size ? [metrics.consecutive_errors, errors].min : metrics.consecutive_errors
             consecutive_successes = config.window_size ? [metrics.consecutive_successes.to_i, successes].min : metrics.consecutive_successes.to_i
 
-            Domain::Metrics.new(
+            Domain::MetricsSnapshot.new(
               errors:,
               successes:,
               consecutive_errors:,
@@ -66,14 +73,14 @@ module Stoplight
           end
         end
 
-        # @return [Stoplight::Domain::Metrics]
+        # @return [Stoplight::Domain::MetricsSnapshot]
         def get_recovery_metrics(config)
           light_name = config.name
 
           synchronize do
             metrics = @recovery_metrics[light_name]
 
-            Domain::Metrics.new(
+            Domain::MetricsSnapshot.new(
               errors: nil, successes: nil,
               consecutive_errors: metrics.consecutive_errors,
               consecutive_successes: metrics.consecutive_successes,
@@ -86,7 +93,7 @@ module Stoplight
         # @return [Stoplight::Domain::StateSnapshot]
         def get_state_snapshot(config)
           time, state = synchronize do
-            [current_time, @states[config.name]]
+            [clock.current_time, @states[config.name]]
           end
 
           Domain::StateSnapshot.new(
@@ -102,7 +109,7 @@ module Stoplight
         # @param exception [Exception]
         # @return [void]
         def record_failure(config, exception)
-          current_time = self.current_time
+          current_time = clock.current_time
           light_name = config.name
           failure = Domain::Failure.from_error(exception, time: current_time)
 
@@ -124,8 +131,8 @@ module Stoplight
           light_name = config.name
           synchronize do
             if config.window_size
-              @errors[light_name] = SlidingWindow.new
-              @successes[light_name] = SlidingWindow.new
+              @errors[light_name] = SlidingWindow.new(clock:)
+              @successes[light_name] = SlidingWindow.new(clock:)
             end
             @metrics[light_name] = Metrics.new
           end
@@ -141,7 +148,7 @@ module Stoplight
         # @return [void]
         def record_success(config)
           light_name = config.name
-          current_time = self.current_time
+          current_time = clock.current_time
 
           synchronize do
             @successes[light_name].increment if config.window_size
@@ -162,7 +169,7 @@ module Stoplight
         # @return [void]
         def record_recovery_probe_failure(config, exception)
           light_name = config.name
-          current_time = self.current_time
+          current_time = clock.current_time
           failure = Domain::Failure.from_error(exception, time: current_time)
 
           synchronize do
@@ -181,7 +188,7 @@ module Stoplight
         # @return [void]
         def record_recovery_probe_success(config)
           light_name = config.name
-          current_time = self.current_time
+          current_time = clock.current_time
 
           synchronize do
             metrics = @recovery_metrics[light_name]
@@ -232,11 +239,11 @@ module Stoplight
         # @return [Boolean] true if this is the first instance to detect this transition
         def transition_to_color(config, color)
           case color
-          when Domain::Color::GREEN
+          when Color::GREEN
             transition_to_green(config)
-          when Domain::Color::YELLOW
+          when Color::YELLOW
             transition_to_yellow(config)
-          when Domain::Color::RED
+          when Color::RED
             transition_to_red(config)
           else
             raise ArgumentError, "Invalid color: #{color}"
@@ -244,12 +251,12 @@ module Stoplight
         end
 
         # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockToken, nil]
+        # @return [Stoplight::Infrastructure::Memory::DataStore::RecoveryLockToken, nil]
         def acquire_recovery_lock(config)
           recovery_lock_store.acquire_lock(config.name)
         end
 
-        # @param lock [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockToken]
+        # @param lock [Stoplight::Infrastructure::Memory::DataStore::RecoveryLockToken]
         # @return [void]
         def release_recovery_lock(lock)
           recovery_lock_store.release_lock(lock)
@@ -261,7 +268,7 @@ module Stoplight
         # @return [Boolean] true if this is the first instance to detect this transition
         private def transition_to_green(config)
           light_name = config.name
-          current_time = self.current_time
+          current_time = clock.current_time
 
           synchronize do
             state = @states[light_name]
@@ -284,7 +291,7 @@ module Stoplight
         # @return [Boolean] true if this is the first instance to detect this transition
         private def transition_to_yellow(config)
           light_name = config.name
-          current_time = self.current_time
+          current_time = clock.current_time
 
           synchronize do
             state = @states[light_name]
@@ -309,7 +316,7 @@ module Stoplight
         # @return [Boolean] true if this is the first instance to detect this transition
         private def transition_to_red(config)
           light_name = config.name
-          current_time = self.current_time
+          current_time = clock.current_time
           recovery_scheduled_after = current_time + config.cool_off_time
 
           synchronize do
@@ -328,11 +335,8 @@ module Stoplight
             end
           end
         end
-
-        private def current_time
-          Time.now
-        end
       end
+      # steep:ignore:end
     end
   end
 end

data/lib/stoplight/infrastructure/memory/storage/recovery_lock.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        # Process-local recovery lock using Ruby's Thread::Mutex.
+        #
+        # This only serializes recovery within a single Ruby process.
+        # Multiple processes/servers will NOT coordinate - each process
+        # can send probes independently.
+        #
+        class RecoveryLock
+          def initialize
+            @lock = Thread::Mutex.new
+          end
+
+          def acquire_lock
+            if lock.try_lock
+              Domain::Storage::RecoveryLockToken.new
+            end
+          end
+
+          def release_lock(_recovery_lock_token)
+            lock.unlock
+          end
+
+          private
+
+          attr_reader :lock
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/memory/storage/recovery_metrics.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        # When a circuit is RED (open), Stoplight periodically sends "recovery probes"
+        # to test whether the protected service has recovered. These test requests have
+        # different semantics than normal requests and their metrics are tracked separately.
+        #
+        class RecoveryMetrics < UnboundedMetrics
+        end
+      end
+    end
+  end
+end