stoplight 5.7.0 → 5.8.2

data/lib/stoplight/infrastructure/redis/storage/unbounded_metrics/record_failure.lua

@@ -0,0 +1,28 @@
+local failure_ts = tonumber(ARGV[1])
+local failure_json = ARGV[2]
+local metrics_ttl = tonumber(ARGV[3])
+
+local metrics_key = KEYS[1]
+
+-- Update metadata
+local meta = redis.call('HMGET', metrics_key, 'last_error_at', 'consecutive_errors')
+local prev_failure_ts = tonumber(meta[1])
+local prev_consecutive_errors = tonumber(meta[2])
+
+if not prev_failure_ts or failure_ts > prev_failure_ts then
+  redis.call(
+    'HSET', metrics_key,
+    'last_error_at', failure_ts,
+    'last_error_json', failure_json,
+    'consecutive_errors', (prev_consecutive_errors or 0) + 1,
+    'consecutive_successes', 0
+  )
+else
+  redis.call(
+    'HSET', metrics_key,
+    'consecutive_errors', (prev_consecutive_errors or 0) + 1,
+    'consecutive_successes', 0
+  )
+end
+
+redis.call('EXPIRE', metrics_key, metrics_ttl)

data/lib/stoplight/infrastructure/redis/storage/unbounded_metrics/record_success.lua

@@ -0,0 +1,26 @@
+local request_ts = tonumber(ARGV[1])
+local metrics_ttl = tonumber(ARGV[2])
+
+local metrics_key = KEYS[1]
+
+-- Update metadata
+local meta = redis.call('HMGET', metrics_key, 'last_success_at', 'consecutive_successes')
+local prev_success_ts = tonumber(meta[1])
+local prev_consecutive_successes = tonumber(meta[2])
+
+if not prev_success_ts or request_ts > prev_success_ts then
+  redis.call(
+    'HSET', metrics_key,
+    'last_success_at', request_ts,
+    'consecutive_errors', 0,
+    'consecutive_successes', (prev_consecutive_successes or 0) + 1
+  )
+else
+  redis.call(
+    'HSET', metrics_key,
+    'consecutive_errors', 0,
+    'consecutive_successes', (prev_consecutive_successes or 0) + 1
+  )
+end
+
+redis.call('EXPIRE', metrics_key, metrics_ttl)

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        # Distributed metrics storage for consecutive-error light strategies.
+        #
+        # This class provides a lightweight alternative to +WindowMetrics+ for circuit
+        # breakers that don't need time-windowed rate calculations. It tracks only:
+        # - Consecutive success/failure counters (reset on opposite outcome)
+        # - Most recent error with timestamp and serialized details
+        # - Most recent success timestamp
+        #
+        # == Storage Structure
+        #
+        # All data is stored in a single Redis hash:
+        #   stoplight:{version}:{system}:{light}:metrics
+        #
+        # Hash fields:
+        # - +last_success_at+: Unix timestamp (float) of most recent success
+        # - +last_error_at+: Unix timestamp (float) of most recent failure
+        # - +last_error_json+: Serialized {Domain::Failure} for error details
+        # - +consecutive_successes+: Integer counter, reset to 0 on failure
+        # - +consecutive_errors+: Integer counter, reset to 0 on success
+        #
+        # == Performance Characteristics
+        #
+        # This implementation is optimized for minimal Redis overhead:
+        # - Single hash key per circuit (vs. multiple ZSETs for +WindowMetrics+)
+        # - O(1) reads and writes
+        # - No time-range queries or bucket management
+        # - Low memory footprint
+        #
+        # == Atomicity
+        #
+        # Record operations use Lua scripts to ensure atomic read-modify-write:
+        # - Consecutive counters are incremented and reset in one round-trip
+        # - "Last" timestamps only update if the new event is more recent,
+        #   preventing out-of-order writes from corrupting state
+        #
+        # == When to Use
+        #
+        # Choose UnboundedMetrics when your circuit breaker strategy is based on
+        # consecutive failures (e.g., "open after 5 failures in a row"). Choose
+        # {WindowMetrics} when you need error rate calculations (e.g., "open when
+        # error rate exceeds 50% over 5 minutes").
+        #
+        # @note The +errors+ and +successes+ fields in the returned +Stoplight::Domain::Metrics+
+        #   are always +nil+ since this class doesn't track windowed totals.
+        #
+        # @note The metrics hash TTL is refreshed on every write operation. Circuits
+        #   with no activity will have their metrics expire, which is generally
+        #   desirable for ephemeral or decommissioned lights.
+        #
+        class UnboundedMetrics < Metrics
+          def initialize(redis:, scripting:, key_space:, clock:)
+            @clock = clock
+            @scripting = scripting
+            @redis = redis
+            @metrics_key = key_space.key(:metrics)
+          end
+
+          # Get metrics for the current light
+          #
+          def metrics_snapshot
+            last_success_at, last_error_json, consecutive_errors, consecutive_successes = redis.with do |client|
+              client.hmget(
+                metrics_key,
+                "last_success_at", "last_error_json", "consecutive_errors", "consecutive_successes"
+              )
+            end
+
+            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: (clock.at(last_success_at.to_f) if last_success_at)
+            )
+          end
+
+          # Records successful circuit breaker execution
+          #
+          def record_success
+            timestamp = clock.current_time.to_f
+
+            scripting.call(
+              :"unbounded_metrics/record_success",
+              args: [timestamp, metrics_ttl],
+              keys: [metrics_key]
+            )
+          end
+
+          # Records failed circuit breaker execution
+          #
+          def record_failure(exception)
+            timestamp = clock.current_time.to_f
+
+            scripting.call(
+              :"unbounded_metrics/record_failure",
+              args: [timestamp, serialize_exception(exception, timestamp:), metrics_ttl],
+              keys: [metrics_key]
+            )
+          end
+
+          def clear
+            redis.with do |client|
+              client.hdel(metrics_key, "last_success_at", "last_error_json", "consecutive_errors", "consecutive_successes")
+            end
+          end
+
+          private
+
+          attr_reader :redis
+          attr_reader :scripting
+          attr_reader :metrics_key
+          attr_reader :clock
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/redis/storage/window_metrics/metrics_snapshot.lua

