stoplight 5.6.0 → 5.8.0

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::Domain::DataStore] 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

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module Stoplight
+  module Wiring
+    # Constructs a fully-wired Light instance from validated configuration.
+    #
+    # LightBuilder is the final assembly step in the Light creation pipeline.
+    # It receives validated config and dependencies from ConfigurationPipeline
+    # and wires together all infrastructure components (data stores, trackers,
+    # strategies) needed for a functioning circuit breaker.
+    #
+    # LightBuilder maintains a global registry (MEMORY_REGISTRY) that ensures
+    # the same Memory data store config object always produces the same
+    # data store instance:
+    #
+    #   data_store = Stoplight::DataStore::Memory.new
+    #   light1 = Stoplight("foo", data_store: data_store)
+    #   light2 = Stoplight("bar", data_store: data_store)
+    #   # light1 and light2 share the same underlying memory store
+    #
+    #   light3 = Stoplight("baz", data_store: Stoplight::DataStore::Memory.new)
+    #   # light3 has its own independent store
+    #
+    # This singleton behavior is keyed by config object identity (object_id),
+    # not by value equality.
+    #
+    # @api private
+    class LightBuilder
+      FAILOVER_DATA_STORE_CONFIG = Stoplight::DataStore::Memory.new
+      private_constant :FAILOVER_DATA_STORE_CONFIG
+
+      MEMORY_REGISTRY = Concurrent::Map.new
+      private_constant :MEMORY_REGISTRY
+
+      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(
+          @name,
+          state_store:,
+          green_run_strategy:,
+          yellow_run_strategy:,
+          red_run_strategy:,
+          factory:
+        )
+      end
+
+      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>]
+      def notifiers
+        Array(@notifiers).map do |notifier|
+          Infrastructure::Notifier::FailSafe.new(notifier:, error_notifier:)
+        end
+      end
+
+      def redis_recovery_lock_store
+        Infrastructure::Redis::DataStore::RecoveryLockStore.new(
+          redis:,
+          lock_timeout: config.cool_off_time_in_milliseconds,
+          scripting:
+        )
+      end
+
+      def scripting = Infrastructure::Redis::DataStore::Scripting.new(redis:)
+
+      def memory_recovery_lock_store
+        Infrastructure::Memory::DataStore::RecoveryLockStore.new
+      end
+
+      def failover_data_store
+        create_data_store(FAILOVER_DATA_STORE_CONFIG)
+      end
+
+      def data_store
+        create_data_store(data_store_config)
+      end
+
+      def metrics_store
+        Stoplight::Infrastructure::Storage::CompatibilityMetrics.new(config:, data_store:)
+      end
+
+      def recovery_lock_store
+        Stoplight::Infrastructure::Storage::CompatibilityRecoveryLock.new(config:, data_store:)
+      end
+
+      def request_tracker
+        Domain::Tracker::Request.new(traffic_control:, notifiers:, config:, metrics_store:, state_store:)
+      end
+
+      def recovery_probe_tracker
+        Domain::Tracker::RecoveryProbe.new(
+          traffic_recovery:,
+          notifiers:,
+          config:,
+          metrics_store: recovery_metrics_store,
+          state_store:
+        )
+      end
+
+      def recovery_metrics_store
+        Stoplight::Infrastructure::Storage::CompatibilityRecoveryMetrics.new(config:, data_store:)
+      end
+
+      def green_run_strategy
+        Domain::Strategies::GreenRunStrategy.new(
+          error_tracking_policy: @error_tracking_policy,
+          request_tracker:
+        )
+      end
+
+      def yellow_run_strategy
+        Domain::Strategies::YellowRunStrategy.new(
+          name: @name,
+          error_tracking_policy: @error_tracking_policy,
+          notifiers:,
+          request_tracker: recovery_probe_tracker,
+          red_run_strategy:,
+          state_store:,
+          metrics_store:,
+          recovery_lock_store:,
+          config: @config
+        )
+      end
+
+      def red_run_strategy
+        Domain::Strategies::RedRunStrategy.new(name: @name, cool_off_time: @cool_off_time)
+      end
+
+      def create_data_store(data_store_config)
+        case data_store_config
+        when Stoplight::DataStore::Memory
+          memory_registry.compute_if_absent(data_store_config.object_id) do
+            Infrastructure::Memory::DataStore.new(
+              recovery_lock_store: memory_recovery_lock_store,
+              clock:
+            )
+          end
+        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,
+              scripting:
+            ),
+            error_notifier:,
+            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
+
+      def memory_registry = MEMORY_REGISTRY
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class LightFactory
+      TrafficControlDsl = ->(value) {
+        case value
+        in _ if value.respond_to?(:stop_traffic?) # TODO: can be removed in 6.0
+          value
+        in :consecutive_errors
+          Domain::TrafficControl::ConsecutiveErrors.new
+        in :error_rate
+          Domain::TrafficControl::ErrorRate.new
+        in {error_rate: error_rate_settings}
+          Domain::TrafficControl::ErrorRate.new(**error_rate_settings)
+        else
+          raise Stoplight::Error::ConfigurationError, <<~ERROR
+            unsupported traffic_control strategy provided (`#{value}`). Supported options:
+              * :consecutive_errors
+              * :error_rate
+          ERROR
+        end
+      }
+    end
+  end
+end

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

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

