stoplight 5.4.0 → 5.5.0

data/lib/stoplight/light/configuration_builder_interface.rb

@@ -1,128 +0,0 @@
-# frozen_string_literal: true
-
-require "forwardable"
-
-module Stoplight
-  class Light
-    # Implements light configuration behavior
-    module ConfigurationBuilderInterface
-      # Configures data store to be used with this circuit breaker
-      #
-      # @example
-      #   Stoplight('example')
-      #     .with_data_store(Stoplight::DataStore::Memory.new)
-      #
-      # @param data_store [DataStore::Base]
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_data_store(data_store)
-        reconfigure(config.with(data_store: data_store))
-      end
-
-      # Configures cool off time. Stoplight automatically tries to recover
-      # from the red state after the cool off time.
-      #
-      # @example
-      #   Stoplight('example')
-      #     .cool_off_time(60)
-      #
-      # @param cool_off_time [Numeric] number of seconds
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_cool_off_time(cool_off_time)
-        reconfigure(config.with(cool_off_time: cool_off_time))
-      end
-
-      # Configures custom threshold. After this number of failures Stoplight
-      # switches to the red state:
-      #
-      # @example
-      #   Stoplight('example')
-      #     .with_threshold(5)
-      #
-      # @param threshold [Numeric]
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_threshold(threshold)
-        reconfigure(config.with(threshold: threshold))
-      end
-
-      # Configures custom window size which Stoplight uses to count failures. For example,
-      #
-      # @example
-      #   Stoplight('example')
-      #     .with_threshold(5)
-      #     .with_window_size(60)
-      #
-      # The above example will turn to red light only when 5 errors happen
-      # within 60 seconds period.
-      #
-      # @param window_size [Numeric] number of seconds
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_window_size(window_size)
-        reconfigure(config.with(window_size: window_size))
-      end
-
-      # Configures custom notifier
-      #
-      # @example
-      #   io = StringIO.new
-      #   notifier = Stoplight::Notifier::IO.new(io)
-      #   Stoplight('example')
-      #     .with_notifiers([notifier])
-      #
-      # @param notifiers [Array<Notifier::Base>]
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_notifiers(notifiers)
-        reconfigure(config.with(notifiers: notifiers))
-      end
-
-      # @param error_notifier [Proc]
-      # @return [Stoplight::Light]
-      # @api private
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_error_notifier(&error_notifier)
-        reconfigure(config.with(error_notifier: error_notifier))
-      end
-
-      # Configures a custom list of tracked errors that counts toward the threshold.
-      #
-      # @example
-      #   light = Stoplight('example')
-      #     .with_tracked_errors(TimeoutError, NetworkError)
-      #   light.run { call_external_service }
-      #
-      # In the example above, the +TimeoutError+ and +NetworkError+ exceptions
-      # will be counted towards the threshold for moving the circuit breaker into the red state.
-      # If not configured, the default tracked error is +StandardError+.
-      #
-      # @param tracked_errors [Array<StandardError>]
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_tracked_errors(*tracked_errors)
-        reconfigure(config.with(tracked_errors: tracked_errors.dup.freeze))
-      end
-
-      # Configures a custom list of skipped errors that do not count toward the threshold.
-      # Typically, such errors does not represent a real failure and handled somewhere else
-      # in the code.
-      #
-      # @example
-      #   light = Stoplight('example')
-      #    .with_skipped_errors(ActiveRecord::RecordNotFound)
-      #   light.run { User.find(123) }
-      #
-      # In the example above, the +ActiveRecord::RecordNotFound+ doesn't
-      # move the circuit breaker into the red state.
-      #
-      # @param skipped_errors [Array<Exception>]
-      # @return [Stoplight::Light]
-      # @deprecated consider using +Light#with+ for reconfiguration
-      def with_skipped_errors(*skipped_errors)
-        reconfigure(config.with(skipped_errors: skipped_errors))
-      end
-    end
-  end
-end

data/lib/stoplight/light/green_run_strategy.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  class Light
-    # 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
-      # 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::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)
-        failure = Stoplight::Failure.from_error(error)
-        metadata = data_store.record_failure(config, failure)
-
-        if config.traffic_control.stop_traffic?(config, metadata) && data_store.transition_to_color(config, Color::RED)
-          config.notifiers.each do |notifier|
-            notifier.notify(config, Color::GREEN, Color::RED, error)
-          end
-        end
-      end
-
-      private def record_success
-        data_store.record_success(config)
-      end
-    end
-  end
-end

data/lib/stoplight/light/red_run_strategy.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  class Light
-    # 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
-      # 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::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

data/lib/stoplight/light/run_strategy.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  class Light
-    # 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
-      # @!attribute [r] config
-      #   @return [Stoplight::Light::Config] The configuration for the light.
-      private attr_reader :config
-
-      # @!attribute [r] data_store
-      #   @return [Stoplight::DataStore::Base] The data store associated with the light.
-      private attr_reader :data_store
-
-      # @param config [Stoplight::Light::Config] The configuration for the light.
-      def initialize(config)
-        @config = config
-        @data_store = config.data_store
-      end
-
-      # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
-      # @param metadata [Stoplight::Metadata] Metadata capturing the current state of the light.
-      def execute(fallback, metadata:, &code)
-        raise NotImplementedError, "Subclasses must implement the execute method"
-      end
-    end
-  end
-end