@@ -0,0 +1,26 @@
+local number_of_metric_buckets = tonumber(ARGV[1])
+local window_start_ts = tonumber(ARGV[2])
+local window_end_ts = tonumber(ARGV[3])
+local metrics_fields = {}
+for idx = 4, #ARGV do
+  table.insert(metrics_fields, ARGV[idx])
+end
+
+local metrics_key = KEYS[1]
+
+local function count_events(start_idx, bucket_count, start_ts)
+  local total = 0
+  for idx = start_idx, start_idx + bucket_count - 1 do
+    total = total + tonumber(redis.call('ZCOUNT', KEYS[idx], start_ts, window_end_ts))
+  end
+  return total
+end
+
+local offset = 2
+local successes = count_events(2, number_of_metric_buckets, window_start_ts)
+
+offset = offset + number_of_metric_buckets
+local errors = count_events(offset, number_of_metric_buckets, window_start_ts)
+
+local metrics = redis.call('HMGET',  metrics_key, unpack(metrics_fields))
+return {successes, errors, unpack(metrics)}

data/lib/stoplight/infrastructure/redis/storage/window_metrics/record_failure.lua

@@ -0,0 +1,36 @@
+local failure_ts = tonumber(ARGV[1])
+local failure_id = ARGV[2]
+local failure_json = ARGV[3]
+local bucket_ttl = tonumber(ARGV[4])
+local metadata_ttl = tonumber(ARGV[5])
+
+local metrics_key = KEYS[1]
+local failures_key = KEYS[2]
+
+-- Record failure
+if failures_key ~= nil then
+  redis.call('ZADD', failures_key, failure_ts, failure_id)
+  redis.call('EXPIRE', failures_key, bucket_ttl) -- Not supported in Redis 6.2:, 'NX')
+end
+
+-- Update metadata
+local meta = redis.call('HMGET', metrics_key, 'last_error_at', 'consecutive_errors')
+local prev_failure_ts = tonumber(meta[1])
+local prev_consecutive_errors = tonumber(meta[2])
+
+if not prev_failure_ts or failure_ts > prev_failure_ts then
+  redis.call(
+    'HSET', metrics_key,
+    'last_error_at', failure_ts,
+    'last_error_json', failure_json,
+    'consecutive_errors', (prev_consecutive_errors or 0) + 1,
+    'consecutive_successes', 0
+  )
+else
+  redis.call(
+    'HSET', metrics_key,
+    'consecutive_errors', (prev_consecutive_errors or 0) + 1,
+    'consecutive_successes', 0
+  )
+end
+redis.call('EXPIRE', metrics_key, metadata_ttl) -- Not supported in Redis 6.2:, 'GT')

data/lib/stoplight/infrastructure/redis/storage/window_metrics/record_success.lua