data/lib/stoplight/wiring/light_factory.rb

@@ -13,34 +13,42 @@ module Stoplight
     # @see Stoplight::Domain::LightFactory
     # @see Stoplight()
     # @api private
-
-    class LightFactory < Domain::LightFactory
-      # @!attribute [r] container
-      #   The dependency injection container holding all component configurations.
-      #   Contains config, data_store, notifiers, strategies, etc.
-      #   @return [Stoplight::Wiring::Container]
-      protected attr_reader :container
-
-      # @param container [Stoplight::Wiring::Container]
-      def initialize(container)
-        @container = container
+    #
+    class LightFactory
+      def initialize(config:)
+        @config = config
       end
 
-      # @param settings [Hash] Settings to override in the new factory
-      #   @see Stoplight()
-      # @return [Stoplight::Wiring::LightFactory]
-      # @see Stoplight()
-      def with(**settings)
-        transformed_settings = transform_settings(settings)
-        config_settings = extract_config_settings(transformed_settings)
-        dependency_settings = extract_dependency_settings(transformed_settings)
-
-        validate_settings!(transformed_settings, config_settings, dependency_settings)
-
-        new_config = container.resolve(:config).with(**config_settings)
-        new_container = container.with(config: new_config, **dependency_settings)
-
-        self.class.new(new_container)
+      def with(
+        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
+      )
+        self.class.new(
+          config: ConfigurationDsl.new(
+            name:,
+            cool_off_time:,
+            threshold:,
+            recovery_threshold:,
+            window_size:,
+            tracked_errors:,
+            skipped_errors:,
+            traffic_control:,
+            traffic_recovery:,
+            error_notifier:,
+            data_store:,
+            notifiers:
+          ).configure!(config)
+        )
       end
 
       # Builds a fully-configured Light instance.
@@ -60,129 +68,60 @@ module Stoplight
       #   light.run { api_call }
 
       def build
-        validate!
-
-        Stoplight::Domain::Light.new(
-          container.resolve(:config),
-          data_store: container.resolve(:data_store),
-          green_run_strategy: container.resolve(:green_run_strategy),
-          yellow_run_strategy: container.resolve(:yellow_run_strategy),
-          red_run_strategy: container.resolve(:red_run_strategy),
-          factory: self
-        )
+        light_builder(config:).build
       end
 
       def ==(other)
-        other.is_a?(self.class) && other.container == container
-      end
-
-      private def extract_config_settings(settings)
-        settings.slice(*container.resolve(:config).members)
-      end
-
-      private def extract_dependency_settings(settings)
-        settings.slice(*container.keys)
+        other.is_a?(self.class) && other.config == config
       end
 
-      private def validate_settings!(settings, config_settings, dependency_settings)
-        recognized_keys = config_settings.keys + dependency_settings.keys
-        unexpected_keys = settings.keys - recognized_keys
-
-        return if unexpected_keys.empty?
-        raise ArgumentError, "Unknown settings: #{unexpected_keys.join(", ")}"
+      alias_method :eql?, :==
+
+      def build_with(
+        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
+      )
+        with(
+          name:,
+          cool_off_time:,
+          threshold:,
+          recovery_threshold:,
+          window_size:,
+          tracked_errors:,
+          skipped_errors:,
+          data_store:,
+          error_notifier:,
+          notifiers:,
+          traffic_control:,
+          traffic_recovery:
+        ).build
       end
 
-      private def transform_settings(settings)
-        settings.dup.tap do |transformed_settings|
-          transform_config_settings!(transformed_settings)
-          transform_dependencies_settings!(transformed_settings)
-        end
+      def hash
+        [self.class, config].hash
       end
 
-      private def transform_config_settings!(settings)
-        if settings.key?(:tracked_errors)
-          settings[:tracked_errors] = normalize_array(settings[:tracked_errors])
-        end
-
-        if settings.key?(:skipped_errors)
-          settings[:skipped_errors] = normalize_array(settings[:skipped_errors])
-        end
+      protected
 