data/lib/stoplight/light/yellow_run_strategy.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  class Light
-    # 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
-      # 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::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)
-        transition_to_yellow(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
-        metadata = data_store.record_recovery_probe_success(config)
-
-        recover(metadata)
-      end
-
-      private def record_recovery_probe_failure(error)
-        failure = Failure.from_error(error)
-        metadata = data_store.record_recovery_probe_failure(config, failure)
-
-        recover(metadata)
-      end
-
-      # @param metadata [Stoplight::Metadata]
-      # @return [void]
-      def transition_to_yellow(metadata:)
-        return unless metadata.color == Color::YELLOW
-
-        if metadata.recovery_scheduled_after && config.data_store.transition_to_color(config, Color::YELLOW)
-          config.notifiers.each do |notifier|
-            notifier.notify(config, Color::RED, Color::YELLOW, nil)
-          end
-        end
-      end
-
-      private def recover(metadata)
-        recovery_result = config.traffic_recovery.determine_color(config, metadata)
-
-        case recovery_result
-        when TrafficRecovery::GREEN
-          if data_store.transition_to_color(config, Color::GREEN)
-            config.notifiers.each do |notifier|
-              notifier.notify(config, Color::YELLOW, Color::GREEN, nil)
-            end
-          end
-        when TrafficRecovery::YELLOW
-          if data_store.transition_to_color(config, Color::YELLOW)
-            config.notifiers.each do |notifier|
-              notifier.notify(config, Color::RED, Color::YELLOW, nil)
-            end
-          end
-        when TrafficRecovery::RED
-          if data_store.transition_to_color(config, Color::RED)
-            config.notifiers.each do |notifier|
-              notifier.notify(config, Color::YELLOW, Color::RED, nil)
-            end
-          end
-        when TrafficRecovery::PASS
-          # No state change, do nothing
-        else
-          raise "recovery strategy returned an expected color: #{recovery_result}"
-        end
-      end
-    end
-  end
-end

data/lib/stoplight/light.rb

@@ -1,191 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  #
-  # @api private use +Stoplight()+ method instead
-  class Light
-    extend Forwardable
-    include ConfigurationBuilderInterface
-
-    # @!attribute [r] config
-    #   @return [Stoplight::Light::Config]
-    #   @api private
-    attr_reader :config
-
-    # @!attribute [r] name
-    #   The name of the light.
-    #   @return [String]
-    def_delegator :config, :name
-
-    # @param config [Stoplight::Light::Config]
-    def initialize(config, green_run_strategy: nil, yellow_run_strategy: nil, red_run_strategy: nil)
-      @config = config
-      @green_run_strategy = green_run_strategy
-      @yellow_run_strategy = yellow_run_strategy
-      @red_run_strategy = red_run_strategy
-    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 [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
-
-      config.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
-      config.data_store.set_state(config, Stoplight::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
-    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::Notifier::Base>] :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)
-      reconfigure(config.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::Runnable::RunStrategy]
-    def green_run_strategy
-      @green_run_strategy ||= GreenRunStrategy.new(config)
-    end
-
-    # @return [Stoplight::Runnable::RunStrategy]
-    def yellow_run_strategy
-      @yellow_run_strategy ||= YellowRunStrategy.new(config)
-    end
-
-    # @return [Stoplight::Runnable::RunStrategy]
-    def red_run_strategy
-      @red_run_strategy ||= RedRunStrategy.new(config)
-    end
-
-    # @param config [Stoplight::Light::Config]
-    # @return [Stoplight::Light]
-    def reconfigure(config)
-      self.class.new(config)
-    end
-
-    # @return [Stoplight::Metadata]
-    def metadata
-      config.data_store.get_metadata(config)
-    end
-  end
-end

data/lib/stoplight/metadata.rb

@@ -1,99 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  # @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
-    def initialize(
-      current_time: Time.now,
-      successes: 0,
-      errors: 0,
-      recovery_probe_successes: 0,
-      recovery_probe_errors: 0,
-      last_error_at: nil,
-      last_success_at: nil,
-      consecutive_errors: 0,
-      consecutive_successes: 0,
-      last_error: nil,
-      breached_at: nil,
-      locked_state: nil,
-      recovery_started_at: nil,
-      recovery_scheduled_after: nil,
-      recovered_at: nil
-    )
-      super(
-        recovery_probe_successes: recovery_probe_successes.to_i,
-        recovery_probe_errors: recovery_probe_errors.to_i,
-        successes: successes.to_i,
-        errors: errors.to_i,
-        last_error_at: (Time.at(Integer(last_error_at)) if last_error_at),
-        last_success_at: (Time.at(Integer(last_success_at)) if last_success_at),
-        consecutive_errors: consecutive_errors.to_i,
-        consecutive_successes: consecutive_successes.to_i,
-        last_error:,
-        breached_at: (Time.at(Integer(breached_at)) if breached_at),
-        locked_state: locked_state || State::UNLOCKED,
-        recovery_scheduled_after: (Time.at(Integer(recovery_scheduled_after)) if recovery_scheduled_after),
-        recovery_started_at: (Time.at(Integer(recovery_started_at)) if recovery_started_at),
-        recovered_at: (Time.at(Integer(recovered_at)) if recovered_at),
-        current_time:,
-      )
-    end
-
-    # Creates a new Metadata instance with updated attributes. This method overrides
-    # the default +with+ method provided by +Data.define+ to ensure constructor
-    # logic is applied.
-    #
-    # @param kwargs [Hash{Symbol => Object}]
-    # @return [Metadata]
-    def with(**kwargs)
-      self.class.new(**to_h.merge(current_time: Time.now, **kwargs))
-    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