stoplight 5.3.8 → 5.5.0

data/lib/stoplight/domain/light.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Stoplight
+  module Domain
+    #
+    # @api private use +Stoplight()+ method instead
+    class Light
+      extend Forwardable
+      include ConfigurationBuilderInterface
+
+      # @!attribute [r] config
+      #   @return [Stoplight::Domain::Config]
+      #   @api private
+      attr_reader :config
+
+      # @!attribute [r] name
+      #   The name of the light.
+      #   @return [String]
+      def_delegator :config, :name
+
+      # @!attribute [r] green_run_strategy
+      #   @return [Stoplight::Domain::Strategies::GreenRunStrategy]
+      protected attr_reader :green_run_strategy
+
+      # @!attribute [r] yellow_run_strategy
+      #   @return [Stoplight::Domain::Strategies::YellowRunStrategy]
+      protected attr_reader :yellow_run_strategy
+
+      # @!attribute [r] red_run_strategy
+      #   @return [Stoplight::Domain::Strategies::RedRunStrategy]
+      protected attr_reader :red_run_strategy
+
+      # @!attribute [r] data_store
+      #   @return [Stoplight::Light::Base]
+      protected attr_reader :data_store
+
+      # @!attribute [r] factory
+      #   @return [Stoplight::Domain::LightFactory]
+      protected attr_reader :factory
+
+      # @param config [Stoplight::Domain::Config]
+      def initialize(config, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, data_store:, factory:)
+        @config = config
+        @data_store = data_store
+        @green_run_strategy = green_run_strategy
+        @yellow_run_strategy = yellow_run_strategy
+        @red_run_strategy = red_run_strategy
+        @factory = factory
+      end
+
+      # Returns the current state of the light:
+      #  * +Stoplight::State::LOCKED_GREEN+ -- light is locked green and allows all traffic
+      #  * +Stoplight::State::LOCKED_RED+ -- light is locked red and blocks all traffic
+      #  * +Stoplight::State::UNLOCKED+ -- light is not locked and follow the configured rules
+      #
+      # @return [String]
+      def state
+        metadata.locked_state
+      end
+
+      # Returns current color:
+      #   * +Stoplight::Color::GREEN+ -- circuit breaker is closed
+      #   * +Stoplight::Color::RED+ -- circuit breaker is open
+      #   * +Stoplight::Color::YELLOW+ -- circuit breaker is half-open
+      #
+      # @example
+      #   light = Stoplight('example')
+      #   light.color #=> Color::GREEN
+      #
+      # @return [String] returns current light color
+      def color
+        metadata.color
+      end
+
+      # Runs the given block of code with this circuit breaker
+      #
+      # @example
+      #   light = Stoplight('example')
+      #   light.run { 2/0 }
+      #
+      # @example Running with fallback
+      #   light = Stoplight('example')
+      #   light.run(->(error) { 0 }) { 1 / 0 } #=> 0
+      #
+      # @param fallback [Proc, nil] (nil) fallback code to run if the circuit breaker is open
+      # @raise [Stoplight::Error::RedLight]
+      # @return [any]
+      # @raise [Stoplight::Error::RedLight]
+      def run(fallback = nil, &code)
+        raise ArgumentError, "nothing to run. Please, pass a block into `Light#run`" unless block_given?
+
+        metadata.then do |metadata|
+          strategy = state_strategy_factory(metadata.color)
+          strategy.execute(fallback, metadata:, &code)
+        end
+      end
+
+      # Locks light in either +State::LOCKED_RED+ or +State::LOCKED_GREEN+
+      #
+      # @example
+      #   light = Stoplight('example-locked')
+      #   light.lock(Stoplight::Color::RED)
+      #
+      # @param color [String] should be either +Color::RED+ or +Color::GREEN+
+      # @return [Stoplight::Light] returns locked light (circuit breaker)
+      def lock(color)
+        state = case color
+        when Color::RED then State::LOCKED_RED
+        when Color::GREEN then State::LOCKED_GREEN
+        else raise Error::IncorrectColor
+        end
+
+        data_store.set_state(config, state)
+
+        self
+      end
+
+      # Unlocks light and sets its state to State::UNLOCKED
+      #
+      # @example
+      #   light = Stoplight('example-locked')
+      #   light.lock(Stoplight::Color::RED)
+      #   light.unlock
+      #
+      # @return [Stoplight::Light] returns unlocked light (circuit breaker)
+      def unlock
+        data_store.set_state(config, State::UNLOCKED)
+
+        self
+      end
+
+      # Two lights considered equal if they have the same configuration.
+      #
+      # @param other [any]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) && config == other.config && data_store == other.data_store &&
+          green_run_strategy == other.green_run_strategy && yellow_run_strategy == other.yellow_run_strategy &&
+          red_run_strategy == other.red_run_strategy && factory == other.factory
+      end
+
+      # Reconfigures the light with updated settings and returns a new instance.
+      #
+      # This method allows you to modify the configuration of a +Stoplight::Light+ object
+      # by providing a hash of settings. The original light remains unchanged, and a new
+      # light instance with the updated configuration is returned.
+      #
+      # @param settings [Hash] A hash of configuration options to update.
+      # @option settings [String] :name The name of the light.
+      # @option settings [Numeric] :cool_off_time The cool-off time in seconds before the light attempts recovery.
+      # @option settings [Numeric] :threshold The failure threshold to trigger the red state.
+      # @option settings [Numeric] :window_size The time window in seconds for counting failures.
+      # @option settings [Stoplight::DataStore::Base] :data_store The data store to use for persisting light state.
+      # @option settings [Array<Stoplight::Domain::AbstractStateTransitionNotifier>] :notifiers A list of notifiers to handle light events.
+      # @option settings [Proc] :error_notifier A custom error notifier to handle exceptions.
+      # @option settings [Array<StandardError>] :tracked_errors A list of errors to track for failure counting.
+      # @option settings [Array<StandardError>] :skipped_errors A list of errors to skip from failure counting.
+      # @return [Stoplight::Light] A new `Stoplight::Light` instance with the updated configuration.
+      #
+      # @example Reconfiguring a light with custom settings
+      #   light = Stoplight('payment-api')
+      #
+      #   # Create a light for invoices with a higher threshold
+      #   invoices_light = light.with(tracked_errors: [TimeoutError], threshold: 10)
+      #
+      #   # Create a light for payments with a lower threshold
+      #   payment_light = light.with(threshold: 5)
+      #
+      #   # Run the lights with their respective configurations
+      #   invoices_light.run(->(error) { [] }) { call_invoices_api }
+      #   payment_light.run(->(error) { nil }) { call_payment_api }
+      # @see +Stoplight()+
+      def with(**settings)
+        factory.build_with(**settings)
+      end
+
+      private
+
+      def state_strategy_factory(color)
+        case color
+        when Color::GREEN
+          green_run_strategy
+        when Color::YELLOW
+          yellow_run_strategy
+        else
+          red_run_strategy
+        end
+      end
+
+      # @return [Stoplight::Domain::Metadata]
+      def metadata
+        data_store.get_metadata(config)
+      end
+    end
+  end
+end

