stoplight 5.0.3 → 5.2.0

data/lib/stoplight.rb

@@ -3,16 +3,20 @@
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("io" => "IO")
+loader.inflector.inflect("io" => "IO", "dsl" => "DSL")
 loader.do_not_eager_load(
   "#{__dir__}/stoplight/data_store",
   "#{__dir__}/stoplight/admin",
   "#{__dir__}/stoplight/admin.rb"
 )
+loader.ignore("#{__dir__}/generators")
 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
+
   CONFIG_MUTEX = Mutex.new
   private_constant :CONFIG_MUTEX
 
@@ -26,7 +30,7 @@ module Stoplight # rubocop:disable Style/Documentation
     # It raises an error if called more than once.
     #
     # @yield [config] Provides a configuration object to the block.
-    # @yieldparam config [Stoplight::Config::ProgrammaticConfig] The configuration object.
+    # @yieldparam config [Stoplight::Config::UserDefaultConfig] The configuration object.
     # @raise [Stoplight::Error::ConfigurationError] If the library is already configured.
     # @return [void]
     #
@@ -46,7 +50,7 @@ module Stoplight # rubocop:disable Style/Documentation
     #   produces a warning:
     #
     #     "Stoplight reconfigured. Existing circuit breakers will not see the new configuration. New
-    #       configuration: #<Stoplight::Config::ConfigProvider cool_off_time=32, threshold=3, window_size=94, tracked_errors=StandardError, skipped_errors=NoMemoryError,ScriptError,SecurityError,SignalException,SystemExit,SystemStackError, data_store=Stoplight::DataStore::Memory>\n"
+    #       configuration: ...f
     #
     #   If you really know what you are doing, you can pass the +trust_me_im_an_engineer+ parameter as +true+ to
     #   suppress this warning, which could be useful in test environments.
@@ -55,28 +59,47 @@ module Stoplight # rubocop:disable Style/Documentation
       user_defaults = Config::UserDefaultConfig.new
       yield(user_defaults) if block_given?
 
-      reconfigured = !@config_provider.nil?
+      reconfigured = !@default_config.nil?
 
-      @config_provider = Config::ConfigProvider.new(
-        user_default_config: user_defaults.freeze,
-        library_default_config: Config::LibraryDefaultConfig.new
-      ).tap do
+      @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: #{@config_provider.inspect}"
+              "New configuration: #{@default_config.inspect}"
           )
         end
       end
     end
 
+    # Creates a Light for internal use.
+    #
+    # @param name [String]
+    # @param settings [Hash]
+    # @return [Stoplight::Light]
+    # @api private
+    def system_light(name, **settings)
+      config = Config::SystemConfig.with(name:, **settings)
+      Stoplight::Light.new(config)
+    end
+
+    # Create a Light with the user default configuration.
+    #
+    # @param name [String]
+    # @param settings [Hash]
+    # @return [Stoplight::Light]
+    # @api private
+    def light(name, **settings)
+      config = Stoplight.default_config.with(name:, **settings)
+      Stoplight::Light.new(config)
+    end
+
     # Retrieves the current configuration provider.
     #
-    # @return [Stoplight::Config::ConfigProvider]
+    # @return [Stoplight::Light::Config]
     # @api private
-    def config_provider
+    def default_config
       CONFIG_MUTEX.synchronize do
-        @config_provider ||= configure
+        @default_config ||= configure
       end
     end
   end
@@ -94,6 +117,8 @@ 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
+#     traffic control strategy to use.
 #
 # @return [Stoplight::Light] A new circuit breaker instance.
 # @raise [ArgumentError] If an unknown option is provided in the settings.
@@ -117,7 +142,14 @@ end
 # @example configure skipped errors
 #   light = Stoplight("Payment API", skipped_errors: [ActiveRecord::RecordNotFound])
 #
+# @example configure traffic control to trip using consecutive failures method
+#   # When 5 consecutive failures occur, the circuit breaker will trip.
+#   light = Stoplight("Payment API", traffic_control: :consecutive_errors, threshold: 5)
+#
+# @example configure traffic control to trip using error rate method
+#   # When 66.6% error rate reached withing a sliding 5 minute window, the circuit breaker will trip.
+#   light = Stoplight("Payment API", traffic_control: :error_rate, threshold: 0.666, window_size: 300)
+#
 def Stoplight(name, **settings) # rubocop:disable Naming/MethodName
-  config = Stoplight.config_provider.provide(name, **settings)
-  Stoplight::Light.new(config)
+  Stoplight.light(name, **settings)
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 5.0.3
+  version: 5.2.0
 platform: ruby
 authors:
 - Cameron Desautels
 - Taylor Fausak
 - Justin Steffy
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-26 00:00:00.000000000 Z
+date: 2025-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -37,6 +38,9 @@ files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
+- lib/generators/stoplight/install/USAGE
+- lib/generators/stoplight/install/install_generator.rb
+- lib/generators/stoplight/install/templates/stoplight.rb.erb
 - lib/stoplight.rb
 - lib/stoplight/admin.rb
 - lib/stoplight/admin/actions/action.rb
