stoplight 4.1.0 → 5.0.1

data/lib/stoplight/light/config.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Stoplight
+  class Light
+    # A +Stoplight::Light+ configuration object.
+    # @api private
+    class Config
+      # @!attribute [r] name
+      #   @return [String]
+      attr_reader :name
+
+      # @!attribute [r] cool_off_time
+      #   @return [Numeric]
+      attr_reader :cool_off_time
+
+      # @!attribute [r] data_store
+      #   @return [Stoplight::DataStore::Base]
+      attr_reader :data_store
+
+      # @!attribute [r] error_notifier
+      #   @return [StandardError => void]
+      attr_reader :error_notifier
+
+      # @!attribute [r] notifiers
+      #   @return [Array<Stoplight::Notifier::Base>]
+      attr_reader :notifiers
+
+      # @!attribute [r] threshold
+      #   @return [Numeric]
+      attr_reader :threshold
+
+      # @!attribute [r] window_size
+      #   @return [Numeric]
+      attr_reader :window_size
+
+      # @!attribute [r] tracked_errors
+      #   @return [Array<StandardError>]
+      attr_reader :tracked_errors
+
+      # @!attribute [r] skipped_errors
+      #  @return [Array<Exception>]
+      attr_reader :skipped_errors
+
+      # @!attribute [r] traffic_control
+      #  @return [Stoplight::TrafficControl::Base]
+      attr_reader :traffic_control
+
+      # @!attribute [r] traffic_recovery
+      #   @return [Stoplight::TrafficRecovery::Base]
+      attr_reader :traffic_recovery
+
+      # @param name [String]
+      # @param cool_off_time [Numeric]
+      # @param data_store [Stoplight::DataStore::Base]
+      # @param error_notifier [Proc]
+      # @param notifiers [Array<Stoplight::Notifier::Base>]
+      # @param threshold [Numeric]
+      # @param window_size [Numeric]
+      # @param tracked_errors [Array<StandardError>]
+      # @param skipped_errors [Array<Exception>]
+      # @param traffic_control [Stoplight::TrafficControl::Base]
+      # @param traffic_recovery [Stoplight::TrafficRecovery::Base]
+      def initialize(name:, cool_off_time:, data_store:, error_notifier:, notifiers:, threshold:, window_size:,
+        tracked_errors:, skipped_errors:, traffic_control:, traffic_recovery:)
+        @name = name
+        @cool_off_time = cool_off_time.to_i
+        @data_store = DataStore::FailSafe.wrap(data_store)
+        @error_notifier = error_notifier
+        @notifiers = notifiers.map { |notifier| Notifier::FailSafe.wrap(notifier) }
+        @threshold = threshold
+        @window_size = window_size
+        @tracked_errors = Array(tracked_errors)
+        @skipped_errors = Array(skipped_errors)
+        @traffic_control = traffic_control
+        @traffic_recovery = traffic_recovery
+      end
+
+      # @param other [any]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) && to_h == other.to_h
+      end
+
+      # @param error [Exception]
+      # @return [Boolean]
+      def track_error?(error)
+        skip = skipped_errors.any? { |klass| klass === error }
+        track = tracked_errors.any? { |klass| klass === error }
+
+        !skip && track
+      end
+
+      # Updates the configuration with new settings and returns a new instance.
+      #
+      # @return [Stoplight::Light::Config]
+      def with(**settings)
+        self.class.new(**to_h.merge(settings))
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          cool_off_time:,
+          data_store:,
+          error_notifier:,
+          name:,
+          notifiers:,
+          threshold:,
+          window_size:,
+          tracked_errors:,
+          skipped_errors:,
+          traffic_control:,
+          traffic_recovery:
+        }
+      end
+    end
+  end
+end

data/lib/stoplight/light/configuration_builder_interface.rb

@@ -0,0 +1,128 @@
+# 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

@@ -0,0 +1,53 @@
+# 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.
+      # @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, &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

@@ -0,0 +1,26 @@
+# 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.
+      # @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)
+        if fallback
+          fallback.call(nil)
+        else
+          raise Error::RedLight, config.name
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/light/run_strategy.rb

@@ -0,0 +1,30 @@
+# 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
+
+      def execute(fallback, &code)
+        raise NotImplementedError, "Subclasses must implement the execute method"
+      end
+    end
+  end
+end

data/lib/stoplight/light/yellow_run_strategy.rb

@@ -0,0 +1,78 @@
+# 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.
+      # @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, &code)
+        # 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
+
+      private def recover(metadata)
+        recovery_result = config.traffic_recovery.determine_color(config, metadata)
+
+        case recovery_result
+        when Color::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 Color::YELLOW
+          if data_store.transition_to_color(config, Color::YELLOW)
+            config.notifiers.each do |notifier|
+              notifier.notify(config, Color::GREEN, Color::YELLOW, nil)
+            end
+          end
+        when Color::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
+        else
+          raise "recovery strategy returned an expected color: #{recovery_result}"
+        end
+      end
+    end
+  end
+end