@@ -0,0 +1,35 @@
+local request_ts = tonumber(ARGV[1])
+local request_id = ARGV[2]
+local bucket_ttl = tonumber(ARGV[3])
+local metadata_ttl = tonumber(ARGV[4])
+
+local metrics_key = KEYS[1]
+local successes_key = KEYS[2]
+
+-- Record success
+if successes_key ~= nil then
+  redis.call('ZADD', successes_key, request_ts, request_id)
+  redis.call('EXPIRE', successes_key, bucket_ttl) -- Not supported in Redis 6.2:, 'NX')
+end
+
+-- Update metadata
+local meta = redis.call('HMGET', metrics_key, 'last_success_at', 'consecutive_successes')
+local prev_success_ts = tonumber(meta[1])
+local prev_consecutive_successes = tonumber(meta[2])
+
+if not prev_success_ts or request_ts > prev_success_ts then
+  redis.call(
+    'HSET', metrics_key,
+    'last_success_at', request_ts,
+    'consecutive_errors', 0,
+    'consecutive_successes', (prev_consecutive_successes or 0) + 1
+  )
+else
+  redis.call(
+    'HSET', metrics_key,
+    'consecutive_errors', 0,
+    'consecutive_successes', (prev_consecutive_successes or 0) + 1
+  )
+end
+
+redis.call('EXPIRE', metrics_key, metadata_ttl) -- Not supported in Redis 6.2:, 'GT')

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      module Storage
+        # Distributed storage for time-windowed light metrics using Redis.
+        #
+        # This class implements sliding window metrics using Redis sorted sets (ZSETs)
+        # for efficient time-range queries. Events are bucketed by hour to bound memory
+        # usage and enable automatic expiration via Redis TTLs.
+        #
+        # == Storage Structure
+        #
+        # Events are stored in hourly buckets as ZSETs:
+        #   stoplight:{version}:{system}:{light}:window_metrics:success:1696154400
+        #   stoplight:{version}:{system}:{light}:window_metrics:failure:1696154400
+        #
+        # Each ZSET member is a unique event ID with its timestamp as the score,
+        # enabling O(log N) range queries via ZCOUNT.
+        #
+        # Metadata (consecutive counters, last error) is stored in a hash:
+        #   stoplight:{version}:{system}:{light}:window_metrics
+        #
+        # == Bucket Strategy
+        #
+        # Fixed 1-hour buckets provide a balance between:
+        # - Query efficiency: At most ~25 buckets for a 24-hour window
+        # - Memory efficiency: Natural expiration without manual cleanup
+        # - Precision: Sub-bucket accuracy via ZSET scores
+        #
+        # == Atomicity
+        #
+        # All operations use Lua scripts to ensure atomicity:
+        # - record_success: Increments counter and updates metadata in one round-trip
+        # - record_failure: Same, plus stores serialized error details
+        # - metrics_snapshot: Aggregates across buckets atomically
+        #
+        class WindowMetrics < Metrics
+          def initialize(redis:, scripting:, config:, clock:, key_space:)
+            @clock = clock
+            @scripting = scripting
+            @redis = redis
+            @config = config
+            @key_space = key_space
+            @metrics_key = key_space.key(:window_metrics)
+            @window_size = T.must(config.window_size).to_i
+          end
+
+          # Get metrics for the current light
+          #
+          # @return [Stoplight::Domain::Metrics]
+          def metrics_snapshot
+            window_end_ts = clock.current_time.to_f
+            window_start_ts = window_end_ts - @window_size
+            failure_keys = failure_bucket_keys(window_end_ts)
+            success_keys = success_bucket_keys(window_end_ts)
+
+            successes, errors, last_success_at, last_error_json, consecutive_errors, consecutive_successes = scripting.call(
+              :"window_metrics/metrics_snapshot",
+              args: [
+                failure_keys.count,
+                window_start_ts,
+                window_end_ts,
+                "last_success_at", "last_error_json", "consecutive_errors", "consecutive_successes"
+              ],
+              keys: [
+                metrics_key,
+                *success_keys,
+                *failure_keys
+              ]
+            )
+            Domain::MetricsSnapshot.new(
+              successes:, errors:,
+              consecutive_errors: [consecutive_errors.to_i, errors].min,
+              consecutive_successes: [consecutive_successes.to_i, successes].min,
+              last_error: deserialize_failure(last_error_json),
+              last_success_at: (clock.at(last_success_at.to_f) if last_success_at)
+            )
+          end
+
+          # Records successful circuit breaker execution
+          #
+          # @return [void]
+          def record_success
+            timestamp = clock.current_time.to_f
+
+            scripting.call(
+              :"window_metrics/record_success",
+              args: [timestamp, SecureRandom.hex(12), bucket_ttl, metrics_ttl],
+              keys: [
+                metrics_key,
+                successes_key(time: timestamp)
+              ]
+            )
+          end
+
+          # Records failed circuit breaker execution
+          #
+          # @param exception [StandardError]
+          # @return [void]
+          def record_failure(exception)
+            timestamp = clock.current_time.to_f
+
+            scripting.call(
+              :"window_metrics/record_failure",
+              args: [timestamp, SecureRandom.hex(12), serialize_exception(exception, timestamp:), bucket_ttl, metrics_ttl],
+              keys: [metrics_key, errors_key(time: timestamp)]
+            )
+          end
+
+          def clear
+            window_end_ts = clock.current_time.to_f
+            failure_keys = failure_bucket_keys(window_end_ts)
+            success_keys = success_bucket_keys(window_end_ts)
+
+            redis.with do |client|
+              client.del(metrics_key, *failure_keys, *success_keys)
+            end
+          end
+
+          # Generates a Redis key for a specific metric and time.
+          #
+          # @param metric [Symbol] The metric type (e.g., "errors").
+          # @param time [Time, Numeric] The time for which to generate the key.
+          # @return [String] The generated Redis key.
+          def bucket_key(metric:, time:)
+            key_space.key(:window_metrics, metric, (time.to_i / bucket_size) * bucket_size)
+          end
+
+          # Retrieves the list of Redis bucket keys required to cover a specific time window.
+          #
+          # @param metric The metric type (e.g., "errors").
+          # @param window_end  The end time of the window (can be a Time object or a numeric timestamp).
+          # @return A list of Redis keys for the buckets that cover the time window.
+          # @api private
+          def buckets_for_window(metric:, window_end:)
+            window_end_ts = window_end.to_i
+            window_start_ts = window_end_ts - @window_size
+
+            # Find bucket timestamps that contain any part of the window
+            start_bucket = (window_start_ts / bucket_size) * bucket_size
+
+            # End bucket is the last bucket that contains data within our window
+            end_bucket = ((window_end_ts - 1) / bucket_size) * bucket_size
+
+            (start_bucket..end_bucket).step(bucket_size).map do |bucket_start|
+              bucket_key(metric: metric, time: bucket_start)
+            end
+          end
+
+          private
+
+          attr_reader :redis
+          attr_reader :scripting
+          attr_reader :metrics_key
+          attr_reader :clock
+          attr_reader :key_space
+
+          def bucket_size = 3600 # 1 hour
+          def bucket_ttl = @window_size + bucket_size
+
+          def successes_key(time:) = bucket_key(metric: :success, time:)
+
+          def errors_key(time:) = bucket_key(metric: :failure, time:)
+
+          def failure_bucket_keys(window_end) = buckets_for_window(metric: :failure, window_end:)
+
+          def success_bucket_keys(window_end) = buckets_for_window(metric: :success, window_end:)
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/storage/compatibility_metrics.rb