data/lib/stoplight/domain/light_factory.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Abstract factory protocol for building +Stoplight::Light+ instances.
+    #
+    # This defines the interface that any Light factory must implement,
+    # regardless of the underlying implementation details.
+    #
+    # This uses the Abstract Factory pattern to decouple the domain (Light)
+    # from the application layer (concrete factory implementation). Light
+    # doesn't know HOW it's built, only that it needs something that can
+    # build variants of itself.
+    #
+    # By defining this interface in the domain layer:
+    # - Light can request reconfiguration without knowing about containers
+    # - Different factory implementations can be swapped (code, database-configured, etc.)
+    # - Dependency direction is preserved (Application → Domain, not Domain → Application)
+    #
+    # @abstract Subclasses must implement +#with+ and +#build+
+    # @api private
+    class LightFactory
+      # Creates a new factory with modified settings.
+      #
+      # This method must return a NEW factory instance - it should not
+      # modify the current factory. The new factory should inherit all
+      # configuration from the current factory, with the provided
+      # settings overriding specific values.
+      #
+      # @param settings [Hash] Configuration and dependency overrides
+      # @return [Stoplight::Domain::LightFactory] New factory with updated settings
+      # @raise [NotImplementedError] Must be implemented by subclass
+      # @abstract
+      # :nocov:
+      def with(**settings)
+        raise NotImplementedError
+      end
+
+      # Builds a +Stoplight::Light+ instance with the current configuration.
+      #
+      # This method must construct a fully-wired Light with all required
+      # dependencies (strategies, data store, notifiers, etc.). The Light
+      # should be ready to use immediately after construction.
+      #
+      # @return [Stoplight::Light] Configured circuit breaker instance
+      # @raise [NotImplementedError] Must be implemented by subclass
+      # @raise [Stoplight::Error::ConfigurationError] If configuration is invalid
+      # @abstract
+      def build
+        raise NotImplementedError
+      end
+      # :nocov:
+
+      # Convenience method to configure and build in one operation.
+      #
+      # This combines +#with+ and +#build+ into a single call, which is
+      # useful when you want to create a customized Light without keeping
+      # a reference to the intermediate factory.
+      #
+      # @param settings [Hash] Settings to override before building
+      # @return [Stoplight::Light] Configured circuit breaker instance
+      #
+      # @example Usage
+      #   # Instead of:
+      #   new_factory = factory.with(threshold: 10)
+      #   light = new_factory.build
+      #
+      #   # You can do:
+      #   light = factory.build_with(threshold: 10)
+      def build_with(**settings)
+        with(**settings).build
+      end
+    end
+  end
+end

