stoplight 5.5.0 → 5.7.0

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

@@ -0,0 +1,48 @@
+# 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
+      #
+      # @see Stoplight::Domain::Storage::Metrics
+      class CompatibilityMetrics < Domain::Storage::Metrics
+        private attr_reader :data_store
+        private 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
+        end
+
+        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
+  end
+end

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

@@ -0,0 +1,36 @@
+# 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::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]
+        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)
+
+        # @param lock [Stoplight::Domain::LockToken]
+        # @return [void]
+        def release_lock(lock) = data_store.release_recovery_lock(lock)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# 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
+      #
+      # @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]
+        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
+        #
+        # @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)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# 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 < 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]
+        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)
+      end
+    end
+  end
+end

data/lib/stoplight/version.rb

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

data/lib/stoplight/wiring/data_store/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module DataStore
+      # @abstract
+      class Base
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module DataStore
+      class Memory < Base
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/data_store/redis.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module DataStore
+      class Redis < Base
+        # @!attribute redis
+        #   @return [::Redis, ConnectionPool<::Redis>]
+        attr_reader :redis
+
+        # @!attribute warn_on_clock_skew
+        #   @return [Boolean]
+        attr_reader :warn_on_clock_skew
+
+        # @param redis [::Redis, ConnectionPool<::Redis>]
+        # @param warn_on_clock_skew [Boolean] (true) Whether to warn about clock skew between Redis and
+        #   the application server
+        def initialize(redis, warn_on_clock_skew: true)
+          @warn_on_clock_skew = warn_on_clock_skew
+          @redis = redis
+        end
+      end
+    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 }
 

data/lib/stoplight/wiring/default_configuration.rb

@@ -37,7 +37,7 @@ module Stoplight
       attr_accessor :notifiers
 
       # @!attribute [rw] data_store
-      #   @return [Stoplight::Domain::DataStore] The default data store instance.
+      #   @return [Stoplight::Wiring::DataStore::Base] The default data store instance.
       attr_accessor :data_store
 
       # @!attribute [w] traffic_control

data/lib/stoplight/wiring/default_factory_builder.rb

@@ -18,7 +18,7 @@ module Stoplight
       # @return [Stoplight::Wiring::LightFactory]
       # @api private the method is used internally by Stoplight
       def build
-        LightFactory.new(Wiring::Container).with(**configuration.to_h)
+        LightFactory.new(configuration.to_h)
       end
     end
   end

data/lib/stoplight/wiring/light_builder.rb