@@ -19,13 +19,10 @@ module Stoplight
       #   )
       #   metrics.record_success
       #
-      # @see Stoplight::Domain::Storage::Metrics
-      class CompatibilityMetrics < Domain::Storage::Metrics
-        private attr_reader :data_store
-        private attr_reader :config
+      class CompatibilityMetrics
+        attr_reader :data_store
+        attr_reader :config
 
-        # @param data_store [Stoplight::Domain::DataStore]
-        # @param config [Stoplight::Domain::Config]
         def initialize(data_store:, config:)
           @data_store = data_store
           @config = config
@@ -33,14 +30,10 @@ module Stoplight
 
         def metrics_snapshot = data_store.get_metrics(config)
 
-        # @return [void]
         def record_success = data_store.record_success(config)
 
-        # @param error [StandardError]
-        # @return [void]
         def record_failure(error) = data_store.record_failure(config, error)
 
-        # @return [void]
         def clear = data_store.clear_metrics(config)
       end
     end

data/lib/stoplight/infrastructure/storage/compatibility_recovery_lock.rb

@@ -12,24 +12,21 @@ module Stoplight
       # This adapter will be removed in a future versions once all
       # data stores have native recovery lock implementations.
       #
-      # @see Stoplight::Domain::Storage::RecoveryLock
-      class CompatibilityRecoveryLock < Domain::Storage::RecoveryLock
-        private attr_reader :data_store
-        private attr_reader :config
-
-        # @param data_store [Stoplight::Domain::DataStore]
-        # @param config [Stoplight::Domain::Config]
+      # @see Stoplight::Domain::_RecoveryLockStore
+      class CompatibilityRecoveryLock
         def initialize(data_store:, config:)
           @data_store = data_store
           @config = config
         end
 
