stoplight 5.6.0 → 5.8.0

data/lib/stoplight.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "concurrent/map"
 require "zeitwerk"
 
+# steep:ignore:start
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect("io" => "IO")
 loader.do_not_eager_load(
@@ -12,19 +14,21 @@ loader.do_not_eager_load(
 loader.ignore("#{__dir__}/generators")
 loader.ignore("#{__dir__}/stoplight/rspec.rb", "#{__dir__}/stoplight/rspec")
 loader.setup
+# steep:ignore:end
 
 module Stoplight # rubocop:disable Style/Documentation
-  include Wiring::PublicApi
+  T = Types
 
   CONFIG_MUTEX = Mutex.new
   private_constant :CONFIG_MUTEX
+  @systems = Concurrent::Map.new
 
   class << self
     # 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.
-    #
+    # @param trust_me_im_an_engineer [Boolean]
     # @yield [config] Provides a configuration object to the block.
     # @yieldparam config [Stoplight::Wiring::DefaultConfiguration] The configuration object.
     # @return [void]
@@ -52,32 +56,175 @@ module Stoplight # rubocop:disable Style/Documentation
     #
     def configure(trust_me_im_an_engineer: false)
       warn_if_reconfiguring(trust_me_im_an_engineer) do
-        factory_builder = Wiring::DefaultFactoryBuilder.new
-        yield factory_builder.configuration if block_given?
+        configuration = Wiring::DefaultConfiguration.new
+        yield configuration if block_given?
 
-        @default_configuration = factory_builder.configuration
-        @default_light_factory = factory_builder.build
+        default_config = configuration.to_config!
+        @default_config = default_config
+        @default_light_factory = Wiring::LightFactory.new(config: default_config)
       end
     end
 
-    # Creates a Light for internal use.
-    #
-    # @param name [String]
-    # @param settings [Hash]
-    # @return [Stoplight::Light]
     # @api private
-    def system_light(name, **settings)
-      Wiring::SystemLightFactory.build_with(name: "__stoplight__#{name}", **settings)
+    def system_light(
+      name,
+      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
+    )
+      Wiring::LightFactory.new(config: Wiring::DefaultConfig).build_with(
+        name: "__stoplight__#{name}",
+        cool_off_time:,
+        threshold:,
+        recovery_threshold:,
+        window_size:,
+        tracked_errors:,
+        skipped_errors:,
+        data_store:,
+        error_notifier:,
+        notifiers:,
+        traffic_control:,
+        traffic_recovery:
+      )
     end
 
     # Create a Light with the user default configuration.
     #
-    # @param name [String]
-    # @param settings [Hash]
     # @return [Stoplight::Light]
     # @api private
-    def light(name, **settings)
-      __stoplight__default_light_factory.build_with(name:, **settings)
+    def light(
+      name,
+      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
+    )
+      __stoplight__default_light_factory.build_with(
+        name:,
+        cool_off_time:,
+        threshold:,
+        recovery_threshold:,
+        window_size:,
+        tracked_errors:,
+        skipped_errors:,
+        data_store:,
+        error_notifier:,
+        notifiers:,
+        traffic_control:,
+        traffic_recovery:
+      )
+    end
+
+    # Creates a new named system with the given configuration.
+    #
+    # Systems are composition roots that own infrastructure (data store, notifiers)
+    # and enforce configuration consistency for all lights created within them.
+    #
+    # @param name [String] Unique identifier for the system
+    # @param settings [Hash] Configuration options that override global defaults.
+    #   @see Stoplight() documentation
+    #
+    # @return [Stoplight::Wiring::System] A new system instance.
+    #
+    # @raise [ArgumentError] If a system with the given name already exists.
+    #
+    # @note Systems are not cached for reuse. Assign the returned system to a constant
+    #   for repeated access. Calling this method twice with the same name raises an error.
+    #
+    # @example Creating a system for payment services
+    #   Payments = Stoplight.__stoplight__system(:payments, threshold: 3, cool_off_time: 30)
+    #   Payments.light("stripe").run { process_payment }
+    #
+    # @example Isolated system with dedicated data store
+    #   Analytics = Stoplight.__stoplight__system(:analytics, data_store: analytics_redis)
+    #
+    # @api private
+    def __stoplight__system(
+      name,
+      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
+    )
+      ensure_configured
+
+      systems.compute(name.to_s) do |existing_system|
+        if existing_system
+          raise ArgumentError, "system `#{name}` is already in use"
+        else
+          Wiring::System.new(
+            config: Wiring::ConfigurationDsl.new(
+              name: name.to_s,
+              cool_off_time:,
+              threshold:,
+              recovery_threshold:,
+              window_size:,
+              tracked_errors:,
+              skipped_errors:,
+              traffic_control:,
+              traffic_recovery:,
+              data_store:,
+              error_notifier:,
+              notifiers:
+            ).configure!(default_config)
+          )
+        end
+      end
+    end
+
+    private attr_reader :systems
+    private def default_config = T.must(@default_config)
+
+    # Resets Stoplight to an unconfigured state.
+    #
+    # Clears all registered systems, default configuration, and the default light factory.
+    # After calling this method, the next call to +Stoplight()+ or +configure+ will
+    # initialize fresh state.
+    #
+    # @return [void]
+    #
+    # @note This method is intended for test suite setup/teardown. Do not use in production
+    #   code, as it orphans any existing light or system references, leading to split-brain
+    #   scenarios where different lights with the same name use different data stores.
+    #
+    # @note This method does not clean up state in external data stores (e.g., Redis keys).
+    #   It only resets in-process configuration.
+    #
+    # @example RSpec test setup
+    #   RSpec.configure do |config|
+    #     config.before do
+    #       Stoplight.__stoplight__reset!
+    #     end
+    #   end
+    #
+    # @api private
+    def __stoplight__reset!
+      @systems = Concurrent::Map.new
+      @default_config = nil
+      @default_light_factory = nil
+      @configured = nil
     end
 
     # Retrieves the current default dependencies.
@@ -86,12 +233,12 @@ module Stoplight # rubocop:disable Style/Documentation
     # @api private
     def __stoplight__default_light_factory
       ensure_configured
-      @default_light_factory
+      T.must(@default_light_factory)
     end
 
     def __stoplight__default_configuration
       ensure_configured
-      @default_configuration
+      T.must(@default_config)
     end
 
     # @api private
@@ -115,13 +262,12 @@ module Stoplight # rubocop:disable Style/Documentation
   end
 end
 
-# Creates a new Stoplight circuit breaker with the given name and settings.
+# Creates a new Stoplight circuit brNeaker with the given name and settings.
 #
 # @param name [String] The name of the circuit breaker.
 # @param settings [Hash] Optional settings to configure the circuit breaker.
 #   @option settings [Numeric] :cool_off_time The time to wait before resetting the circuit breaker.
 #   @option settings [Stoplight::DataStore::Base] :data_store The data store to use for storing state.
-#   @option settings [Proc] :error_notifier A proc to handle error notifications.
 #   @option settings [Array<Stoplight::Notifier::Base>] :notifiers A list of notifiers to use.
 #   @option settings [Numeric] :threshold The failure threshold to trip the circuit breaker.
 #   @option settings [Numeric] :window_size The size of the rolling window for failure tracking.
@@ -160,6 +306,46 @@ end
 #   # 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
-  Stoplight.light(name, **settings)
+def Stoplight(
+  name,
+  cool_off_time: Stoplight::T.undefined,
+  threshold: Stoplight::T.undefined,
+  recovery_threshold: Stoplight::T.undefined,
+  window_size: Stoplight::T.undefined,
+  tracked_errors: Stoplight::T.undefined,
+  skipped_errors: Stoplight::T.undefined,
+  data_store: Stoplight::T.undefined,
+  error_notifier: Stoplight::T.undefined,
+  notifiers: Stoplight::T.undefined,
+  traffic_control: Stoplight::T.undefined,
+  traffic_recovery: Stoplight::T.undefined
+) # rubocop:disable Naming/MethodName
+  Stoplight::Common::Deprecations.deprecate(<<~MSG) if error_notifier != Stoplight::T.undefined
+    Passing "error_notifier" to Stoplight('#{name}') is deprecated and will be removed in v6.0.0.
+
+    IMPORTANT: The `error_notifier` is NOT called for exceptions in your protected code.
+    It only reports internal Stoplight failures (e.g., Redis connection errors).
+
+    To fix: Move `error_notifier` to global configuration:
+
+      Stoplight.configure do |config|
+        config.error_notifier = ->(error) { Logger.warn(error) }
+      end
+
+    See: https://github.com/bolshakov/stoplight#error-notifiers
+  MSG
+  Stoplight.light(
+    name,
+    cool_off_time:,
+    threshold:,
+    recovery_threshold:,
+    window_size:,
+    tracked_errors:,
+    skipped_errors:,
+    data_store:,
+    error_notifier:,
+    notifiers:,
+    traffic_control:,
+    traffic_recovery:
+  )
 end

data/sig/_private/generators/stoplight/install/install_generator.rbs

@@ -0,0 +1,22 @@
+module Stoplight
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      ROUTES_PATH: String
+      STOPLIGHT_CONFIG_TEMPLATE: String
+      INITIALIZERS_PATH: String
+      AFTER_INSTALL_NOTIFICATION: String
+      STOPLIGHT_ADMIN_ROUTE: String
+      STOPLIGHT_AUTH: String
+
+      def options: -> Hash[Symbol, untyped]
+      def generate_redis_gem: -> void
+      def generate_sinatra_deps: -> void
+      def generate_initializer: -> void
+      def generate_admin_panel: -> void
+      def redis_configuration_notification: -> void
+
+      def copy_file: (String, String) -> void
+      def inject_into_file: (String path, String what, ?after: String) -> void
+    end
+  end
+end

data/sig/_private/stoplight/common/deprecations.rbs

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Common
+    module Deprecations
+      def deprecate: (String) -> void
+    end
+  end
+end

data/sig/_private/stoplight/data_store.rbs

@@ -0,0 +1,6 @@
+module Stoplight
+  module DataStore
+    class Base
+    end
+  end
+end

data/sig/_private/stoplight/domain/compatibility_result.rbs

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    class CompatibilityResult
+      def self.compatible: -> CompatibilityResult
+      def self.incompatible: (*String) -> CompatibilityResult
+
+      attr_reader errors: Array[String]
+
+      def initialize: (?errors: Array[String]) -> void
+
+      def compatible?: -> bool
+      def incompatible?: -> bool
+      def error_messages: -> String?
+    end
+  end
+end

data/sig/_private/stoplight/domain/config.rbs

@@ -0,0 +1,65 @@
+module Stoplight
+  module Domain
+    class Config < Data
+      attr_reader threshold: percentage | Integer
+      attr_reader window_size: duration?
+      attr_reader tracked_errors: Array[_ExceptionMatcher]
+      attr_reader skipped_errors: Array[_ExceptionMatcher]
+      attr_reader name: String
+      attr_reader cool_off_time: duration
+      attr_reader recovery_threshold: Integer
+      attr_reader traffic_control: _TrafficControl
+      attr_reader traffic_recovery: _TrafficRecovery
+      attr_reader error_notifier: error_notifier
+      attr_reader notifiers: Array[state_transition_notifier]
+      attr_reader data_store: data_store
+
+      def self.new: (
+          name: String,
+          cool_off_time: duration,
+          threshold: percentage | Integer,
+          recovery_threshold: Integer,
+          window_size: duration?,
+          tracked_errors: Array[_ExceptionMatcher],
+          skipped_errors: Array[_ExceptionMatcher],
+          traffic_control: _TrafficControl,
+          traffic_recovery: _TrafficRecovery,
+          error_notifier: error_notifier,
+          notifiers: Array[state_transition_notifier],
+          data_store: data_store
+        ) -> instance
+
+      def initialize: (
+          name: String,
+          cool_off_time: duration,
+          threshold: percentage | Integer,
+          recovery_threshold: Integer,
+          window_size: duration?,
+          tracked_errors: Array[_ExceptionMatcher],
+          skipped_errors: Array[_ExceptionMatcher],
+          traffic_control: _TrafficControl,
+          traffic_recovery: _TrafficRecovery,
+          error_notifier: error_notifier,
+          notifiers: Array[state_transition_notifier],
+          data_store: data_store
+        ) -> void
+
+      def cool_off_time_in_milliseconds: () -> Integer
+
+      def with: (
+          ?name: optional[String],
+          ?cool_off_time: optional[duration],
+          ?threshold: optional[percentage | Integer],
+          ?recovery_threshold: optional[Integer],
+          ?window_size: optional[duration?],
+          ?tracked_errors: optional[Array[_ExceptionMatcher]],
+          ?skipped_errors: optional[Array[_ExceptionMatcher]],
+          ?traffic_control: optional[_TrafficControl],
+          ?traffic_recovery: optional[_TrafficRecovery],
+          ?error_notifier: optional[error_notifier],
+          ?notifiers: optional[Array[state_transition_notifier]],
+          ?data_store: optional[data_store],
+      ) -> Config | () -> Config
+    end
+  end
+end

data/sig/_private/stoplight/domain/error_tracking_policy.rbs

@@ -0,0 +1,14 @@
+module Stoplight
+  module Domain
+    class ErrorTrackingPolicy
+      @tracked: Array[_ExceptionMatcher]
+      @skipped: Array[_ExceptionMatcher]
+
+      def initialize: (tracked: Array[_ExceptionMatcher], skipped: Array[_ExceptionMatcher]) -> void
+      def track?: (StandardError) -> bool
+
+      def skipped?: (StandardError) -> bool
+      def tracked?: (StandardError) -> bool
+    end
+  end
+end

data/sig/_private/stoplight/domain/failure.rbs

@@ -0,0 +1,16 @@
+module Stoplight
+  module Domain
+    class Failure
+      attr_reader error_class: String
+      attr_reader error_message: String
+      attr_reader time: Time
+      alias occurred_at time
+
+      def self.from_error: (StandardError error, time: Time) -> Failure
+
+      def initialize: (String error_class, String error_message, Time time) -> void
+
+      def ==: (untyped other) -> bool
+    end
+  end
+end

data/sig/_private/stoplight/domain/light.rbs

@@ -0,0 +1,25 @@
+module Stoplight
+  module Domain
+    class Light
+      include _Light
+      attr_reader green_run_strategy: Strategies::GreenRunStrategy
+      attr_reader yellow_run_strategy: Strategies::YellowRunStrategy
+      attr_reader red_run_strategy: Strategies::RedRunStrategy
+      attr_reader state_store: Domain::_StateStore
+      attr_reader factory: _LightFactory
+      @name: String
+
+      def initialize: (
+        String name,
+        green_run_strategy: Strategies::GreenRunStrategy,
+        yellow_run_strategy: Strategies::YellowRunStrategy,
+        red_run_strategy: Strategies::RedRunStrategy,
+        factory: _LightFactory,
+        state_store: Domain::_StateStore
+      ) -> void
+
+      private def state_strategy_factory: (color) -> _RunStrategy
+      private def state_snapshot: -> StateSnapshot
+    end
+  end
+end

data/sig/_private/stoplight/domain/light_info.rbs

@@ -0,0 +1,19 @@
+module Stoplight
+  module Domain
+    class LightInfo < Data
+      include _LightInfo
+
+      def self.new: (
+          name: String,
+        ) -> instance
+
+      def initialize: (
+          name: String,
+        ) -> void
+
+      def with: (
+          ?name: String,
+      ) -> LightInfo
+    end
+  end
+end

data/sig/_private/stoplight/domain/metrics_snapshot.rbs

@@ -0,0 +1,38 @@
+module Stoplight
+  module Domain
+    class MetricsSnapshot < Data
+      attr_reader successes: Integer?
+      attr_reader errors: Integer?
+      attr_reader consecutive_errors: Integer
+      attr_reader consecutive_successes: Integer
+      attr_reader last_error: Failure?
+      attr_reader last_success_at: Time?
+
+      def self.new: (
+          successes: Integer?,
+          errors: Integer?,
+          consecutive_errors: Integer,
+          consecutive_successes: Integer,
+          last_error: Failure?,
+          last_success_at: Time?
+        ) -> instance
+
+      def initialize: (
+          successes: Integer?,
+          errors: Integer?,
+          consecutive_errors: Integer,
+          consecutive_successes: Integer,
+          last_error: Failure?,
+          last_success_at: Time?
+        ) -> void
+
+      def errors!: -> Integer
+      def successes!: -> Integer
+      def error_rate: () -> Float?
+
+      def requests: () -> Integer?
+
+      def last_error_at: () -> Time?
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/clock.rbs

@@ -0,0 +1,18 @@
+module Stoplight
+  module Domain
+    # Wall-clock interface for time-dependent operations.
+    #
+    # Provides a centralized definition of how Stoplight obtains and
+    # interprets time. All time-dependent components should use this
+    # interface rather than calling Time methods directly, ensuring
+    # consistent time handling across the library.
+    #
+    interface _Clock
+      # Returns the current time.
+      def current_time: () -> Time
+
+      # Converts a Unix timestamp to a Time object.
+      def at: (timestamp) -> Time
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/data_store.rbs

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    interface _DataStore
+      # Retrieves the names of all lights stored in the data store.
+      #
+      # @return An array of light names.
+      def names: -> Array[String]
+
+      # Retrieves metrics for a specific light configuration.
+      def get_metrics: (Config) -> Domain::MetricsSnapshot
+
+      # Retrieves recovery metrics for a specific light configuration.
+      def get_recovery_metrics: (Config) -> Domain::MetricsSnapshot
+
+      # Retrieves State Snapshot for a specific light configuration.
+      def get_state_snapshot: (Config) -> StateSnapshot
+
+      # Clears windowed metrics (successes/errors) to prevent
+      # stale failures from before recovery from affecting post-recovery decisions.
+      # Consecutive counts are intentionally preserved as they track current streaks.
+      def clear_metrics: (Config) -> void
+
+      def clear_recovery_metrics: (Config) -> void
+
+      # Records a failure for a specific light configuration.
+      def record_failure: (Config, StandardError exception) -> void
+
+      # Records a success for a specific light configuration.
+      def record_success: (Config) -> void
+
+      # Records a failed recovery probe for a specific light configuration.
+      def record_recovery_probe_failure: (Config, StandardError exception) -> void
+
+      # Records a successful recovery probe for a specific light configuration.
+      def record_recovery_probe_success: (Config) -> void
+
+      # Sets the state of a specific light configuration.
+      def set_state: (Config, state state) -> state
+
+      # Acquires recovery lock for serializing probe execution.
+      def acquire_recovery_lock: (Config) -> _RecoveryLockToken?
+
+      # Releases previously acquired lock.
+      def release_recovery_lock: (_RecoveryLockToken lock) -> void
+
+      # Transitions the Stoplight to the specified color.
+      #
+      # This method performs a color transition operation that works across distributed instances
+      # of the light. It ensures that in a multi-instance environment, only one instance
+      # is considered the "first" to perform the transition (and therefore responsible for
+      # triggering notifications).
+      #
+      # @param config
+      # @param color The target color/state to transition to.
+      #   Should be one of Stoplight::Color::GREEN, Stoplight::Color::YELLOW, or Stoplight::Color::RED.
+      #
+      # @return [Boolean] Returns +true+ if this instance was the first to perform this specific transition
+      #   (and should therefore trigger notifications). Returns +false+ if another instance already
+      #   initiated this transition.
+      #
+      # @note In distributed environments with multiple instances, race conditions can occur when instances
+      #   attempt conflicting transitions simultaneously (e.g., one instance tries to transition from
+      #   YELLOW to GREEN while another tries YELLOW to RED). The implementation handles this, but
+      #   be aware that the last operation may determine the final color of the light.
+      #
+      def transition_to_color: (Config, color color) -> bool
+
+      # Deletes metadata (and related persistent state) for the given light.
+      #
+      # Implementations may choose to only remove metadata; metrics may expire via TTL.
+      def delete_light: (Config) -> void
+    end
+  end
+end