stoplight 5.6.0 → 5.8.0

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Storage
+      # Temporary adapter that bridges Domain::Storage::Metrics to existing DataStore.
+      #
+      # This compatibility layer allows the metrics abstraction to be introduced
+      # without breaking existing data store implementations. It delegates all
+      # operations to the data store's original methods.
+      #
+      # This class will be removed in a future versions once all data stores
+      # have native metrics implementations.
+      #
+      # @example Creating metrics for a circuit
+      #   metrics = CompatibilityMetrics.new(
+      #     data_store: redis_store,
+      #     config: config
+      #   )
+      #   metrics.record_success
+      #
+      class CompatibilityMetrics
+        attr_reader :data_store
+        attr_reader :config
+
+        def initialize(data_store:, config:)
+          @data_store = data_store
+          @config = config
+        end
+
+        def metrics_snapshot = data_store.get_metrics(config)
+
+        def record_success = data_store.record_success(config)
+
+        def record_failure(error) = data_store.record_failure(config, error)
+
+        def clear = data_store.clear_metrics(config)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Storage
+      # Temporary adapter that bridges +Domain::Storage::RecoveryLock+ to existing DataStore.
+      #
+      # This compatibility layer allows the recovery lock abstraction to be
+      # introduced without breaking existing data store implementations. It
+      # delegates all lock operations to the data store's original methods.
+      #
+      # This adapter will be removed in a future versions once all
+      # data stores have native recovery lock implementations.
+      #
+      # @see Stoplight::Domain::_RecoveryLockStore
+      class CompatibilityRecoveryLock
+        def initialize(data_store:, config:)
+          @data_store = data_store
+          @config = config
+        end
+
+        def acquire_lock = data_store.acquire_recovery_lock(config) #: Domain::Storage::RecoveryLockToken?
+
+        def release_lock(lock) = data_store.release_recovery_lock(lock)
+
+        private
+
+        attr_reader :data_store
+        attr_reader :config
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    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.
+      #
+      # Like +CompatibilityMetrics+, this adapter will be replaced with purpose-built
+      # recovery metrics implementations (e.g., +ConsecutiveSuccessMetrics+) once the
+      # metrics extraction is complete.
+      #
+      # @example Recovery probe flow
+      #   # Circuit is RED, start probing
+      #   recovery_metrics = CompatibilityRecoveryMetrics.new(
+      #     data_store: redis_store,
+      #     config: circuit_config
+      #   )
+      #
+      #   recovery_metrics.record_success
+      #   recovery_metrics.metrics_snapshot # => 1 success, 0 failures
+      #
+      class CompatibilityRecoveryMetrics
+        def initialize(data_store:, config:)
+          @data_store = data_store
+          @config = config
+        end
+
+        def metrics_snapshot = data_store.get_recovery_metrics(config)
+
+        # Tracks successful circuit breaker execution
+        def record_success = data_store.record_recovery_probe_success(config)
+
+        # Tracks failed circuit breaker execution
+        def record_failure(error) = data_store.record_recovery_probe_failure(config, error)
+
+        def clear = data_store.clear_recovery_metrics(config)
+
+        private
+
+        attr_reader :data_store
+        attr_reader :config
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Storage
+      # Temporary adapter that bridges Domain::Storage::State to existing DataStore.
+      #
+      # This compatibility layer allows the state abstraction to be introduced
+      # without breaking existing data store implementations. It delegates all
+      # state operations to the data store's original methods.
+      #
+      # This adapter will be removed in a future versions once all
+      # data stores have native state storage implementations.
+      #
+      # @example Creating state storage for a circuit
+      #   state = CompatibilityState.new(
+      #     data_store: redis_store,
+      #     config: circuit_config
+      #   )
+      #   state.set_state(State::LOCKED_RED)
+      #   snapshot = state.state_snapshot
+      #
+      class CompatibilityState
+        def initialize(data_store:, config:)
+          @data_store = data_store
+          @config = config
+        end
+
+        def state_snapshot = data_store.get_state_snapshot(config)
+
+        def set_state(state) = data_store.set_state(config, state)
+
+        def transition_to_color(color) = data_store.transition_to_color(config, color)
+
+        def clear = data_store.delete_light(config)
+
+        private
+
+        attr_reader :data_store
+        attr_reader :config
+      end
+    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

data/lib/stoplight/undefined.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Stoplight
+  # Singleton representing an undefined/not-provided argument.
+  #
+  # Distinct from nil, which may be a valid configured value.
+  # Used with keyword arguments to detect when a parameter
+  # wasn't passed vs. explicitly set to nil.
+  # @api private
+  class Undefined
+    include Singleton
+
+    def inspect = "UNDEFINED"
+    alias_method :to_s, :inspect
+  end
+end

data/lib/stoplight/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stoplight
-  VERSION = Gem::Version.new("5.6.0")
+  VERSION = Gem::Version.new("5.8.0")
 end

