stoplight 5.7.0 → 5.8.2

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.7.0")
+  VERSION = Gem::Version.new("5.8.2")
 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

@@ -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

data/lib/stoplight/wiring/default_configuration.rb

@@ -2,76 +2,93 @@
 
 module Stoplight
   module Wiring
-    # User-facing configuration interface
+    # User-facing configuration interface for setting global Stoplight defaults.
+    #
+    # This class serves as the configuration DSL yielded to users when calling
+    # +Stoplight.configure+. It provides a clean interface for setting default
+    # values while internally tracking whether each setting was explicitly
+    # configured or should fall back to library defaults.
+    #
+    # @example Configuring Stoplight defaults
+    #   Stoplight.configure do |config|
+    #     config.data_store = Redis.new
+    #     config.threshold = 5
+    #     # window_size not set - will use library default
+    #   end
+    #
+    # == Option-Based Configuration Tracking
+    #
+    # Internally, each setting is wrapped in an Option type (+Some+ or +None+).
+    # This design allows the class to distinguish between three states:
+    #
+    # 1. Not configured: Stored as +None+, getter returns library default
+    # 2. Explicitly configured: Stored as +Some(value)+, getter returns that value
+    # 3. Explicitly set to nil: Stored as +Some(nil)+, getter returns +nil+
+    #
+    # This distinction is critical when building {Settings} and {Dependencies}
+    # objects, which need to know whether a value was user-specified (and should
+    # be enforced) or inherited (and can be overridden per-circuit).
+    #
+    # == Dual Interface
+    #
+    # The class exposes two interfaces for each setting:
+    #
+    # - *Setters* (+attr_writer+): Accept raw values, wrap them in +Some+
+    # - *Getters* (custom methods): Unwrap the Option, returning the value
+    #   or falling back to library defaults from {Default}
+    #
+    # The {#settings} and {#dependencies} methods preserve the raw Option
+    # values, allowing downstream code to detect explicit configuration.
+    #
+    # @see Settings Value object for circuit behavior configuration
+    # @see Dependencies Value object for infrastructure dependencies
+    # @see Default Library default constants
+    #
     class DefaultConfiguration
-      # @!attribute [w] cool_off_time
-      #   @return [Integer, nil] The default cool-off time in seconds.
-      attr_writer :cool_off_time
+      def initialize
+        @config = DefaultConfig.with
+        @cool_off_time = T.undefined
+        @threshold = T.undefined
+        @recovery_threshold = T.undefined
+        @window_size = T.undefined
+        @tracked_errors = T.undefined
+        @skipped_errors = T.undefined
+        @traffic_control = T.undefined
+        @traffic_recovery = T.undefined
+        @error_notifier = T.undefined
+        @data_store = T.undefined
+        @notifiers = T.undefined
+      end
 
-      # @!attribute [w] threshold
-      #   @return [Integer, Float, nil] The default failure threshold to trip the circuit breaker.
-      attr_writer :threshold
+      def notifiers = @config.notifiers
 
-      # @!attribute [w] recovery_threshold
-      #  @return [Integer, nil] The default recovery threshold for the circuit breaker.
+      attr_writer :cool_off_time
+      attr_writer :threshold
       attr_writer :recovery_threshold
-
-      # @!attribute [w] window_size
-      #   @return [Integer, nil] The default size of the rolling window for failure tracking.
       attr_writer :window_size
-
-      # @!attribute [w] tracked_errors
-      #   @return [Array<Class>, nil] The default list of errors to track.
       attr_writer :tracked_errors
-
-      # @!attribute [w] skipped_errors
-      #   @return [Array<Class>, nil] The default list of errors to skip.
       attr_writer :skipped_errors
-
-      # @!attribute [w] error_notifier
-      #   @return [Proc, nil] The default error notifier (callable object).
-      attr_writer :error_notifier
-
-      # @!attribute [rw] notifiers
-      #   @return [Array<Stoplight::Domain::StateTransitionNotifier>] The default list of notifiers.
-      attr_accessor :notifiers
-
-      # @!attribute [rw] data_store
-      #   @return [Stoplight::Wiring::DataStore::Base] The default data store instance.
-      attr_accessor :data_store
-
-      # @!attribute [w] traffic_control
-      #   @return [Stoplight::Domain::TrafficControl::Base] The traffic control strategy.
       attr_writer :traffic_control
-
-      # @!attribute [w] traffic_recovery
-      #   @return [Stoplight::Domain::TrafficRecovery::Base] The traffic recovery strategy.
       attr_writer :traffic_recovery
+      attr_writer :error_notifier
+      attr_writer :data_store
+      attr_writer :notifiers
 
