stoplight 5.7.0 → 5.8.2

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

@@ -4,7 +4,7 @@ require "forwardable"
 
 module Stoplight
   module Infrastructure
-    module DataStore
+    module Redis
       # == Errors
       # All errors are stored in the sorted set where keys are serialized errors and
       # values (Redis uses "score" term) contain integer representations of the time
@@ -17,7 +17,8 @@ module Stoplight
       # of errors happened within last +config.window_size+ seconds (by default infinity).
       #
       # @see Base
-      class Redis < Domain::DataStore
+      # steep:ignore:start
+      class DataStore
         extend Forwardable
 
         class << self
@@ -30,6 +31,8 @@ module Stoplight
             [KEY_PREFIX, *pieces].join(KEY_SEPARATOR)
           end
 
+          METRICS_RETENTION_TIME = 60 * 60 * 24 # 1 day
+
           # Retrieves the list of Redis bucket keys required to cover a specific time window.
           #
           # @param light_name [String] The name of the light (used as part of the Redis key).
@@ -40,7 +43,7 @@ module Stoplight
           # @api private
           def buckets_for_window(light_name, metric:, window_end:, window_size:)
             window_end_ts = window_end.to_i
-            window_start_ts = window_end_ts - [window_size, Domain::DataStore::METRICS_RETENTION_TIME].compact.min.to_i
+            window_start_ts = window_end_ts - [window_size, METRICS_RETENTION_TIME].compact.min.to_i
 
             # Find bucket timestamps that contain any part of the window
             start_bucket = (window_start_ts / bucket_size) * bucket_size
@@ -75,11 +78,11 @@ module Stoplight
         KEY_PREFIX = %w[stoplight v5].join(KEY_SEPARATOR)
 
         # @!attribute recovery_lock_store
-        #   @return [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockStore]
+        #   @return [Stoplight::Infrastructure::Redis::DataStore::RecoveryLockStore]
         protected attr_reader :recovery_lock_store
 
         # @!attribute scripting
-        #   @return [Stoplight::Infrastructure::DataStore::Redis::Scripting]
+        #   @return [Stoplight::Infrastructure::Redis::DataStore::Scripting]
         protected attr_reader :scripting
 
         # @!attribute redis
@@ -90,12 +93,18 @@ module Stoplight
         #   @return [Boolean]
         protected attr_reader :warn_on_clock_skew
 
+        # @!attribute clock
+        #   @return [Stoplight::Domain::_Clock]
+        private attr_reader :clock
+
         # @param redis [::Redis, ConnectionPool<::Redis>]
-        # @param recovery_lock_store [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockStore]
+        # @param recovery_lock_store [Stoplight::Infrastructure::Redis::DataStore::RecoveryLockStore]
         # @param warn_on_clock_skew [Boolean] (true) Whether to warn about clock skew between Redis and
-        # @param scripting [Stoplight::Infrastructure::DataStore::Redis::Scripting]
+        # @param scripting [Stoplight::Infrastructure::Redis::DataStore::Scripting]
+        # @param clock [Stoplight::Domain::_Clock]
         #   the application server
-        def initialize(redis:, recovery_lock_store:, scripting:, warn_on_clock_skew: true)
+        def initialize(redis:, recovery_lock_store:, scripting:, clock:, warn_on_clock_skew: true)
+          @clock = clock
           @warn_on_clock_skew = warn_on_clock_skew
           @redis = redis
           @recovery_lock_store = recovery_lock_store
@@ -117,11 +126,11 @@ module Stoplight
         end
 
         # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Domain::Metrics]
+        # @return [Stoplight::Domain::MetricsSnapshot]
         def get_metrics(config)
           config.name
 
-          window_end_ts = current_time.to_f
+          window_end_ts = clock.current_time.to_f
           window_start_ts = window_end_ts - config.window_size.to_i
 
           if config.window_size
@@ -149,18 +158,18 @@ module Stoplight
           consecutive_errors = config.window_size ? [consecutive_errors.to_i, errors].min : consecutive_errors.to_i
           consecutive_successes = config.window_size ? [consecutive_successes.to_i, successes].min : consecutive_successes.to_i
 
