stoplight 5.4.0 → 5.5.0

data/lib/stoplight/{data_store/fail_safe.rb → wiring/fail_safe_data_store.rb}

@@ -3,32 +3,41 @@
 require "securerandom"
 
 module Stoplight
-  module DataStore
+  module Wiring
     # A wrapper around a data store that provides fail-safe mechanisms using a
     # circuit breaker. It ensures that operations on the data store can gracefully
     # handle failures by falling back to default values when necessary.
     #
     # @api private
-    class FailSafe < Base
+    class FailSafeDataStore < Domain::DataStore
       class << self
         # Wraps a data store with fail-safe mechanisms.
         #
         # @param data_store [Stoplight::DataStore::Base] The data store to wrap.
+        # @param error_notifier [Proc] called when wrapped data store fails
         # @return [Stoplight::DataStore::Base, FailSafe] The original data store if it is already
         #   a +Memory+ or +FailSafe+ instance, otherwise a new +FailSafe+ instance.
-        def wrap(data_store)
+        def wrap(data_store:, error_notifier:)
           case data_store
-          when Memory, FailSafe
+          in Infrastructure::DataStore::Memory
             data_store
+          in self if data_store.error_notifier == error_notifier
+            data_store
+          in self
+            new(data_store: data_store.data_store, error_notifier:)
           else
-            new(data_store)
+            new(data_store:, error_notifier:)
           end
         end
       end
 
       # @!attribute data_store
       #  @return [Stoplight::DataStore::Base] The underlying primary data store being used
-      protected attr_reader :data_store
+      attr_reader :data_store
+
+      # @!attribute error_notifier
+      #   @return [Proc]
+      attr_reader :error_notifier
 
       # @!attribute failover_data_store
       #   @return [Stoplight::DataStore::Base] The fallback data store used when the primary fails.
@@ -38,11 +47,13 @@ module Stoplight
       #   @return [Stoplight::Light] The circuit breaker used to handle data store failures.
       private attr_reader :circuit_breaker
 
-      # @param data_store [Stoplight::DataStore::Base]
-      def initialize(data_store, failover_data_store: Default::DATA_STORE)
+      # @param data_store [Stoplight::Domain::DataStore]
+      # @param error_notifier [Proc]
+      def initialize(data_store:, error_notifier:, failover_data_store: Wiring::Default::DATA_STORE)
         @data_store = data_store
+        @error_notifier = error_notifier
         @failover_data_store = failover_data_store
-        @circuit_breaker = Stoplight.system_light("stoplight:data_store:fail_safe:#{data_store.class.name}")
+        @circuit_breaker = Stoplight.system_light("data_store:fail_safe:#{data_store.class.name}")
       end
 
       def names
@@ -94,14 +105,14 @@ module Stoplight
       end
 
       def ==(other)
-        other.is_a?(self.class) && other.data_store == data_store
+        other.is_a?(self.class) && other.data_store == data_store && other.error_notifier == error_notifier
       end
 
       # @param method_name [Symbol] protected method name
       private def with_fallback(method_name, *args, **kwargs, &code)
         fallback = proc do |error|
           config = args.first
-          config.error_notifier.call(error) if config && error
+          error_notifier.call(error) if config && error
           @failover_data_store.public_send(method_name, *args, **kwargs)
         end
 

data/lib/stoplight/{notifier/fail_safe.rb → wiring/fail_safe_notifier.rb}

@@ -1,50 +1,59 @@
 # frozen_string_literal: true
 
 module Stoplight
-  module Notifier
+  module Wiring
     # A wrapper around a notifier that provides fail-safe mechanisms using a
     # circuit breaker. It ensures that a notification can gracefully
     # handle failures.
     #
     # @api private
-    class FailSafe < Base
+    class FailSafeNotifier < Domain::StateTransitionNotifier
       # @!attribute [r] notifier
-      #   @return [Stoplight::Notifier::Base] The underlying notifier being wrapped.
-      protected attr_reader :notifier
+      #   @return [Stoplight::Domain::StateTransitionNotifier] The underlying notifier being wrapped.
+      attr_reader :notifier
+
+      # @!attribute [r] error_notifier
+      #   @return [Stoplight::Domain::StateTransitionNotifier] The underlying notifier being wrapped.
+      attr_reader :error_notifier
 
       class << self
         # Wraps a notifier with fail-safe mechanisms.
         #
-        # @param notifier [Stoplight::Notifier::Base] The notifier to wrap.
+        # @param notifier [Stoplight::Domain::StateTransitionNotifier] The notifier to wrap.
+        # @param error_notifier [Proc] called when wrapped data store fails
         # @return [Stoplight::Notifier::FailSafe] The original notifier if it is already
         #   a +FailSafe+ instance, otherwise a new +FailSafe+ instance.
-        def wrap(notifier)
+        def wrap(notifier:, error_notifier:)
           case notifier
-          when FailSafe
+          in self if notifier.error_notifier == error_notifier
             notifier
+          in self
+            new(notifier: notifier.notifier, error_notifier:)
           else