data/lib/stoplight/domain/metadata.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # @api private
+    Metadata = Data.define(
+      :successes,
+      :errors,
+      :recovery_probe_successes,
+      :recovery_probe_errors,
+      :last_error_at,
+      :last_success_at,
+      :consecutive_errors,
+      :consecutive_successes,
+      :last_error,
+      :breached_at,
+      :locked_state,
+      :recovery_scheduled_after,
+      :recovery_started_at,
+      :recovered_at,
+      :current_time
+    ) do
+      # YELLOW color could be entered implicitly through a timeout
+      # and explicitly through a transition.
+      #
+      # This method indicates whether the recovery has already started explicitly
+      #
+      # @return [Boolean]
+      def recovery_started?
+        recovery_started_at && recovery_started_at <= current_time
+      end
+
+      # @return [String] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
+      def color
+        if locked_state == State::LOCKED_GREEN
+          Color::GREEN
+        elsif locked_state == State::LOCKED_RED
+          Color::RED
+        elsif (recovery_scheduled_after && recovery_scheduled_after < current_time) || recovery_started_at
+          Color::YELLOW
+        elsif breached_at
+          Color::RED
+        else
+          Color::GREEN
+        end
+      end
+
+      # Calculates the error rate based on the number of successes and errors.
+      #
+      # @return [Float]
+      def error_rate
+        if (successes + errors).zero?
+          0.0
+        else
+          errors.fdiv(successes + errors)
+        end
+      end
+
+      # @return [Integer]
+      def requests
+        successes + errors
+      end
+    end
+  end
+end

data/lib/stoplight/domain/state.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module State
+      UNLOCKED = "unlocked"
+      LOCKED_GREEN = "locked_green"
+      LOCKED_RED = "locked_red"
+    end
+  end
+end

data/lib/stoplight/{notifier/base.rb → domain/state_transition_notifier.rb}

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module Stoplight
-  module Notifier
+  module Domain
     # Base class for creating custom notifiers in Stoplight.
     # This is an abstract class that defines the interface for notifiers.
     #
     # @abstract Subclasses must implement the `notify` method to define custom notification logic.
