stoplight 5.7.0 → 5.8.0

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        # Thread-safe in-memory state storage for a single light.
+        #
+        # Manages light state transitions and ensures notification
+        # deduplication through atomic transition detection. Each transition
+        # method returns whether the calling thread was first to trigger that
+        # transition, enabling exactly-once notification semantics.
+        #
+        # @example Basic usage
+        #   state = State.new(clock: SystemClock.new, cool_off_time: 60)
+        #
+        #   # Multiple threads may call this concurrently
+        #   if state.transition_to_color(Color::RED)
+        #     # Only one thread reaches here - send notification
+        #     notifier.notify(circuit_name, :opened)
+        #   end
+        #
+        # @example Inspecting current state
+        #   snapshot = state.state_snapshot
+        #   snapshot.locked_state        # => "unlocked"
+        #   snapshot.breached_at         # => 2025-01-15 10:30:00 UTC
+        #   snapshot.recovery_scheduled_after  # => 2025-01-15 10:31:00 UTC
+        #
+        # @see Stoplight::Domain::StateSnapshot for the structure of state snapshots
+        #
+        class State
+          def initialize(clock:, cool_off_time:)
+            @locked_state = Stoplight::State::UNLOCKED
+            @mutex = Thread::Mutex.new
+            @clock = clock
+            @cool_off_time = cool_off_time
+          end
+
+          def set_state(state)
+            mutex.synchronize do
+              self.locked_state = state
+            end
+          end
+
+          def state_snapshot
+            mutex.synchronize do
+              Domain::StateSnapshot.new(
+                time: clock.current_time,
+                locked_state:,
+                recovery_scheduled_after:,
+                recovery_started_at:,
+                breached_at:
+              )
+            end
+          end
+
+          # Combined method that performs the state transition based on color
+          #
+          # @param color The color to transition to ("GREEN", "YELLOW", or "RED")
+          # @return true if this is the first instance to detect this transition
+          def transition_to_color(color)
+            case color
+            when Color::GREEN
+              transition_to_green
+            when Color::YELLOW
+              transition_to_yellow
+            when Color::RED
+              transition_to_red
+            else
+              raise ArgumentError, "Invalid color: #{color}"
+            end
+          end
+
+          def clear
+            mutex.synchronize do
+              self.locked_state = Stoplight::State::UNLOCKED
+              self.recovered_at = nil
+              self.recovery_scheduled_after = nil
+              self.breached_at = nil
+              self.recovery_started_at = nil
+            end
+          end
+
+          private
+
+          attr_accessor :locked_state
+          attr_accessor :recovered_at
+          attr_accessor :recovery_scheduled_after
+          attr_accessor :recovery_started_at
+          attr_accessor :breached_at
+          attr_reader :mutex
+          attr_reader :clock
+          attr_reader :cool_off_time
+
+          # Transitions to GREEN state and ensures only one notification
+          #
+          # @return true if this is the first instance to detect this transition
+          def transition_to_green
+            mutex.synchronize do
+              if recovered_at
+                false
+              else
+                self.recovered_at = clock.current_time
+                self.recovery_started_at = nil
+                self.breached_at = nil
+                self.recovery_scheduled_after = nil
+                true
+              end
+            end
+          end
+
+          # Transitions to YELLOW (recovery) state and ensures only one notification
+          #
+          # @return true if this is the first instance to detect this transition
+          def transition_to_yellow
+            mutex.synchronize do
+              if recovery_started_at.nil?
+                self.recovery_started_at = clock.current_time
+                self.recovery_scheduled_after = nil
+                self.recovered_at = nil
+                self.breached_at = nil
+                true
+              else
+                self.recovery_scheduled_after = nil
+                self.recovered_at = nil
+                self.breached_at = nil
+                false
+              end
+            end
+          end
+
+          # Transitions to RED state and ensures only one notification
+          #
+          # @return true if this is the first instance to detect this transition
+          def transition_to_red
+            mutex.synchronize do
+              current_time = clock.current_time
+
+              self.recovery_scheduled_after = current_time + cool_off_time
+              self.recovery_started_at = nil
+              self.recovered_at = nil
+
+              if breached_at
+                false
+              else
+                self.breached_at = current_time
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        # Thread-safe metrics storage for consecutive-error light strategies.
+        #
+        # Unlike +WindowMetrics+, this class does not track event counts within
+        # a time window. It only maintains:
+        # - Consecutive success/failure counters (reset on opposite outcome)
+        # - Most recent error with timestamp
+        # - Most recent success timestamp
+        #
+        # This is appropriate for circuit breakers using threshold-based strategies
+        # (e.g., "open after 5 consecutive failures") rather than rate-based
+        # strategies (e.g., "open when error rate exceeds 50%").
+        #
+        # @note The +#errors+ and +#successes+ fields in the returned +Stoplight::Domain::Metrics+
+        #   are always +nil+ since totals aren't tracked.
+        #
+        class UnboundedMetrics
+          def initialize(clock:)
+            initialize_metrics
+            @clock = clock
+            @mutex = Mutex.new
+          end
+
+          # Get metrics for the current light
+          def metrics_snapshot
+            mutex.synchronize do
+              Domain::MetricsSnapshot.new(
+                errors: nil,
+                successes: nil,
+                consecutive_errors: consecutive_errors.to_i,
+                consecutive_successes: consecutive_successes.to_i,
+                last_error: last_error,
+                last_success_at: last_success_at
+              )
+            end
+          end
+
+          # Records successful circuit breaker execution
+          def record_success
+            current_time = clock.current_time
+
+            mutex.synchronize do
+              if last_success_at.nil? || current_time > last_success_at
+                self.last_success_at = current_time
+              end
+
+              self.consecutive_errors = 0
+              self.consecutive_successes += 1
+            end
+          end
+
+          # Records failed circuit breaker execution
+          def record_failure(exception)
+            current_time = clock.current_time
+            failure = Domain::Failure.from_error(exception, time: current_time)
+            last_error_at = self.last_error_at
+
+            mutex.synchronize do
+              if last_error_at.nil? || failure.occurred_at > last_error_at
+                self.last_error = failure
+              end
+
+              self.consecutive_errors += 1
+              self.consecutive_successes = 0
+            end
+          end
+
+          def clear
+            mutex.synchronize do
+              initialize_metrics
+            end
+          end
+
+          private
+
+          attr_accessor :consecutive_errors
+          attr_accessor :consecutive_successes
+          attr_accessor :last_error
+          attr_accessor :last_success_at
+
+          attr_reader :mutex
+          attr_reader :clock
+
+          def initialize_metrics
+            @consecutive_errors = 0
+            @consecutive_successes = 0
+            @last_error = nil
+            @last_success_at = nil
+          end
+
+          def last_error_at
+            last_error&.occurred_at
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        # Thread-safe in-memory storage for time-windowed light @
+        #
+        # This class tracks success and failure counts within a sliding time window,
+        # along with consecutive counters and the most recent error. It's designed
+        # for single-process deployments where distributed coordination isn't needed.
+        #
+        # The sliding window approach provides more accurate error rate calculations
+        # than consecutive-error counting, as it considers the full picture of
+        # recent traffic rather than just the most recent streak.
+        #
+        # @note All public methods are synchronized via mutex to ensure thread safety.
+        #
+        class WindowMetrics
+          def initialize(window_size:, clock:)
+            @clock = clock
+            @mutex = Mutex.new
+            @window_size = window_size
+
+            initialize_metrics
+          end
+
+          # Get metrics for the current light
+          def metrics_snapshot
+            mutex.synchronize do
+              window_start = (clock.current_time - @window_size)
+              errors = @errors.sum_in_window(window_start)
+              successes = @successes.sum_in_window(window_start)
+
+              Domain::MetricsSnapshot.new(
+                errors:,
+                successes:,
+                consecutive_errors: [@consecutive_errors, errors].min,
+                consecutive_successes: [@consecutive_successes, successes].min,
+                last_error: @last_error,
+                last_success_at: @last_success_at
+              )
+            end
+          end
+
+          # Records successful circuit breaker execution
+          def record_success
+            mutex.synchronize do
+              current_time = clock.current_time
+              @successes.increment
+
+              if @last_success_at.nil? || current_time > T.must(@last_success_at)
+                @last_success_at = current_time
+              end
+
+              @consecutive_errors = 0
+              @consecutive_successes += 1
+            end
+          end
+
+          # Records failed circuit breaker execution
+          def record_failure(exception)
+            mutex.synchronize do
+              @errors.increment
+
+              failure = Domain::Failure.from_error(exception, time: clock.current_time)
+              last_error_at = @last_error&.occurred_at
+
+              if last_error_at.nil? || failure.occurred_at > last_error_at
+                @last_error = failure
+              end
+
+              @consecutive_errors += 1
+              @consecutive_successes = 0
+            end
+          end
+
+          def clear
+            mutex.synchronize do
+              initialize_metrics
+            end
+          end
+
+          private
+
+          attr_reader :mutex
+          attr_reader :clock
+
+          def initialize_metrics
+            @consecutive_errors = 0
+            @consecutive_successes = 0
+            @last_error = nil
+            @last_success_at = nil
+            @successes = Infrastructure::Memory::DataStore::SlidingWindow.new(clock:)
+            @errors = Infrastructure::Memory::DataStore::SlidingWindow.new(clock:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/notifier/fail_safe.rb

@@ -8,40 +8,29 @@ module Stoplight
       # handle failures.
       #
       # @api private
-      class FailSafe < Domain::StateTransitionNotifier
-        # @!attribute [r] notifier
-        #   @return [Stoplight::Domain::StateTransitionNotifier] The underlying notifier being wrapped.
+      class FailSafe
+        # The underlying notifier being wrapped.
         attr_reader :notifier
-
-        # @!attribute [r] error_notifier
-        #   @return [Stoplight::Domain::StateTransitionNotifier] The underlying notifier being wrapped.
+        # The underlying notifier being wrapped.
         attr_reader :error_notifier
 
-        # Initializes a new instance of the +FailSafe+ class.
-        #
-        # @param notifier [Stoplight::Domain::StateTransitionNotifier] The notifier to wrap.
-        # @param error_notifier [Proc] called when wrapped data store fails
+        # @param notifier The notifier to wrap.
+        # @param error_notifier called when wrapped data store fails
         def initialize(notifier:, error_notifier:)
           @notifier = notifier
           @error_notifier = error_notifier
         end
 
         # Sends a notification using the wrapped notifier with fail-safe mechanisms.
-        #
-        # @param config [Stoplight::Domain::Config] The light configuration.
-        # @param from_color [String] The initial color of the light.
-        # @param to_color [String] The target color of the light.
-        # @param error [Exception, nil] An optional error to include in the notification.
-        # @return [void]
-        def notify(config, from_color, to_color, error = nil)
+        def notify(info, from_color, to_color, error = nil)
           fallback = proc do |exception|
             error_notifier.call(exception) if exception
             nil
-          end
+          end #: ^(StandardError?) -> void
 
           circuit_breaker.run(fallback) do
-            notifier.notify(config, from_color, to_color, error)
-          end
+            notifier.notify(info, from_color, to_color, error)
+          end #: void
         end
 
         # @return [Boolean]
@@ -49,7 +38,6 @@ module Stoplight
           other.is_a?(self.class) && notifier == other.notifier
         end
 
-        # @return [Stoplight::Light] The circuit breaker used to handle failures.
         private def circuit_breaker
           @circuit_breaker ||= Stoplight.system_light(
             "stoplight:notifier:fail_safe:#{notifier.class.name}",

data/lib/stoplight/infrastructure/notifier/generic.rb

@@ -39,10 +39,8 @@ module Stoplight
       #     light.run { raise 'Simulated failure' } rescue nil
       #     light.run { raise 'Simulated failure' } rescue nil
       #
-      module Generic # rubocop:disable Style/Documentation
-        # @!attribute [r] formatter
-        #   @return [Proc] The formatter used to generate notification messages.
-        #   @see Stoplight::Default::FORMATTER
+      module Generic
+        # The formatter used to generate notification messages.
         attr_reader :formatter
 
         DEFAULT_FORMATTER = lambda do |light, from_color, to_color, error|
@@ -52,8 +50,8 @@ module Stoplight
         end
         public_constant :DEFAULT_FORMATTER
 
-        # @param object [Object] The object used by the notifier (e.g., a logger or external service).
-        # @param formatter [Proc, nil] A custom formatter for generating notification messages.
+        # @param object The object used by the notifier (e.g., a logger or external service).
+        # @param formatter A custom formatter for generating notification messages.
         #   If no formatter is provided, the default formatter is used.
         def initialize(object, formatter = nil)
           @object = object
@@ -61,12 +59,6 @@ module Stoplight
         end
 
         # Sends a notification when a Stoplight changes state.
-        #
-        # @param light [Light] The Stoplight instance triggering the notification.
-        # @param from_color [String] The previous state color of the Stoplight.
-        # @param to_color [String] The new state color of the Stoplight.
-        # @param error [Exception, nil] The error (if any) that caused the state change.
-        # @return [String] The formatted notification message.
         def notify(light, from_color, to_color, error)
           message = formatter.call(light, from_color, to_color, error)
           put(message)
@@ -77,8 +69,6 @@ module Stoplight
 
         # Processes the notification message.
         #
-        # @param message [String] The notification message to be processed.
-        # @raise [NotImplementedError] If the method is not implemented in a subclass.
         # :nocov:
         def put(message)
           raise NotImplementedError

data/lib/stoplight/infrastructure/notifier/io.rb

@@ -4,10 +4,9 @@ module Stoplight
   module Infrastructure
     module Notifier
       # @see Base
-      class IO < Domain::StateTransitionNotifier
+      class IO
         include Generic
 
-        # @return [::IO]
         def io
           @object
         end

data/lib/stoplight/infrastructure/notifier/logger.rb

@@ -4,10 +4,9 @@ module Stoplight
   module Infrastructure
     module Notifier
       # @see Base
-      class Logger < Domain::StateTransitionNotifier
+      class Logger
         include Generic
 
-        # @return [::Logger]
         def logger
           @object
         end

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

@@ -5,9 +5,9 @@ require "forwardable"
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Redis
-        # Distributed recovery recovery_lock using Redis SET NX (set-if-not-exists).
+    module Redis
+      class DataStore
+        # Distributed recovery lock using Redis SET NX (set-if-not-exists).
         #
         # Lock Acquisition:
         # - Uses unique UUID token to prevent accidental release of others' locks
@@ -25,29 +25,12 @@ module Stoplight
         # - Release failure: Lock auto-expires after lock_timeout
         #
         class RecoveryLockStore
-          # @!attribute redis
-          #   @return [RedisClient]
-          protected attr_reader :redis
-
-          # @!attribute lock_timeout
-          #   @return [Integer]
-          protected attr_reader :lock_timeout
-
-          # @!attribute scripting
-          #   @return [Stoplight::Infrastructure::DataStore::Redis::Scripting]
-          protected attr_reader :scripting
-
-          # @param redis [RedisClient | ConnectionPool]
-          # @param lock_timeout [Integer] recovery_lock timeout in milliseconds
-          # @param scripting [Stoplight::Infrastructure::DataStore::Redis::Scripting]
           def initialize(redis:, lock_timeout:, scripting:)
             @redis = redis
             @lock_timeout = lock_timeout
             @scripting = scripting
           end
 
-          # @param light_name [String]
-          # @return [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockToken, nil]
           def acquire_lock(light_name)
             recovery_lock = RecoveryLockToken.new(light_name:)
 
@@ -58,14 +41,18 @@ module Stoplight
             recovery_lock if acquired
           end
 
-          # @param recovery_lock [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockToken]
-          # @return [void]
           def release_lock(recovery_lock)
             scripting.call(
               :release_lock,
               keys: [recovery_lock.lock_key], args: [recovery_lock.token]
             )
           end
+
+          protected
+
+          attr_reader :redis
+          attr_reader :lock_timeout
+          attr_reader :scripting
         end
       end
     end

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

@@ -1,24 +1,13 @@
 # frozen_string_literal: true
 
 require "securerandom"
-require "forwardable"
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Redis
-        class RecoveryLockToken < Domain::RecoveryLockToken
-          extend Forwardable
-
-          def_delegator "Stoplight::Infrastructure::DataStore::Redis", :key
-          private :key
-
-          # @!attribute light_name
-          #   @return [String]
+    module Redis
+      class DataStore
+        class RecoveryLockToken
           attr_reader :light_name
-
-          # @!attribute token
-          #   @return [String]
           attr_reader :token
 
           # @param light_name [String]
@@ -28,6 +17,10 @@ module Stoplight
           end
 
           def lock_key = key(:locks, :recovery, light_name)
+
+          private def key(*parts)
+            Stoplight::Infrastructure::Redis::DataStore.key(*parts)
+          end
         end
       end
     end

data/lib/stoplight/infrastructure/{data_store/redis → redis/data_store}/scripting.rb

@@ -2,8 +2,8 @@
 
 module Stoplight
   module Infrastructure
-    module DataStore
-      class Redis
+    module Redis
+      class DataStore
         # Manages Lua scripts for Redis operations.
         #
         # This class provides execution of Lua scripts by caching their SHA digests
@@ -16,22 +16,15 @@ module Stoplight
         # @note Scripts are loaded lazily on first use and cached in memory
         # @note Script files must be named `<script_name>.lua` and located in scripts_root
         class Scripting
-          SCRIPTS_ROOT = File.join(__dir__, "lua_scripts")
-          # @!attribute scripts_root
-          #   @return [String]
-          protected attr_reader :scripts_root
+          current_dir = __dir__ or raise "Cannot determine script directory"
+          SCRIPTS_ROOT = File.join(current_dir, "lua_scripts")
+          private_constant :SCRIPTS_ROOT
 
-          # @!attribute shas
-          #   @return [Hash{Symbol, String}]
-          private attr_reader :shas
-
-          # @!attribute redis
-          #   @return [RedisClient | ConnectionPool]
-          protected attr_reader :redis
+          class << self
+            def default_scripts_root = SCRIPTS_ROOT
+          end
 
-          # @param redis [RedisClient | ConnectionPool]
-          # @param scripts_root [String]
-          def initialize(redis:, scripts_root: SCRIPTS_ROOT)
+          def initialize(redis:, scripts_root: self.class.default_scripts_root)
             @scripts_root = scripts_root
             @redis = redis
             @shas = {}
@@ -39,7 +32,7 @@ module Stoplight
 
           def call(script_name, keys: [], args: [])
             redis.then do |client|
-              client.evalsha(script_sha(script_name), keys: keys, argv: args)
+              client.evalsha(script_sha(script_name), keys: keys.map(&:to_s), argv: args.map(&:to_s))
             end
           rescue ::Redis::CommandError => error
             if error.message.include?("NOSCRIPT")
@@ -50,18 +43,27 @@ module Stoplight
             end
           end
 
-          private def reload_script(script_name)
+          protected
+
+          attr_reader :scripts_root
+          attr_reader :redis
+
+          private
+
+          attr_reader :shas
+
+          def reload_script(script_name)
             shas.delete(script_name)
             script_sha(script_name)
           end
 
-          private def script_sha(script_name)
+          def script_sha(script_name)
             if shas.key?(script_name)
               shas[script_name]
             else
               script = File.read(File.join(scripts_root, "#{script_name}.lua"))
 
-              shas[script_name] = redis.then { |client| client.script("load", script) }
+              shas[script_name] = redis.then { |client| client.script(:load, script) }
             end
           end
         end