-            new(notifier)
+            new(notifier:, error_notifier:)
           end
         end
       end
 
       # Initializes a new instance of the +FailSafe+ class.
       #
-      # @param notifier [Stoplight::Notifier::Base] The notifier to wrap.
-      def initialize(notifier)
+      # @param notifier [Stoplight::Domain::StateTransitionNotifier] The notifier to wrap.
+      # @param error_notifier [Proc] called when wrapped data store fails
+      def initialize(notifier:, error_notifier:)
         @notifier = notifier
+        @error_notifier = error_notifier
       end
 
       # Sends a notification using the wrapped notifier with fail-safe mechanisms.
       #
-      # @param config [Stoplight::Light::Config] The light configuration.
+      # @param config [Stoplight::Domain::Config] The light configuration.
       # @param from_color [String] The initial color of the light.
       # @param to_color [String] The target color of the light.
       # @param error [Exception, nil] An optional error to include in the notification.
       # @return [void]
       def notify(config, from_color, to_color, error = nil)
         fallback = proc do |exception|
-          config.error_notifier.call(exception) if exception
+          error_notifier.call(exception) if exception
           nil
         end
 
@@ -55,7 +64,7 @@ module Stoplight
 
       # @return [Boolean]
       def ==(other)
-        other.is_a?(FailSafe) && notifier == other.notifier
+        other.is_a?(self.class) && notifier == other.notifier
       end
 
       # @return [Stoplight::Light] The circuit breaker used to handle failures.

data/lib/stoplight/wiring/light/default_config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module Light
+      # Provides default settings for the Stoplight library.
+      # @api private
+      DefaultConfig = Domain::Config.empty.with(
+        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
+      )
+    end
+  end
+end

data/lib/stoplight/wiring/light/system_config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module Light
+      SystemConfig = DefaultConfig.with(
+        recovery_threshold: 3
+      )
+    end
+  end
+end

data/lib/stoplight/wiring/light_factory.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Concrete factory for building +Stoplight::Light++ instances with full dependency wiring.
+    #
+    # This factory implements the +Stoplight::Domain::LightFactory+ protocol. It knows how to:
+    #   1. Parse and transform user-provided settings
+    #   2. Wire together all Light dependencies using a DI container
+    #   3. Validate configuration compatibility
+    #   4. Construct fully-functional Light instances
+    #
+    # @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
+      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)
+      end
+
+      # Builds a fully-configured Light instance.
+      #
+      # The method resolves all dependencies from the container and constructs a Light that's
+      # ready to use. The Light is injected with a reference to this factory, allowing the
+      # +Stoplight::Light#with+ method to work for reconfiguration.
+      #
+      # @return [Stoplight::Light] Configured circuit breaker
+      # @raise [Stoplight::Error::ConfigurationError] If configuration is invalid
+      #
+      # @example
+      #   factory = Stoplight::Wiring::LightFactory.new(container)
+      #   light = factory.build
+      #
+      #   # Light is ready to use
+      #   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
+        )
+      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)
+      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(", ")}"
+      end
+
+      private def transform_settings(settings)
+        settings.dup.tap do |transformed_settings|
+          transform_config_settings!(transformed_settings)
+          transform_dependencies_settings!(transformed_settings)
+        end
+      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
+
+        if settings.key?(:cool_off_time)
+          settings[:cool_off_time] = normalize_cool_off_time(settings[:cool_off_time])
+        end
+      end
+
+      private def transform_dependencies_settings!(settings)
+        if settings.key?(:traffic_control)
+          settings[:traffic_control] = apply_traffic_control_dsl(settings[:traffic_control])
+        end
+
+        if settings.key?(:traffic_recovery)
+          settings[:traffic_recovery] = apply_traffic_recovery_dsl(settings[:traffic_recovery])
+        end
+      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
+    end
+  end
+end

data/lib/stoplight/wiring/public_api.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Public API facade for backward compatibility and convenience
+    # @api public
+    module PublicApi
+      # Aliases for domain concepts
+      Color = Domain::Color
+      Error = Domain::Error
+      State = Domain::State
+
+      # Namespace aliases for data stores
+      module DataStore
+        Redis = Infrastructure::DataStore::Redis
+        Memory = Infrastructure::DataStore::Memory
+      end
+
+      # Namespace aliases for notifiers
+      module Notifier
+        Base = Domain::StateTransitionNotifier
+        Generic = Infrastructure::Notifier::Generic
+        IO = Infrastructure::Notifier::IO
+        Logger = Infrastructure::Notifier::Logger
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/system_container.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    SystemContainer = Container.with(
+      traffic_recovery: Domain::TrafficRecovery::ConsecutiveSuccesses.new
+    )
+  end
+end

data/lib/stoplight/wiring/system_light_factory.rb

@@ -0,0 +1,17 @@
+# frozon_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Factory for internal system lights used by the Stoplight itself.
+    #
+    # System lights are isolated from user configuration to prevent
+    # user settings from breaking the library's own circuit breakers.
+    # For example, the FailSafe data store wrapper uses a system light
+    # to protect against data store failures.
+    #
+    # @api private
+    SystemLightFactory = Wiring::LightFactory.new(
+      Wiring::SystemContainer.with(config: Light::SystemConfig)
+    )
+  end
+end