@@ -55,8 +59,10 @@ files:
 - lib/stoplight/admin/views/index.erb
 - lib/stoplight/admin/views/layout.erb
 - lib/stoplight/color.rb
-- lib/stoplight/config/config_provider.rb
+- lib/stoplight/config/compatibility_result.rb
+- lib/stoplight/config/dsl.rb
 - lib/stoplight/config/library_default_config.rb
+- lib/stoplight/config/system_config.rb
 - lib/stoplight/config/user_default_config.rb
 - lib/stoplight/data_store.rb
 - lib/stoplight/data_store/base.rb
@@ -90,14 +96,16 @@ files:
 - lib/stoplight/rspec/generic_notifier.rb
 - lib/stoplight/state.rb
 - lib/stoplight/traffic_control/base.rb
-- lib/stoplight/traffic_control/consecutive_failures.rb
+- lib/stoplight/traffic_control/consecutive_errors.rb
+- lib/stoplight/traffic_control/error_rate.rb
 - lib/stoplight/traffic_recovery/base.rb
-- lib/stoplight/traffic_recovery/single_success.rb
+- lib/stoplight/traffic_recovery/consecutive_successes.rb
 - lib/stoplight/version.rb
 homepage: https://github.com/bolshakov/stoplight
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -112,7 +120,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Traffic control for code.
 test_files: []

data/lib/stoplight/config/config_provider.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Config
-    # Provides configuration for a Stoplight light by its name.
-    #
-    # It combines settings from three sources in the following order of precedence:
-    # 1. **Settings Overrides**: Explicit settings passed as arguments to +#provide+ method.
-    # 2. **User-level Default Settings**: Settings defined using the +Stoplight.configure+ method.
-    # 4. **Library-Level Default Settings**: Default settings defined in the +Stoplight::Config::UserDefaultConfig+ module.
-    #
-    # The settings are merged in this order, with higher-precedence settings overriding lower-precedence ones.
-    #
-    # @api private
-    class ConfigProvider
-      # @!attribute [r] default_settings
-      #   @return [Hash]
-      private attr_reader :default_settings
-
-      # @param user_default_config [Stoplight::Config::UserDefaultConfig]
-      # @param library_default_config [Stoplight::Config::LibraryDefaultConfig]
-      # @raise [Error::ConfigurationError] if both user_default_config and legacy_config are not empty
-      def initialize(user_default_config:, library_default_config:)
-        @default_settings = library_default_config.to_h.merge(
-          user_default_config.to_h
-        )
-      end
-
-      # @return [Stoplight::DataStore::Base]
-      def data_store
-        default_settings.fetch(:data_store)
-      end
-
-      # Returns a configuration for a specific light with the given name and settings overrides.
-      #
-      # @param light_name [Symbol, String] The name of the light.
-      # @param settings_overrides [Hash] The settings to override.
-      #   @see +Stoplight()+
-      # @return [Stoplight::Light::Config] The configuration for the specified light.
-      # @raise [Error::ConfigurationError]
-      def provide(light_name, **settings_overrides)
-        raise Error::ConfigurationError, <<~ERROR if settings_overrides.has_key?(:name)
-          The +name+ setting cannot be overridden in the configuration.
-        ERROR
-
-        settings = default_settings.merge(settings_overrides, {name: light_name})
-        Light::Config.new(**settings)
-      end
-
-      def inspect
-        "#<#{self.class.name} " \
-          "cool_off_time=#{default_settings[:cool_off_time]}, " \
-          "threshold=#{default_settings[:threshold]}, " \
-          "window_size=#{default_settings[:window_size]}, " \
-          "tracked_errors=#{default_settings[:tracked_errors].join(",")}, " \
-          "skipped_errors=#{default_settings[:skipped_errors].join(",")}, " \
-          "data_store=#{default_settings[:data_store].class.name}" \
-        ">"
-      end
-    end
-  end
-end

data/lib/stoplight/traffic_recovery/single_success.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficRecovery
-    # A basic strategy that recovers traffic flow after a successful recovery probe.
-    #
-    # This strategy allows traffic to resume when a single successful probe
-    # occurs after the Stoplight has been in red state. It's a simple "one success and we're back"
-    # approach.
-    #
-    # @example Basic usage
-    #   config = Stoplight::Light::Config.new(cool_off_time: 60)
-    #   strategy = Stoplight::TrafficRecovery::SingleSuccess.new
-    #
-    # After the Stoplight turns red:
-    # - The Stoplight will wait for the cool-off period (60 seconds)
-    # - Then enter the recovery phase (YELLOW color)
-    # - The first successful probe will resume normal traffic flow (green color)
-    # @api private
-    class SingleSuccess < Base
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [String]
-      def determine_color(config, metadata)
-        recovery_started_at = metadata.recovery_started_at || metadata.recovery_scheduled_after
-        last_success_at = metadata.last_success_at
-        if last_success_at && recovery_started_at <= last_success_at
-          Color::GREEN
-        else
-          Color::RED
-        end
-      end
-    end
-  end
-end