-          Domain::Metrics.new(
+          Domain::MetricsSnapshot.new(
             successes: (successes if config.window_size),
             errors: (errors if config.window_size),
             consecutive_errors:,
             consecutive_successes:,
             last_error: deserialize_failure(last_error_json),
-            last_success_at: (Time.at(last_success_at.to_f) if last_success_at)
+            last_success_at: (clock.at(last_success_at.to_f) if last_success_at)
           )
         end
 
         # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Domain::Metrics]
+        # @return [Stoplight::Domain::MetricsSnapshot]
         def get_recovery_metrics(config)
           last_success_at, last_error_json, consecutive_errors, consecutive_successes = @redis.with do |client|
             client.hmget(
@@ -169,12 +178,12 @@ module Stoplight
             )
           end
 
-          Domain::Metrics.new(
+          Domain::MetricsSnapshot.new(
             successes: nil, errors: nil,
             consecutive_errors: consecutive_errors.to_i,
             consecutive_successes: consecutive_successes.to_i,
             last_error: deserialize_failure(last_error_json),
-            last_success_at: (Time.at(last_success_at.to_f) if last_success_at)
+            last_success_at: (clock.at(last_success_at.to_f) if last_success_at)
           )
         end
 
@@ -190,17 +199,17 @@ module Stoplight
           recovery_started_at = recovery_started_at_raw&.to_f
 
           Domain::StateSnapshot.new(
-            breached_at: (Time.at(breached_at) if breached_at),
-            locked_state: locked_state || Domain::State::UNLOCKED,
-            recovery_scheduled_after: (Time.at(recovery_scheduled_after) if recovery_scheduled_after),
-            recovery_started_at: (Time.at(recovery_started_at) if recovery_started_at),
-            time: current_time
+            breached_at: (clock.at(breached_at) if breached_at),
+            locked_state: locked_state || State::UNLOCKED,
+            recovery_scheduled_after: (clock.at(recovery_scheduled_after) if recovery_scheduled_after),
+            recovery_started_at: (clock.at(recovery_started_at) if recovery_started_at),
+            time: clock.current_time
           )
         end
 
         def clear_metrics(config)
           if config.window_size
-            window_end_ts = current_time.to_i
+            window_end_ts = clock.current_time.to_i
             @redis.with do |client|
               client.multi do |tx|
                 tx.unlink(
@@ -223,26 +232,12 @@ module Stoplight
           end
         end
 
-        private def state_snapshot_from_hash(data, time: current_time)
-          breached_at = data[:breached_at]&.to_f
-          recovery_scheduled_after = data[:recovery_scheduled_after]&.to_f
-          recovery_started_at = data[:recovery_started_at]&.to_f
-
-          Domain::StateSnapshot.new(
-            breached_at: (Time.at(breached_at) if breached_at),
-            locked_state: data[:locked_state] || Domain::State::UNLOCKED,
-            recovery_scheduled_after: (Time.at(recovery_scheduled_after) if recovery_scheduled_after),
-            recovery_started_at: (Time.at(recovery_started_at) if recovery_started_at),
-            time:
-          )
-        end
-
         # @param config [Stoplight::Domain::Config] The light configuration.
         # @param exception [Exception]
         # @return [void]
         def record_failure(config, exception)
-          current_time = self.current_time
-          current_ts = current_time.to_f
+          current_time = clock.current_time
+          current_ts = clock.current_time.to_f
           failure = Domain::Failure.from_error(exception, time: current_time)
 
           scripting.call(
@@ -256,7 +251,7 @@ module Stoplight
         end
 
         def record_success(config, request_id: SecureRandom.hex(12))
-          current_ts = current_time.to_f
+          current_ts = clock.current_time.to_f
 
           scripting.call(
             :record_success,
@@ -274,8 +269,8 @@ module Stoplight
         # @param exception [Exception]
         # @return [void]
         def record_recovery_probe_failure(config, exception)
-          current_time = self.current_time
-          current_ts = current_time.to_f
+          current_time = clock.current_time
+          current_ts = clock.current_time.to_f
           failure = Domain::Failure.from_error(exception, time: current_time)
 
           scripting.call(
@@ -290,7 +285,7 @@ module Stoplight
         # @param config [Stoplight::Domain::Config] The light configuration.
         # @return [void]
         def record_recovery_probe_success(config)
-          current_ts = current_time.to_f
+          current_ts = clock.current_time.to_f
 
           scripting.call(
             :record_recovery_probe_success,
@@ -317,11 +312,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}"
@@ -329,12 +324,12 @@ module Stoplight
         end
 
         # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockToken, nil]
+        # @return [Stoplight::Infrastructure::Redis::DataStore::RecoveryLockToken, nil]
         def acquire_recovery_lock(config)
           recovery_lock_store.acquire_lock(config.name)
         end
 
-        # @param lock [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockToken]
+        # @param lock [Stoplight::Infrastructure::Redis::DataStore::RecoveryLockToken]
         # @return [void]
         def release_recovery_lock(lock)
           recovery_lock_store.release_lock(lock)
@@ -345,7 +340,7 @@ module Stoplight
         # @param config [Stoplight::Domain::Config] The light configuration
         # @return [Boolean] true if this is the first instance to detect this transition
         private def transition_to_green(config)
-          current_ts = current_time.to_f
+          current_ts = clock.current_time.to_f
           meta_key = metadata_key(config)
 
           became_green = scripting.call(
@@ -361,7 +356,7 @@ module Stoplight
         # @param config [Stoplight::Domain::Config] The light configuration
         # @return [Boolean] true if this is the first instance to detect this transition
         private def transition_to_yellow(config)
-          current_ts = current_time.to_f
+          current_ts = clock.current_time.to_f
           meta_key = metadata_key(config)
 
           became_yellow = scripting.call(
@@ -377,7 +372,7 @@ module Stoplight
         # @param config [Stoplight::Domain::Config] The light configuration
         # @return [Boolean] true if this is the first instance to detect this transition
         private def transition_to_red(config)
-          current_ts = current_time.to_f
+          current_ts = clock.current_time.to_f
           meta_key = metadata_key(config)
           recovery_scheduled_after_ts = current_ts + config.cool_off_time
 
@@ -410,7 +405,7 @@ module Stoplight
 
           error_class = error_object["class"]
           error_message = error_object["message"]
-          time = Time.at(object["time"])
+          time = clock.at(object["time"])
 
           Domain::Failure.new(error_class, error_message, time)
         end
@@ -505,7 +500,7 @@ module Stoplight
           return unless should_sample?(0.01) # 1% chance
 
           redis_seconds, _redis_millis = @redis.then(&:time)
-          app_seconds = current_time.to_i
+          app_seconds = clock.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
@@ -514,11 +509,8 @@ module Stoplight
         private def should_sample?(probability)
           rand <= probability
         end
-
-        private def current_time
-          Time.now
-        end
       end
+      # steep:ignore:end
     end
   end
 end

data/lib/stoplight/infrastructure/redis/storage/key_space.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        # Immutable key namespace for a light within a system.
+        #
+        # Produces keys following entity-first structure:
+        #   stoplight:v6:{system_id}:{light_id}:locks:recovery
+        #   stoplight:v6:{system_id}:{light_id}:metrics:successes
+        #   stoplight:v6:{system_id}:{light_id}:state
+        #
+        # Identifiers are derived from SHA-256 and truncated to 12 characters. Collisions are extremely
+        # unlikely at expected system scale.
+        #
+        # @example
+        #   key_space = KeySpace.build(system_name: "payments", light_name: "stripe-api")
+        #   key_space.key(:locks, :recovery)  #=> "stoplight:v6:df384ae97c77:cfe6861fa39e:locks:recovery"
+        #
+        KeySpace = Data.define(:system_id, :light_id)
+
+        class KeySpace
+          # @!attribute system_id
+          #   12-char hex identifier for the system
+          #
+          # @!attribute light_id
+          #   12-char hex identifier for the light
+
+          class << self
+            def build(system_name:, light_name:) = new(
+              system_id: hash_name(system_name),
+              light_id: hash_name(light_name)
+            )
+
+            # Generates a truncated SHA256 hash for use in Redis keys.
+            def hash_name(name) = Digest::SHA256.hexdigest(name.to_s)[0, 12] #: String
+          end
+
+          # Builds a Redis key within this namespace.
+          #
+          # @param pieces  Key segments to append
+          # @return  Full Redis key
+          def key(*pieces) = [:stoplight, :v5, system_id, "{#{light_id}}", *pieces].join(":")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        class Metrics
+          def serialize_exception(exception, timestamp:)
+            JSON.generate(
+              {
+                error: {
+                  class: exception.class.name,
+                  message: exception.message
+                },
+                time: timestamp
+              }
+            )
+          end
+
+          def deserialize_failure(failure_json)
+            return if failure_json.nil?
+
+            object = JSON.parse(failure_json)
+            error_object = object["error"]
+
+            error_class = error_object["class"]
+            error_message = error_object["message"]
+            time = Time.at(object["time"])
+
+            Domain::Failure.new(error_class, error_message, time)
+          end
+
+          private def metrics_ttl = 86400 * 7 # 7 days
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/redis/storage/recovery_lock/release_lock.lua

@@ -0,0 +1,6 @@
+local token = ARGV[1]
+local lock_key = KEYS[1]
+
+if redis.call("get", lock_key) == token then
+  return redis.call("del", lock_key)
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        # Distributed recovery lock using Redis SET NX (set-if-not-exists).
+        #
+        # Lock Acquisition:
+        # - Uses unique UUID token to prevent accidental release of others' locks
+        # - Atomic SET with NX flag ensures only one process acquires recovery_lock
+        # - TTL (px: lock_timeout) auto-releases recovery_lock if process crashes
+        #
+        # Lock Release:
+        # - Lua script ensures only token holder can release (token comparison)
+        # - Best-effort release; TTL cleanup handles failures
+        #
+        # Failure Modes:
+        # - Lock contention: Returns false, caller should skip probe
+        # - Redis unavailable: raises an error and let caller decide
+        # - Crashed holder: raises an error and let caller decide. Lock auto-expires after lock_timeout
+        # - Release failure: Lock auto-expires after lock_timeout
+        #
+        class RecoveryLock
+          def initialize(config:, redis:, scripting:, key_space:)
+            @config = config
+            @redis = redis
+            @scripting = scripting
+            @key_space = key_space
+          end
+
+          def acquire_lock
+            recovery_lock = Domain::Storage::RecoveryLockToken.new
+
+            acquired = redis.then do |client|
+              client.set(lock_key, recovery_lock.token, nx: true, px: lock_timeout)
+            end
+
+            recovery_lock if acquired
+          end
+
+          # @param recovery_lock [Stoplight::Infrastructure::Redis::DataStore::RecoveryLockToken]
+          # @return [void]
+          def release_lock(recovery_lock)
+            scripting.call(
+              :"recovery_lock/release_lock",
+              keys: [lock_key], args: [recovery_lock.token]
+            )
+          end
+
+          private
+
+          attr_reader :config
+          attr_reader :redis
+          attr_reader :scripting
+          attr_reader :key_space
+
+          def lock_key = key_space.key(:locks, :recovery)
+          def lock_timeout = config.cool_off_time_in_milliseconds
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      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
+          def initialize(redis:, scripting:, key_space:, clock:)
+            super
+            @metrics_key = key_space.key(:recovery_metrics)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/redis/storage/scripting.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        class Scripting < Infrastructure::Redis::DataStore::Scripting
+          SCRIPTS_ROOT = __dir__ => String
+          private_constant :SCRIPTS_ROOT
+
+          class << self
+            def default_scripts_root = SCRIPTS_ROOT
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/redis/storage/state/transition_to_green.lua

@@ -0,0 +1,10 @@
+local meta_key = KEYS[1]
+local current_ts = tonumber(ARGV[1])
+
+--  1 if the field is a new field in the hash and the value was set
+local became_green = redis.call('HSETNX', meta_key, 'recovered_at', current_ts)
+
+if became_green == 1 then
+  redis.call("HDEL", meta_key, 'recovery_started_at', 'recovery_scheduled_after', 'breached_at')
+end
+return became_green

data/lib/stoplight/infrastructure/redis/storage/state/transition_to_red.lua

@@ -0,0 +1,10 @@
+local meta_key = KEYS[1]
+local current_ts = tonumber(ARGV[1])
+local recovery_scheduled_after_ts = tonumber(ARGV[2])
+
+--  1 if the field is a new field in the hash and the value was set
+local became_red = redis.call('HSETNX', meta_key, 'breached_at', current_ts)
+
+redis.call('HSET', meta_key, 'recovery_scheduled_after', recovery_scheduled_after_ts)
+redis.call("HDEL", meta_key, "recovery_started_at", "recovered_at")
+return became_red

data/lib/stoplight/infrastructure/redis/storage/state/transition_to_yellow.lua

@@ -0,0 +1,9 @@
+local meta_key = KEYS[1]
+local current_ts = tonumber(ARGV[1])
+
+-- HSETNX returns 1 if field is new and was set, 0 if field already exists
+local became_yellow = redis.call('HSETNX', meta_key, 'recovery_started_at', current_ts)
+if became_yellow == 1 then
+  redis.call('HDEL', meta_key, 'recovery_scheduled_after', 'breached_at', 'recovered_at')
+end
+return became_yellow

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        # Redis-backed state storage for a single circuit breaker.
+        #
+        # Manages circuit breaker state transitions using Redis hashes and Lua scripts
+        # for atomic operations. Ensures notification deduplication across distributed
+        # processes - when multiple processes detect the same circuit condition,
+        # only one will receive +true+ from transition methods.
+        #
+        # All state is stored in a single Redis hash with fields:
+        # - +locked_state+: forced lock (UNLOCKED, LOCKED_GREEN, LOCKED_RED)
+        # - +breached_at+: timestamp (float) when circuit opened
+        # - +recovery_scheduled_after+: timestamp (float) when recovery probe allowed
+        # - +recovery_started_at+: timestamp (float) when recovery probe began
+        #
+        # @example Basic usage
+        #   state = State.new(
+        #     clock: SystemClock.new,
+        #     redis: Redis.new,
+        #     scripting: Scripting.new(redis:),
+        #     key_space: KeySpace.build(light_name: "payments", system_name: "main"),
+        #     cool_off_time: 60
+        #   )
+        #
+        #   # Multiple processes may call this concurrently
+        #   if state.transition_to_color(Color::RED)
+        #     # Only one process reaches here - send notification
+        #     notifier.notify("payments", :opened)
+        #   end
+        #
+        # @note Thread safety is guaranteed by Redis's single-threaded execution model
+        #   and the use of Lua scripts for atomic multistep operations.
+        #
+        # @see Stoplight::Memory::State for the in-memory equivalent
+        # @see Stoplight::Domain::StateSnapshot for the structure of state snapshots
+        #
+        class State
+          def initialize(clock:, redis:, scripting:, key_space:, cool_off_time:)
+            @redis = redis
+            @scripting = scripting
+            @key_space = key_space
+            @clock = clock
+            @cool_off_time = cool_off_time
+
+            @state_key = key_space.key(:state)
+          end
+
+          def set_state(state)
+            redis.with do |client|
+              client.hset(state_key, "locked_state", state)
+            end
+            state
+          end
+
+          def state_snapshot
+            breached_at_raw, locked_state, recovery_scheduled_after_raw, recovery_started_at_raw = redis.with do |client|
+              client.hmget(state_key, :breached_at, :locked_state, :recovery_scheduled_after, :recovery_started_at)
+            end
+
+            Domain::StateSnapshot.new(
+              breached_at: breached_at_raw && clock.at(breached_at_raw.to_f),
+              locked_state: locked_state || Stoplight::State::UNLOCKED,
+              recovery_scheduled_after: recovery_scheduled_after_raw && clock.at(recovery_scheduled_after_raw.to_f),
+              recovery_started_at: recovery_started_at_raw && clock.at(recovery_started_at_raw.to_f),
+              time: clock.current_time
+            )
+          end
+
+          def clear
+            redis.with do |client|
+              client.del(state_key)
+            end
+          end
+
+          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
+
+          private
+
+          attr_reader :redis
+          attr_reader :scripting
+          attr_reader :key_space
+          attr_reader :clock
+          attr_reader :cool_off_time
+          attr_reader :state_key
+
+          # Transitions to GREEN state and ensures only one notification
+          #
+          def transition_to_green
+            became_green = scripting.call(
+              :"state/transition_to_green",
+              args: [clock.current_time.to_f],
+              keys: [state_key]
+            )
+            became_green == 1
+          end
+
+          # Transitions to YELLOW (recovery) state and ensures only one notification
+          #
+          def transition_to_yellow
+            became_yellow = scripting.call(
+              :"state/transition_to_yellow",
+              args: [clock.current_time.to_f],
+              keys: [state_key]
+            )
+            became_yellow == 1
+          end
+
+          # Transitions to RED state and ensures only one notification
+          #
+          def transition_to_red
+            current_ts = clock.current_time.to_f
+            recovery_scheduled_after_ts = current_ts + cool_off_time
+
+            became_red = scripting.call(
+              :"state/transition_to_red",
+              args: [current_ts, recovery_scheduled_after_ts],
+              keys: [state_key]
+            )
+
+            became_red == 1
+          end
+        end
+      end
+    end
+  end
+end