data/lib/stoplight.rb

@@ -3,7 +3,7 @@
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("io" => "IO", "dsl" => "DSL")
+loader.inflector.inflect("io" => "IO")
 loader.do_not_eager_load(
   "#{__dir__}/stoplight/data_store",
   "#{__dir__}/stoplight/admin",
@@ -14,24 +14,19 @@ loader.ignore("#{__dir__}/stoplight/rspec.rb", "#{__dir__}/stoplight/rspec")
 loader.setup
 
 module Stoplight # rubocop:disable Style/Documentation
-  CONFIG_DSL = Config::DSL.new
-  private_constant :CONFIG_DSL
+  include Wiring::PublicApi
 
   CONFIG_MUTEX = Mutex.new
   private_constant :CONFIG_MUTEX
 
   class << self
-    ALREADY_CONFIGURED_WARNING = "Stoplight must be configured only once"
-    private_constant :ALREADY_CONFIGURED_WARNING
-
     # Configures the Stoplight library.
     #
     # This method allows you to set up the library's configuration using a block.
     # It raises an error if called more than once.
     #
     # @yield [config] Provides a configuration object to the block.
-    # @yieldparam config [Stoplight::Config::UserDefaultConfig] The configuration object.
-    # @raise [Stoplight::Error::ConfigurationError] If the library is already configured.
+    # @yieldparam config [Stoplight::Wiring::DefaultConfiguration] The configuration object.
     # @return [void]
     #
     # @example
@@ -56,18 +51,12 @@ module Stoplight # rubocop:disable Style/Documentation
     #   suppress this warning, which could be useful in test environments.
     #
     def configure(trust_me_im_an_engineer: false)
-      user_defaults = Config::UserDefaultConfig.new
-      yield(user_defaults) if block_given?
-
-      reconfigured = !@default_config.nil?
+      warn_if_reconfiguring(trust_me_im_an_engineer) do
+        factory_builder = Wiring::DefaultFactoryBuilder.new
+        yield factory_builder.configuration if block_given?
 
-      @default_config = Config::LibraryDefaultConfig.with(**user_defaults.to_h).tap do
-        if reconfigured && !trust_me_im_an_engineer
-          warn(
-            "Stoplight reconfigured. Existing circuit breakers will not see new configuration. " \
-              "New configuration: #{@default_config.inspect}"
-          )
-        end
+        @default_configuration = factory_builder.configuration
+        @default_light_factory = factory_builder.build
       end
     end
 
@@ -78,8 +67,7 @@ module Stoplight # rubocop:disable Style/Documentation
     # @return [Stoplight::Light]
     # @api private
     def system_light(name, **settings)
-      config = Config::SystemConfig.with(name:, **settings)
-      Stoplight::Light.new(config)
+      Wiring::SystemLightFactory.build_with(name: "__stoplight__#{name}", **settings)
     end
 
     # Create a Light with the user default configuration.
@@ -89,18 +77,40 @@ module Stoplight # rubocop:disable Style/Documentation
     # @return [Stoplight::Light]
     # @api private
     def light(name, **settings)
-      config = Stoplight.default_config.with(name:, **settings)
-      Stoplight::Light.new(config)
+      __stoplight__default_light_factory.build_with(name:, **settings)
     end
 
-    # Retrieves the current configuration provider.
+    # Retrieves the current default dependencies.
     #
-    # @return [Stoplight::Light::Config]
+    # @return [Stoplight::Domain::LightFactory]
+    # @api private
+    def __stoplight__default_light_factory
+      ensure_configured
+      @default_light_factory
+    end
+
+    def __stoplight__default_configuration
+      ensure_configured
+      @default_configuration
+    end
+
     # @api private
-    def default_config
+    private def ensure_configured
       CONFIG_MUTEX.synchronize do
-        @default_config ||= configure
+        configure unless configured?
+      end
+    end
+
+    private def warn_if_reconfiguring(trust_me_im_an_engineer)
+      if configured? && !trust_me_im_an_engineer
+        warn "Stoplight reconfigured. Existing circuit breakers will not see new configuration"
       end
+      yield
+      @configured = true
+    end
+
+    private def configured?
+      @configured == true
     end
   end
 end
@@ -117,7 +127,7 @@ end
 #   @option settings [Numeric] :window_size The size of the rolling window for failure tracking.
 #   @option settings [Array<StandardError>] :tracked_errors A list of errors to track.
 #   @option settings [Array<Exception>] :skipped_errors A list of errors to skip.
-#   @option settings [Stoplight::TrafficControl::Base, Symbol, {Symbol, Hash{Symbol, any}}] :traffic_control The
+#   @option settings [Symbol, {Symbol, Hash{Symbol, any}}] :traffic_control The
 #     traffic control strategy to use.
 #
 # @return [Stoplight::Light] A new circuit breaker instance.