-        # @return [Stoplight::Domain::RecoveryLockToken, nil]
-        def acquire_lock = data_store.acquire_recovery_lock(config)
+        def acquire_lock = data_store.acquire_recovery_lock(config) #: Domain::Storage::RecoveryLockToken?
 
-        # @param lock [Stoplight::Domain::LockToken]
-        # @return [void]
         def release_lock(lock) = data_store.release_recovery_lock(lock)
+
+        private
+
+        attr_reader :data_store
+        attr_reader :config
       end
     end
   end

data/lib/stoplight/infrastructure/storage/compatibility_recovery_metrics.rb

@@ -21,13 +21,7 @@ module Stoplight
       #   recovery_metrics.record_success
       #   recovery_metrics.metrics_snapshot # => 1 success, 0 failures
       #
-      # @see Stoplight::Domain::Storage::Metrics
-      class CompatibilityRecoveryMetrics < Domain::Storage::Metrics
-        private attr_reader :data_store
-        private attr_reader :config
-
-        # @param data_store [Stoplight::Domain::DataStore]
-        # @param config [Stoplight::Domain::Config]
+      class CompatibilityRecoveryMetrics
         def initialize(data_store:, config:)
           @data_store = data_store
           @config = config
@@ -36,19 +30,17 @@ module Stoplight
         def metrics_snapshot = data_store.get_recovery_metrics(config)
 
         # Tracks successful circuit breaker execution
-        #
-        # @return [void]
         def record_success = data_store.record_recovery_probe_success(config)
 
         # Tracks failed circuit breaker execution
-        #
-        # @param error [StandardError]
-        # @return [void]
         def record_failure(error) = data_store.record_recovery_probe_failure(config, error)
 
-        # Clears metrics
-        # @return [void]
         def clear = data_store.clear_recovery_metrics(config)
+
+        private
+
+        attr_reader :data_store
+        attr_reader :config
       end
     end
   end

data/lib/stoplight/infrastructure/storage/compatibility_state.rb

@@ -20,35 +20,24 @@ module Stoplight
       #   state.set_state(State::LOCKED_RED)
       #   snapshot = state.state_snapshot
       #
-      class CompatibilityState < Domain::Storage::State
-        # @!attribute data_store
-        #   @return [Stoplight::Domain::DataStore]
-        private attr_reader :data_store
-
-        # @!attribute config
-        #   @return [Stoplight::Domain::Config]
-        private attr_reader :config
-
-        # @param data_store [Stoplight::Domain::DataStore]
-        # @param config [Stoplight::Domain::Config]
+      class CompatibilityState
         def initialize(data_store:, config:)
           @data_store = data_store
           @config = config
         end
 
-        # @return [Stoplight::Domain::StateSnapshot]
         def state_snapshot = data_store.get_state_snapshot(config)
 
-        # @param state [String]
-        # @return [String]
         def set_state(state) = data_store.set_state(config, state)
 
-        # @param color [String]
-        # @return [Boolean]
         def transition_to_color(color) = data_store.transition_to_color(config, color)
 
-        # @return [void]
         def clear = data_store.delete_light(config)
+
+        private
+
+        attr_reader :data_store
+        attr_reader :config
       end
     end
   end

data/lib/stoplight/infrastructure/system_clock.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    # Production clock implementation using Ruby's Time class.
+    #
+    # Default clock for all Stoplight time-dependent operations including
+    # bucket calculation, window boundaries, and state transition timestamps.
+    #
+    class SystemClock
+      def current_time = Time.now.utc
+
+      def at(timestamp) = Time.at(timestamp).utc
+    end
+  end
+end

data/lib/stoplight/notifier.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Notifier
+    class Base
+    end
+    Generic = Infrastructure::Notifier::Generic
+    IO = Infrastructure::Notifier::IO
+    Logger = Infrastructure::Notifier::Logger
+  end
+end

data/lib/stoplight/state.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module State
+    UNLOCKED = "unlocked"
+    LOCKED_GREEN = "locked_green"
+    LOCKED_RED = "locked_red"
+  end
+end

data/lib/stoplight/types.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Stoplight
+  module Types
+    def self.undefined = Undefined.instance
+
+    # Asserts a value is non-nil, returning it with a narrowed type.
+    #
+    # Use this to satisfy Steep's flow typing when you know a nilable value
+    # must be present. Prefer this over type assertions (#: Type) since it
+    # provides runtime validation.
+    #
+    # @example Validating required configuration
+    #   @window_size = T.must(config.window_size)
+    #
+    # @raise [TypeError] if value is nil
+    # @return [T] the non-nil value
+    #
+    def self.must(value)
+      if value.nil?
+        raise TypeError, "must not have nil value"
+      else
+        value
+      end
+    end
+  end
+end