-      def initialize
-        # This allows users appending notifiers to the default list,
-        # while still allowing them to override the default list.
-        @notifiers = Default::NOTIFIERS
-      end
-
-      # Converts the user-defined configuration to a hash.
-      #
-      # @return [Hash] A hash representation of the configuration, excluding nil values.
-      # @api private
-      def to_h
-        {
+      # Builds and validates configuration
+      def to_config!
+        ConfigurationDsl.new(
           cool_off_time: @cool_off_time,
           threshold: @threshold,
           recovery_threshold: @recovery_threshold,
           window_size: @window_size,
           tracked_errors: @tracked_errors,
           skipped_errors: @skipped_errors,
-          data_store: @data_store,
-          error_notifier: @error_notifier,
-          notifiers: @notifiers,
           traffic_control: @traffic_control,
-          traffic_recovery: @traffic_recovery
-        }.compact
+          traffic_recovery: @traffic_recovery,
+          error_notifier: @error_notifier,
+          data_store: @data_store,
+          notifiers: @notifiers
+        ).configure!(@config)
       end
     end
   end

data/lib/stoplight/wiring/light_builder.rb

@@ -34,43 +34,28 @@ module Stoplight
       MEMORY_REGISTRY = Concurrent::Map.new
       private_constant :MEMORY_REGISTRY
 
-      # @!attribute data_store_config
-      #   @return [Stoplight::DataStore::Bose]
-      private attr_reader :data_store_config
-
-      # @!attribute error_notifier
-      #   @return [Proc]
-      private attr_reader :error_notifier
-
-      # @!attribute traffic_recovery
-      #   @return [Stoplight::Domain::TrafficRecovery::Base]
-      private attr_reader :traffic_recovery
-
-      # @!attribute traffic_control
-      #   @return [Stoplight::Domain::TrafficControl::Base]
-      private attr_reader :traffic_control
-
-      # @!attribute config
-      #   @return [Stoplight::Domain::Config]
-      private attr_reader :config
-
-      # @!attribute factory
-      #   @return [Stoplight::Domain::LightFactory]
-      private attr_reader :factory
-
-      def initialize(settings)
-        @notifiers = settings[:notifiers]
-        @data_store_config = settings[:data_store]
-        @error_notifier = settings[:error_notifier]
-        @traffic_recovery = settings[:traffic_recovery]
-        @traffic_control = settings[:traffic_control]
-        @config = settings[:config]
-        @factory = settings[:factory]
+      def initialize(config:, factory:)
+        @clock = Infrastructure::SystemClock.new
+        @config = config
+        @name = T.must(config.name)
+        @cool_off_time = config.cool_off_time
+
+        @data_store_config = config.data_store
+        @error_notifier = config.error_notifier
+        @factory = factory
+        @notifiers = config.notifiers
+        @traffic_recovery = config.traffic_recovery
+        @traffic_control = config.traffic_control
+
+        @error_tracking_policy = Domain::ErrorTrackingPolicy.new(
+          tracked: config.tracked_errors,
+          skipped: config.skipped_errors
+        )
       end
 
       def build
         Stoplight::Domain::Light.new(
-          config,
+          @name,
           state_store:,
           green_run_strategy:,
           yellow_run_strategy:,
@@ -79,50 +64,60 @@ module Stoplight
         )
       end
 
-      private def state_store = Stoplight::Infrastructure::Storage::CompatibilityState.new(config:, data_store:)
+      private
+
+      attr_reader :data_store_config
+      attr_reader :error_notifier
+      attr_reader :factory
+      attr_reader :clock
+      attr_reader :traffic_control
+      attr_reader :traffic_recovery
+      attr_reader :config
+
+      def state_store = Stoplight::Infrastructure::Storage::CompatibilityState.new(config:, data_store:)
 
       # @return [<Stoplight::Notifier::Base>]
-      private def notifiers
+      def notifiers
         Array(@notifiers).map do |notifier|
           Infrastructure::Notifier::FailSafe.new(notifier:, error_notifier:)
         end
       end
 