-    # @see +Stoplight::Notifier::Generic+
-    class Base
+    # :nocov:
+    class StateTransitionNotifier # ColorTransition?????
       # Sends a notification when a Stoplight changes state.
       #
-      # @param config [Stoplight::Light::Config] The Stoplight instance triggering the notification.
+      # @param config [Stoplight::Domain::Config] The Stoplight instance triggering the notification.
       # @param from_color [String] The previous state color of the Stoplight.
       # @param to_color [String] The new state color of the Stoplight.
       # @param error [Exception, nil] The error (if any) that caused the state change.
@@ -20,5 +20,6 @@ module Stoplight
         raise NotImplementedError
       end
     end
+    # :nocov:
   end
 end

data/lib/stoplight/domain/strategies/green_run_strategy.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Strategies
+      # Defines how the light executes when it is green.
+      #
+      # This strategy clears failures after successful execution and handles errors
+      # by either raising them or invoking a fallback if provided.
+      #
+      # @api private
+      class GreenRunStrategy < RunStrategy
+        # @!attribute [r] request_tracker
+        #   @return [Stoplight::Domain::Tracker::Request]
+        protected attr_reader :request_tracker
+
+        # @!attribute [r] config
+        #   @return [Stoplight::Domain::Config] The configuration for the light.
+        protected attr_reader :config
+
+        # @param config [Stoplight::Domain::Config]
+        # @param request_tracker [Stoplight::Domain::Tracker::Request
+        def initialize(config:, request_tracker:)
+          @config = config
+          @request_tracker = request_tracker
+        end
+
+        # Executes the provided code block when the light is in the green state.
+        #
+        # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
+        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @yield The code block to execute.
+        # @return [Object] The result of the code block if successful.
+        # @raise [Exception] Re-raises the error if it is not tracked or no fallback is provided.
+        def execute(fallback, metadata:, &code)
+          # TODO: Consider implementing sampling rate to limit the memory footprint
+          code.call.tap { record_success }
+        rescue => error
+          if config.track_error?(error)
+            record_error(error)
+
+            if fallback
+              fallback.call(error)
+            else
+              raise
+            end
+          else
+            # User chose to not track the error, so we record it as a success
+            record_success
+            raise
+          end
+        end
+
+        private def record_error(error)
+          request_tracker.record_failure(error)
+        end
+
+        private def record_success
+          request_tracker.record_success
+        end
+
+        # @return [Boolean]
+        def ==(other)
+          super && config == other.config && request_tracker == other.request_tracker
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/strategies/red_run_strategy.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Strategies
+      # Defines how the light executes when it is red.
+      #
+      # This strategy prevents execution of the code block and either raises an error
+      # or invokes a fallback if provided.
+      #
+      # @api private
+      class RedRunStrategy < RunStrategy
+        # @!attribute [r] config
+        #   @return [Stoplight::Domain::Config] The configuration for the light.
+        protected attr_reader :config
+
+        def initialize(config:)
+          @config = config
+        end
+
+        # Executes the fallback proc when the light is in the red state.
+        #
+        # @param fallback [Proc, nil] A fallback proc to execute instead of the code block.
+        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @return [Object, nil] The result of the fallback proc if provided.
+        # @raise [Stoplight::Error::RedLight] Raises an error if no fallback is provided.
+        def execute(fallback, metadata:)
+          if fallback
+            fallback.call(nil)
+          else
+            raise Error::RedLight.new(
+              config.name,
+              cool_off_time: config.cool_off_time,
+              retry_after: metadata.recovery_scheduled_after
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/strategies/run_strategy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Strategies
+      # Represents an abstract strategy for running a light's operations.
+      # Every new strategy should be a child of this class.
+      #
+      # @api private
+      # @abstract
+      class RunStrategy
+        # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
+        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # :nocov:
+        def execute(fallback, metadata:, &code)
+          raise NotImplementedError, "Subclasses must implement the execute method"
+        end
+        # :nocov:
+
+        # @return [Boolean]
+        def ==(other)
+          other.is_a?(self.class)
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/strategies/yellow_run_strategy.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Strategies
+      # Defines how the light executes when it is yellow.
+      #
+      # This strategy clears failures after successful execution and notifies
+      # about color switch from Red to Green. It also handles errors by either
+      # raising them or invoking a fallback if provided.
+      #
+      # @api private
+      class YellowRunStrategy < RunStrategy
+        # @!attribute [r] config
+        #   @return [Stoplight::Domain::Config] The configuration for the light.
+        protected attr_reader :config
+
+        # @!attribute [r] data_store
+        #   @return [Stoplight::DataStore::Base] The data store associated with the light.
+        protected attr_reader :data_store
+
+        # @!attribute [r] notifiers
+        #   @return [Stoplight::Domain::StateTransitionNotifier]
+        protected attr_reader :notifiers
+
+        # @!attribute [r] request_tracker
+        #   @return [Stoplight::Domain::RecoveryProbeRequestRecorder]
+        protected attr_reader :request_tracker
+
+        # @param config [Stoplight::Domain::Config]
+        # @param data_store [Stoplight::DataStore::Base]
+        # @param notifiers [Array<Stoplight::Domain::StateTransitionNotifier>]
+        # @param request_tracker [Stoplight::Domain::Tracker::RecoveryProbe]
+        def initialize(config:, data_store:, notifiers:, request_tracker:)
+          @config = config
+          @data_store = data_store
+          @notifiers = notifiers
+          @request_tracker = request_tracker
+        end
+
+        # Executes the provided code block when the light is in the yellow state.
+        #
+        # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
+        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @yield The code block to execute.
+        # @return [Object] The result of the code block if successful.
+        # @raise [Exception] Re-raises the error if it is not tracked or no fallback is provided.
+        def execute(fallback, metadata:, &code)
+          enter_recovery(metadata)
+          # TODO: We need to employ a probabilistic approach here to avoid "thundering herd" problem
+          code.call.tap { record_recovery_probe_success }
+        rescue => error
+          if config.track_error?(error)
+            record_recovery_probe_failure(error)
+
+            if fallback
+              fallback.call(error)
+            else
+              raise
+            end
+          else
+            record_recovery_probe_success
+            raise
+          end
+        end
+
+        private def record_recovery_probe_success
+          request_tracker.record_success
+        end
+
+        private def record_recovery_probe_failure(error)
+          request_tracker.record_failure(error)
+        end
+
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [void]
+        private def enter_recovery(metadata)
+          return if metadata.recovery_started?
+
+          if data_store.transition_to_color(config, Color::YELLOW)
+            notifiers.each do |notifier|
+              notifier.notify(config, Color::RED, Color::YELLOW, nil)
+            end
+          end
+        end
+
+        # @return [Boolean]
+        def ==(other)
+          super &&
+            config == other.config &&
+            notifiers == other.notifiers &&
+            data_store == other.data_store &&
+            request_tracker == other.request_tracker
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/tracker/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Tracker
+      # @api private
+      # @abstract
+      class Base
+        # @!attribute [r] data_store
+        #   @return [Stoplight::DataStore::Base] The data store associated with the light.
+        protected attr_reader :data_store
+
+        # @!attribute [r] traffic_control
+        #   @return [Stoplight::Domain::TrafficControl::Base]
+        protected attr_reader :notifiers
+
+        # @!attribute [r] config
+        #   @return [Stoplight::Domain::Config] The configuration for the light.
+        protected attr_reader :config
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            config == other.config &&
+            data_store == other.data_store &&
+            notifiers == other.notifiers
+        end
+
+        def transition_and_notify(from_color, to_color, error = nil)
+          if data_store.transition_to_color(config, to_color)
+            notifiers.each do |notifier|
+              notifier.notify(config, from_color, to_color, error)
+            end
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end