data/lib/stoplight/wiring/config_compatibility_validator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Validates that traffic control and recovery strategies are
+    # compatible with the provided configuration.
+    #
+    # Different strategies have different configuration requirements:
+    # - ErrorRate requires window_size and threshold ∈ [0,1]
+    # - ConsecutiveErrors requires threshold > 0
+    # - ConsecutiveSuccesses requires recovery_threshold > 0
+    #
+    # @raise [Stoplight::Error::ConfigurationError] if incompatible
+    class ConfigCompatibilityValidator
+      private attr_reader :config
+
+      class << self
+        def call(config:) = new(config:).call
+      end
+
+      def initialize(config:)
+        @config = config
+      end
+
+      def call
+        validate_traffic_control!
+        validate_traffic_recovery!
+        config
+      end
+
+      private def validate_traffic_control!
+        traffic_control = config.traffic_control
+        traffic_control.check_compatibility(config).then do |compatibility_result|
+          if compatibility_result.incompatible?
+            raise Error::ConfigurationError,
+              "#{traffic_control} incompatible with config: #{compatibility_result.error_messages}",
+              caller(8)
+          end
+        end
+      end
+
+      def validate_traffic_recovery!
+        traffic_recovery = config.traffic_recovery
+        traffic_recovery.check_compatibility(config).then do |compatibility_result|
+          if compatibility_result.incompatible?
+            raise Error::ConfigurationError,
+              "#{traffic_recovery} incompatible with config: #{compatibility_result.error_messages}",
+              caller(8)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/configuration_dsl.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class ConfigurationDsl
+      def initialize(
+        name: T.undefined,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        tracked_errors: T.undefined,
+        skipped_errors: T.undefined,
+        data_store: T.undefined,
+        error_notifier: T.undefined,
+        notifiers: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined
+      )
+        @name = name
+        @cool_off_time = cool_off_time
+        @threshold = threshold
+        @recovery_threshold = recovery_threshold
+        @window_size = window_size
+        @tracked_errors = tracked_errors
+        @skipped_errors = skipped_errors
+        @traffic_control = traffic_control
+        @traffic_recovery = traffic_recovery
+        @error_notifier = error_notifier
+        @data_store = data_store
+        @notifiers = notifiers
+      end
+
+      def configure!(default_config)
+        ConfigCompatibilityValidator.call(
+          config: default_config.with(
+            name:,
+            cool_off_time:,
+            threshold:,
+            recovery_threshold:,
+            window_size:,
+            tracked_errors:,
+            skipped_errors:,
+            traffic_control:,
+            traffic_recovery:,
+            error_notifier:,
+            data_store:,
+            notifiers:
+          )
+        )
+      end
+
+      private
+
+      attr_reader :name
+      attr_reader :cool_off_time
+      attr_reader :threshold
+      attr_reader :recovery_threshold
+      attr_reader :window_size
+      attr_reader :error_notifier
+      attr_reader :data_store
+      attr_reader :notifiers
+
+      def tracked_errors
+        value = @tracked_errors
+        if value.is_a?(Undefined)
+          value
+        else
+          Array(value)
+        end
+      end
+
+      def skipped_errors
+        value = @skipped_errors
+        if value.is_a?(Undefined)
+          value
+        else
+          Array(value)
+        end
+      end
+
+      def traffic_control
+        value = @traffic_control
+        if value.is_a?(Undefined)
+          value
+        else
+          LightFactory::TrafficControlDsl.call(value)
+        end
+      end
+
+      def traffic_recovery
+        value = @traffic_recovery
+        if value.is_a?(Undefined)
+          value
+        else
+          LightFactory::TrafficRecoveryDsl.call(value)
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/data_store_backend.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Abstract base class defining the storage backend interface.
+    #
+    # A backend encapsulates all storage construction for a specific data store type
+    # (Memory or Redis). Backends handle infrastructure concerns like connection
+    # management and failover wrapping, exposing a uniform interface to StorageSetBuilder.
+    #
+    # Each method returns a memoized storage instance. Backends are designed to be
+    # instantiated once per Light and reused.
+    #
+    # @abstract Subclass and implement all methods
+    # @see Memory::Backend
+    # @see Redis::Backend
+    # @api private
+    class DataStoreBackend
+      def state_store = raise ArgumentError
+      def recovery_lock_store = raise ArgumentError
+      def recovery_metrics_store = raise ArgumentError
+      def windowed_metrics_store = raise ArgumentError
+      def unbounded_metrics_store = raise ArgumentError
+    end
+  end
+end

data/lib/stoplight/wiring/default.rb

@@ -5,7 +5,7 @@ module Stoplight
     module Default
       COOL_OFF_TIME = 60.0
 
-      DATA_STORE = Infrastructure::DataStore::Memory.new
+      DATA_STORE = Stoplight::DataStore::Memory.new
 
       ERROR_NOTIFIER = ->(error) { warn error }
 
@@ -19,7 +19,7 @@ module Stoplight
       WINDOW_SIZE = nil
 
       TRACKED_ERRORS = [StandardError].freeze
-      SKIPPED_ERRORS = [].freeze
+      SKIPPED_ERRORS = [].freeze # steep:ignore
 
       TRAFFIC_CONTROL = Domain::TrafficControl::ConsecutiveErrors.new
       TRAFFIC_RECOVERY = Domain::TrafficRecovery::ConsecutiveSuccesses.new

data/lib/stoplight/wiring/default_config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Provides default settings for the Stoplight library.
+    DefaultConfig = Domain::Config.new(
+      name: "DEFAULT_CONFIG",
+      cool_off_time: Default::COOL_OFF_TIME,
+      threshold: Default::THRESHOLD,
+      recovery_threshold: Default::RECOVERY_THRESHOLD,
+      window_size: Default::WINDOW_SIZE,
+      tracked_errors: Default::TRACKED_ERRORS,
+      skipped_errors: Default::SKIPPED_ERRORS,
+      traffic_control: Default::TRAFFIC_CONTROL,
+      traffic_recovery: Default::TRAFFIC_RECOVERY,
+      error_notifier: Default::ERROR_NOTIFIER,
+      notifiers: Default::NOTIFIERS,
+      data_store: Default::DATA_STORE
+    )
+  end
+end