-      private def redis_recovery_lock_store
-        Infrastructure::DataStore::Redis::RecoveryLockStore.new(
-          redis: data_store_config.redis,
+      def redis_recovery_lock_store
+        Infrastructure::Redis::DataStore::RecoveryLockStore.new(
+          redis:,
           lock_timeout: config.cool_off_time_in_milliseconds,
           scripting:
         )
       end
 
-      private def scripting = Infrastructure::DataStore::Redis::Scripting.new(redis: data_store_config.redis)
+      def scripting = Infrastructure::Redis::DataStore::Scripting.new(redis:)
 
-      private def memory_recovery_lock_store
-        Infrastructure::DataStore::Memory::RecoveryLockStore.new
+      def memory_recovery_lock_store
+        Infrastructure::Memory::DataStore::RecoveryLockStore.new
       end
 
-      private def failover_data_store
+      def failover_data_store
         create_data_store(FAILOVER_DATA_STORE_CONFIG)
       end
 
-      private def data_store
+      def data_store
         create_data_store(data_store_config)
       end
 
-      private def metrics_store
+      def metrics_store
         Stoplight::Infrastructure::Storage::CompatibilityMetrics.new(config:, data_store:)
       end
 
-      private def recovery_lock_store
+      def recovery_lock_store
         Stoplight::Infrastructure::Storage::CompatibilityRecoveryLock.new(config:, data_store:)
       end
 
-      private def request_tracker
+      def request_tracker
         Domain::Tracker::Request.new(traffic_control:, notifiers:, config:, metrics_store:, state_store:)
       end
 
-      private def recovery_probe_tracker
+      def recovery_probe_tracker
         Domain::Tracker::RecoveryProbe.new(
           traffic_recovery:,
           notifiers:,
@@ -132,41 +127,48 @@ module Stoplight
         )
       end
 
-      private def recovery_metrics_store
+      def recovery_metrics_store
         Stoplight::Infrastructure::Storage::CompatibilityRecoveryMetrics.new(config:, data_store:)
       end
 
-      private def green_run_strategy
-        Domain::Strategies::GreenRunStrategy.new(config:, request_tracker:)
+      def green_run_strategy
+        Domain::Strategies::GreenRunStrategy.new(
+          error_tracking_policy: @error_tracking_policy,
+          request_tracker:
+        )
       end
 
-      private def yellow_run_strategy
+      def yellow_run_strategy
         Domain::Strategies::YellowRunStrategy.new(
-          config:,
+          name: @name,
+          error_tracking_policy: @error_tracking_policy,
           notifiers:,
           request_tracker: recovery_probe_tracker,
           red_run_strategy:,
           state_store:,
           metrics_store:,
-          recovery_lock_store:
+          recovery_lock_store:,
+          config: @config
         )
       end
 
-      private def red_run_strategy
-        Domain::Strategies::RedRunStrategy.new(config:)
+      def red_run_strategy
+        Domain::Strategies::RedRunStrategy.new(name: @name, cool_off_time: @cool_off_time)
       end
 
-      private def create_data_store(data_store_config)
+      def create_data_store(data_store_config)
         case data_store_config
-        in Stoplight::DataStore::Memory
+        when Stoplight::DataStore::Memory
           memory_registry.compute_if_absent(data_store_config.object_id) do
-            Infrastructure::DataStore::Memory.new(
-              recovery_lock_store: memory_recovery_lock_store
+            Infrastructure::Memory::DataStore.new(
+              recovery_lock_store: memory_recovery_lock_store,
+              clock:
             )
           end
-        in Stoplight::DataStore::Redis
-          Infrastructure::DataStore::FailSafe.new(
-            data_store: Stoplight::Infrastructure::DataStore::Redis.new(
+        when Stoplight::DataStore::Redis
+          Infrastructure::FailSafe::DataStore.new(
+            data_store: Stoplight::Infrastructure::Redis::DataStore.new(
+              clock:,
               redis: data_store_config.redis,
               warn_on_clock_skew: data_store_config.warn_on_clock_skew,
               recovery_lock_store: redis_recovery_lock_store,
@@ -176,10 +178,21 @@ module Stoplight
             failover_data_store:,
             circuit_breaker: Stoplight.system_light("data_store:fail_safe:redis")
           )
+        else
+          raise NoMatchingPatternError, data_store_config
+        end
+      end
+
+      def redis
+        case data_store_config
+        when DataStore::Redis
+          data_store_config.redis
+        else
+          raise TypeError, "Expected Stoplight::DataStore::Redis, got #{data_store_config.class}"
         end
       end
 
-      private def memory_registry = MEMORY_REGISTRY
+      def memory_registry = MEMORY_REGISTRY
     end
   end
 end

data/lib/stoplight/wiring/light_factory/traffic_control_dsl.rb

@@ -3,9 +3,9 @@
 module Stoplight
   module Wiring
     class LightFactory
-      TrafficControlDsl = proc do |value|
+      TrafficControlDsl = ->(value) {
         case value
-        in Domain::TrafficControl::Base
+        in _ if value.respond_to?(:stop_traffic?) # TODO: can be removed in 6.0
           value
         in :consecutive_errors
           Domain::TrafficControl::ConsecutiveErrors.new
@@ -20,7 +20,7 @@ module Stoplight
               * :error_rate
           ERROR
         end
-      end
+      }
     end
   end
 end

data/lib/stoplight/wiring/light_factory/traffic_recovery_dsl.rb

@@ -3,19 +3,19 @@
 module Stoplight
   module Wiring
     class LightFactory
-      TrafficRecoveryDsl = proc do |value|
+      TrafficRecoveryDsl = ->(value) {
         case value
-        in Domain::TrafficRecovery::Base
+        in _ if value.respond_to?(:determine_color) # TODO: remove in 6.0
           value
         in :consecutive_successes
           Domain::TrafficRecovery::ConsecutiveSuccesses.new
         else
-          raise Domain::Error::ConfigurationError, <<~ERROR
+          raise Error::ConfigurationError, <<~ERROR
             unsupported traffic_recovery strategy provided (`#{value}`). Supported options:
               * :consecutive_successes
           ERROR
         end
-      end
+      }
     end
   end
 end