@@ -0,0 +1,185 @@
+# 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
+
+      # @!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]
+      end
+
+      def build
+        Stoplight::Domain::Light.new(
+          config,
+          state_store:,
+          green_run_strategy:,
+          yellow_run_strategy:,
+          red_run_strategy:,
+          factory:
+        )
+      end
+
+      private def state_store = Stoplight::Infrastructure::Storage::CompatibilityState.new(config:, data_store:)
+
+      # @return [<Stoplight::Notifier::Base>]
+      private 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,
+          lock_timeout: config.cool_off_time_in_milliseconds,
+          scripting:
+        )
+      end
+
+      private def scripting = Infrastructure::DataStore::Redis::Scripting.new(redis: data_store_config.redis)
+
+      private def memory_recovery_lock_store
+        Infrastructure::DataStore::Memory::RecoveryLockStore.new
+      end
+
+      private def failover_data_store
+        create_data_store(FAILOVER_DATA_STORE_CONFIG)
+      end
+
+      private def data_store
+        create_data_store(data_store_config)
+      end
+
+      private def metrics_store
+        Stoplight::Infrastructure::Storage::CompatibilityMetrics.new(config:, data_store:)
+      end
+
+      private def recovery_lock_store
+        Stoplight::Infrastructure::Storage::CompatibilityRecoveryLock.new(config:, data_store:)
+      end
+
+      private def request_tracker
+        Domain::Tracker::Request.new(traffic_control:, notifiers:, config:, metrics_store:, state_store:)
+      end
+
+      private def recovery_probe_tracker
+        Domain::Tracker::RecoveryProbe.new(
+          traffic_recovery:,
+          notifiers:,
+          config:,
+          metrics_store: recovery_metrics_store,
+          state_store:
+        )
+      end
+
+      private 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:)
+      end
+
+      private def yellow_run_strategy
+        Domain::Strategies::YellowRunStrategy.new(
+          config:,
+          notifiers:,
+          request_tracker: recovery_probe_tracker,
+          red_run_strategy:,
+          state_store:,
+          metrics_store:,
+          recovery_lock_store:
+        )
+      end
+
+      private def red_run_strategy
+        Domain::Strategies::RedRunStrategy.new(config:)
+      end
+
+      private def create_data_store(data_store_config)
+        case data_store_config
+        in 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
+            )
+          end
+        in Stoplight::DataStore::Redis
+          Infrastructure::DataStore::FailSafe.new(
+            data_store: Stoplight::Infrastructure::DataStore::Redis.new(
+              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")
+          )
+        end
+      end
+
+      private def memory_registry = MEMORY_REGISTRY
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class LightFactory
+      # 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 CompatibilityValidator
+        private attr_reader :dependencies
+        private attr_reader :config
+
+        class << self
+          def call(config, dependencies) = new(config, dependencies).call
+        end
+
+        def initialize(config, dependencies)
+          @config = config
+          @dependencies = dependencies
+        end
+
+        def call
+          validate_traffic_control!
+          validate_traffic_recovery!
+        end
+
+        private def validate_traffic_control!
+          traffic_control = dependencies.fetch(:traffic_control)
+          traffic_control.check_compatibility(config).then do |compatibility_result|
+            if compatibility_result.incompatible?
+              raise Domain::Error::ConfigurationError,
+                "#{traffic_control.class.name} incompatible with config: #{compatibility_result.error_messages}"
+            end
+          end
+        end
+
+        def validate_traffic_recovery!
+          traffic_recovery = dependencies.fetch(:traffic_recovery)
+          traffic_recovery.check_compatibility(config).then do |compatibility_result|
+            if compatibility_result.incompatible?
+              raise Domain::Error::ConfigurationError,
+                "#{traffic_recovery.class.name} incompatible with config: #{compatibility_result.error_messages}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class LightFactory
+      # Normalizes user-provided configuration values into canonical forms.
+      #
+      # Handles common user convenience patterns:
+      # - Single error class → Array of error classes
+      # - Numeric cool_off_time → Integer
+      #
+      # @example
+      #   config = Config.empty.with(
+      #     tracked_errors: StandardError,  # Single class
+      #     cool_off_time: 30.5             # Float
+      #   )
+      #
+      #   normalized = ConfigNormalizer.call(config)
+      #   normalized.tracked_errors #=> [StandardError]  # Array
+      #   normalized.cool_off_time  #=> 30               # Integer
+      #
+      # @api private
+      class ConfigNormalizer
+        class << self
+          def call(config) = new(config).call
+        end
+
+        # @!attribute config
+        #   @return [Stoplight::Domain::Config]
+        private attr_reader :config
+
+        # @param [Stoplight::Domain::Config]
+        def initialize(config)
+          @config = config
+        end
+
+        # @return [Stoplight::Domain::Config]
+        def call
+          config
+            .then { |c| normalize_tracked_errors(c) }
+            .then { |c| normalize_skipped_errors(c) }
+            .then { |c| normalize_cool_off_time(c) }
+        end
+
+        private def normalize_tracked_errors(config)
+          if config.tracked_errors.is_a?(Array)
+            config
+          else
+            config.with(tracked_errors: Array(config.tracked_errors))
+          end
+        end
+
+        private def normalize_skipped_errors(config)
+          if config.skipped_errors.is_a?(Array)
+            config
+          else
+            config.with(skipped_errors: Array(config.skipped_errors))
+          end
+        end
+
+        private def normalize_cool_off_time(config)
+          if config.cool_off_time.is_a?(Integer)
+            config
+          else
+            config.with(cool_off_time: config.cool_off_time.to_i)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class LightFactory
+      # Orchestrates DSL interpretation, normalization, and validation.
+      #
+      # ConfigurationPipeline is the entry point for transforming raw user settings
+      # into validated domain objects. It coordinates three steps:
+      #
+      # 1. Normalization - Convert user-friendly values to canonical forms
+      # 2. DSL Interpretation - Transform symbols/hashes into strategy objects
+      # 3. Validation - Ensure strategies are compatible with configuration
+      #
+      # @api private
+      class ConfigurationPipeline
+        BASE_DEPENDENCIES = {
+          data_store: Default::DATA_STORE,
+          traffic_recovery: Default::TRAFFIC_RECOVERY,
+          traffic_control: Default::TRAFFIC_CONTROL,
+          notifiers: Default::NOTIFIERS,
+          error_notifier: Default::ERROR_NOTIFIER
+        }.freeze
+        private_constant :BASE_DEPENDENCIES
+
+        private attr_reader :dependency_settings
+        private attr_reader :config_settings
+
+        def self.process(config_settings, dependency_settings)
+          new(config_settings, dependency_settings).process
+        end
+
+        def initialize(config_settings, dependency_settings)
+          @config_settings = config_settings
+          @dependency_settings = dependency_settings
+        end
+
+        def process
+          config = build_config
+          dependencies = build_dependencies
+
+          CompatibilityValidator.call(config, dependencies)
+
+          [config, dependencies]
+        end
+
+        def build_config
+          base_config
+            .with(**config_settings)
+            .then { |cfg| ConfigNormalizer.call(cfg) }
+        end
+
+        def build_dependencies
+          base_dependencies
+            .merge(dependency_settings)
+            .then { |deps| interpret_dsl(deps) }
+        end
+
+        def interpret_dsl(dependencies)
+          dependencies.merge(
+            traffic_control: TrafficControlDsl.call(dependencies.fetch(:traffic_control)),
+            traffic_recovery: TrafficRecoveryDsl.call(dependencies.fetch(:traffic_recovery))
+          )
+        end
+
+        def base_config = Light::DefaultConfig
+
+        def base_dependencies = BASE_DEPENDENCIES
+      end
+    end
+  end
+end