-        if settings.key?(:cool_off_time)
-          settings[:cool_off_time] = normalize_cool_off_time(settings[:cool_off_time])
-        end
-      end
+      attr_reader :config
 
-      private def transform_dependencies_settings!(settings)
-        if settings.key?(:traffic_control)
-          settings[:traffic_control] = apply_traffic_control_dsl(settings[:traffic_control])
-        end
+      private
 
-        if settings.key?(:traffic_recovery)
-          settings[:traffic_recovery] = apply_traffic_recovery_dsl(settings[:traffic_recovery])
-        end
+      def light_builder(config:)
+        LightBuilder.new(config:, factory: light_factory)
       end
 
-      private def normalize_array(value) = Array(value)
-      private def normalize_cool_off_time(value) = value.to_i
-
-      private def apply_traffic_control_dsl(traffic_control)
-        case traffic_control
-        in Domain::TrafficControl::Base
-          traffic_control
-        in :consecutive_errors
-          Domain::TrafficControl::ConsecutiveErrors.new
-        in :error_rate
-          Domain::TrafficControl::ErrorRate.new
-        in {error_rate: error_rate_settings}
-          Domain::TrafficControl::ErrorRate.new(**error_rate_settings)
-        else
-          raise Domain::Error::ConfigurationError, <<~ERROR
-            unsupported traffic_control strategy provided (`#{traffic_control}`). Supported options:
-              * :consecutive_errors
-              * :error_rate
-          ERROR
-        end
-      end
-
-      def apply_traffic_recovery_dsl(traffic_recovery)
-        case traffic_recovery
-        in Domain::TrafficRecovery::Base
-          traffic_recovery
-        in :consecutive_successes
-          Domain::TrafficRecovery::ConsecutiveSuccesses.new
-        else
-          raise Domain::Error::ConfigurationError, <<~ERROR
-            unsupported traffic_recovery strategy provided (`#{traffic_recovery}`). Supported options:
-              * :consecutive_successes
-          ERROR
-        end
-      end
-
-      private def validate!
-        validate_traffic_control!(container.resolve(:traffic_control), container.resolve(:config))
-        validate_traffic_recovery!(container.resolve(:traffic_recovery), container.resolve(:config))
-      end
-
-      private def validate_traffic_control!(traffic_control, config)
-        traffic_control.check_compatibility(config).then do |compatibility_result|
-          if compatibility_result.incompatible?
-            raise Domain::Error::ConfigurationError.new(
-              "#{traffic_control.class.name} strategy is incompatible with the Stoplight configuration: #{compatibility_result.error_messages}"
-            )
-          end
-        end
-      end
-
-      private def validate_traffic_recovery!(traffic_recovery, config)
-        traffic_recovery.check_compatibility(config).then do |compatibility_result|
-          if compatibility_result.incompatible?
-            raise Domain::Error::ConfigurationError.new(
-              "#{traffic_recovery.class.name} strategy is incompatible with the Stoplight configuration: #{compatibility_result.error_messages}"
-            )
-          end
-        end
-      end
+      def light_factory = self
     end
   end
 end

data/lib/stoplight/wiring/memory/backend.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module Memory
+      # In-memory storage backend for single-process deployments.
+      #
+      # All storage components use thread-safe in-memory data structures.
+      # State is not shared across processes and is lost on restart.
+      #
+      # Memory backend is also used as the fallback layer for Redis backend
+      # when Redis is unavailable.
+      #
+      # @example
+      #   backend = Memory::Backend.new(clock: SystemClock.new, config:)
+      #   backend.state_store #=> Memory::Storage::State
+      #
+      # @api private
+      class Backend < DataStoreBackend
+        def initialize(clock:, config:)
+          @clock = clock
+          @config = config
+        end
+
+        def state_store
+          @state_store ||= Infrastructure::Memory::Storage::State.new(
+            clock: @clock,
+            cool_off_time: @config.cool_off_time
+          )
+        end
+
+        def recovery_lock_store
+          @recovery_lock_store ||= Infrastructure::Memory::Storage::RecoveryLock.new
+        end
+
+        def recovery_metrics_store
+          @recovery_metrics_store ||= Infrastructure::Memory::Storage::RecoveryMetrics.new(
+            clock: @clock
+          )
+        end
+
+        def windowed_metrics_store
+          @windowed_metrics_store ||= Infrastructure::Memory::Storage::WindowMetrics.new(
+            window_size: T.must(@config.window_size),
+            clock: @clock
+          )
+        end
+
+        def unbounded_metrics_store
+          @unbounded_metrics_store ||= Infrastructure::Memory::Storage::UnboundedMetrics.new(
+            clock: @clock
+          )
+        end
+      end
+    end
+  end
+end