stoplight 4.1.0 → 5.0.1

data/lib/stoplight/light.rb

@@ -1,110 +1,190 @@
 # frozen_string_literal: true
 
-require 'stoplight/light/deprecated'
-
 module Stoplight
   #
   # @api private use +Stoplight()+ method instead
   class Light
     extend Forwardable
-    extend Deprecated
-    include CircuitBreaker
-    include Lockable
-    include Runnable
-
-    # @!attribute [r] data_store
-    #   @return [Stoplight::DataStore::Base]
-    def_delegator :configuration, :data_store
+    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
 
-    # @!attribute [r] threshold
-    #   @return [Integer]
-    def_delegator :configuration, :threshold
+    # 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
+      config
+        .data_store
+        .get_metadata(config)
+        .locked_state
+    end
 
-    # @!attribute [r] cool_off_time
-    #   @return [Fixnum]
-    def_delegator :configuration, :cool_off_time
+    # 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
+      config
+        .data_store
+        .get_metadata(config)
+        .color
+    end
 
-    # @!attribute [r] window_size
-    #   @return [Float]
-    def_delegator :configuration, :window_size
+    # 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?
+
+      strategy = state_strategy_factory(color)
+      strategy.execute(fallback, &code)
+    end
 
-    # @!attribute [r] notifiers
-    #   # @return [Array<Notifier::Base>]
-    def_delegator :configuration, :notifiers
+    # 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
 
-    # @!attribute [r] error_notifier
-    #   # @return [Proc]
-    def_delegator :configuration, :error_notifier
+      config.data_store.set_state(config, state)
 
-    # @return [String]
-    attr_reader :name
-    # @return [Proc]
-    attr_reader :code
-    # @return [Proc]
-    attr_reader :error_handler
-    # @return [Proc, nil]
-    attr_reader :fallback
-    # @return [Stoplight::Configuration]
-    # @api private
-    attr_reader :configuration
-
-    class << self
-      alias __new_with_configuration__ new
-
-      # It overrides the +Light.new+ method to support an old and a new
-      # way of instantiation.
-      #
-      # @overload new(name, &code)
-      #   @param name [String]
-      #   @return [Stoplight::Light]
-      #
-      # @overload new(name, configuration)
-      #   @param name [String]
-      #   @param configuration [Stoplight::Configuration]
-      #   @return [Stoplight::Light]
-      #
-      def new(name, configuration = nil, &code)
-        if configuration
-          __new_with_configuration__(name, configuration, &code)
-        else
-          warn '[DEPRECATED] Instantiating `Stoplight::Light` is deprecated. ' \
-            'Please use `Stoplight()` method instead.'
-          Builder.with(name: name).build(&code)
-        end
-      end
+      self
     end
 
-    # @param name [String]
-    # @param configuration [Stoplight::Configuration]
-    # @yield []
-    def initialize(name, configuration, &code)
-      @configuration = configuration
-      @name = name
-      @code = code
-      @error_handler = Default::ERROR_HANDLER
-      @fallback = Default::FALLBACK
-    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)
 
-    # @yieldparam error [Exception]
-    # @yieldparam handle [Proc]
-    # @return [Stoplight::CircuitBreaker]
-    def with_error_handler(&error_handler)
-      @error_handler = error_handler
       self
     end
 
-    # @yieldparam error [Exception, nil]
-    # @return [Stoplight::CircuitBreaker]
-    def with_fallback(&fallback)
-      @fallback = fallback
-      self
+    # 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 reconfigure(configuration)
-      @configuration = configuration
-      self
+    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
   end
 end

data/lib/stoplight/metadata.rb

@@ -0,0 +1,71 @@
+# 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
+  ) do
+    def initialize(
+      successes: nil,
+      errors: nil,
+      recovery_probe_successes: nil,
+      recovery_probe_errors: nil,
+      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_errors:,
+        successes:,
+        errors:,
+        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: Integer(consecutive_errors),
+        consecutive_successes: Integer(consecutive_successes),
+        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),
+      )
+    end
+
+    # @param at [Time] (Time.now) the moment of time when the color is determined
+    # @return [String] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
+    def color(at: Time.now)
+      if locked_state == State::LOCKED_GREEN
+        Color::GREEN
+      elsif locked_state == State::LOCKED_RED
+        Color::RED
+      elsif (recovery_scheduled_after && recovery_scheduled_after < at) || recovery_started_at
+        Color::YELLOW
+      elsif breached_at
+        Color::RED
+      else
+        Color::GREEN
+      end
+    end
+  end
+end

data/lib/stoplight/notifier/base.rb

@@ -2,14 +2,21 @@
 
 module Stoplight
   module Notifier
-    # @abstract
+    # 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
-      # @param _light [Light]
-      # @param _from_color [String]
-      # @param _to_color [String]
-      # @param _error [Exception, nil]
-      # @return [String]
-      def notify(_light, _from_color, _to_color, _error)
+      # Sends a notification when a Stoplight changes state.
+      #
+      # @param config [Stoplight::Light::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.
+      # @return [String] The result of the notification process.
+      #
+      def notify(config, from_color, to_color, error)
         raise NotImplementedError
       end
     end

data/lib/stoplight/notifier/fail_safe.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Notifier
+    # A wrapper around a notifier that provides fail-safe mechanisms using a
+    # circuit breaker. It ensures that a notification can gracefully
+    # handle failures.
+    #
+    # @api private
+    class FailSafe < Base
+      # @!attribute [r] notifier
+      #   @return [Stoplight::Notifier::Base] The underlying notifier being wrapped.
+      protected attr_reader :notifier
+
+      class << self
+        # Wraps a notifier with fail-safe mechanisms.
+        #
+        # @param notifier [Stoplight::Notifier::Base] The notifier to wrap.
+        # @return [Stoplight::Notifier::FailSafe] The original notifier if it is already
+        #   a +FailSafe+ instance, otherwise a new +FailSafe+ instance.
+        def wrap(notifier)
+          case notifier
+          when FailSafe
+            notifier
+          else
+            new(notifier)
+          end
+        end
+      end
+
+      # Initializes a new instance of the +FailSafe+ class.
+      #
+      # @param notifier [Stoplight::Notifier::Base] The notifier to wrap.
+      def initialize(notifier)
+        @notifier = notifier
+      end
+
+      # Sends a notification using the wrapped notifier with fail-safe mechanisms.
+      #
+      # @param config [Stoplight::Light::Config] The light configuration.
+      # @param from_color [String] The initial color of the light.
+      # @param to_color [String] The target color of the light.
+      # @param error [Exception, nil] An optional error to include in the notification.
+      # @return [void]
+      def notify(config, from_color, to_color, error = nil)
+        fallback = proc do |exception|
+          config.error_notifier.call(exception) if exception
+          nil
+        end
+
+        circuit_breaker.run(fallback) do
+          notifier.notify(config, from_color, to_color, error)
+        end
+      end
+
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(FailSafe) && notifier == other.notifier
+      end
+
+      # @return [Stoplight] The circuit breaker used to handle failures.
+      private def circuit_breaker
+        @circuit_breaker ||= Stoplight("stoplight:notifier:fail_safe:#{notifier.class.name}", data_store: Default::DATA_STORE, notifiers: [])
+      end
+    end
+  end
+end

data/lib/stoplight/notifier/generic.rb

@@ -2,18 +2,63 @@
 
 module Stoplight
   module Notifier
+    # The Generic module provides a reusable implementation for notifiers in Stoplight.
+    # It includes a formatter for generating notification messages and defines the `notify` method.
+    #
+    # @example Custom Notifier Implementation and Usage
+    #     # Custom notifier that writes notifications to a file
+    #     class FileNotifier < Stoplight::Notifier::Base
+    #       include Stoplight::Notifier::Generic
+    #
+    #       def initialize(file_path)
+    #         @file = File.open(file_path, 'a')
+    #         super(@file)
+    #       end
+    #
+    #       private
+    #
+    #       # Writes the notification message to the file
+    #       def put(message)
+    #         @file.puts(message)
+    #       end
+    #     end
+    #
+    #     # Usage example
+    #     # Create a custom notifier that writes to 'stoplight.log'
+    #     notifier = FileNotifier.new('stoplight.log')
+    #
+    #     # Configure Stoplight to use the custom notifier
+    #     Stoplight.configure do |config|
+    #       config.notifiers += [notifier]
+    #     end
+    #
+    #     # Create a stoplight and trigger a state change
+    #     light = Stoplight('example-light')
+    #     light.run { raise 'Simulated failure' } rescue nil
+    #     light.run { raise 'Simulated failure' } rescue nil
+    #     light.run { raise 'Simulated failure' } rescue nil
+    #
     module Generic # rubocop:disable Style/Documentation
-      # @return [Proc]
+      # @!attribute [r] formatter
+      #   @return [Proc] The formatter used to generate notification messages.
+      #   @see Stoplight::Default::FORMATTER
       attr_reader :formatter
 
-      # @param object [Object]
-      # @param formatter [Proc, nil]
+      # @param object [Object] The object used by the notifier (e.g., a logger or external service).
+      # @param formatter [Proc, nil] A custom formatter for generating notification messages.
+      #   If no formatter is provided, the default formatter is used.
       def initialize(object, formatter = nil)
         @object = object
         @formatter = formatter || Default::FORMATTER
       end
 
-      # @see Base#notify
+      # Sends a notification when a Stoplight changes state.
+      #
+      # @param light [Light] 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.
+      # @return [String] The formatted notification message.
       def notify(light, from_color, to_color, error)
         message = formatter.call(light, from_color, to_color, error)
         put(message)
@@ -22,7 +67,11 @@ module Stoplight
 
       private
 
-      def put(_message)
+      # Processes the notification message.
+      #
+      # @param message [String] The notification message to be processed.
+      # @raise [NotImplementedError] If the method is not implemented in a subclass.
+      def put(message)
         raise NotImplementedError
       end
     end

data/lib/stoplight/rspec/generic_notifier.rb

@@ -1,40 +1,39 @@
 # frozen_string_literal: true
 
-RSpec.shared_examples 'a generic notifier' do
-  it 'includes Generic' do
+RSpec.shared_examples "a generic notifier" do
+  it "includes Generic" do
     expect(described_class).to include(Stoplight::Notifier::Generic)
   end
 
-  describe '#formatter' do
-    it 'is initially the default' do
+  describe "#formatter" do
+    it "is initially the default" do
       formatter = nil
       expect(described_class.new(nil, formatter).formatter)
         .to eql(Stoplight::Default::FORMATTER)
     end
 
-    it 'reads the formatter' do
+    it "reads the formatter" do
       formatter = proc {}
       expect(described_class.new(nil, formatter).formatter)
         .to eql(formatter)
     end
   end
 
-  describe '#notify' do
-    let(:light) { Stoplight::Light.new(name, &code) }
-    let(:name) { ('a'..'z').to_a.shuffle.join }
-    let(:code) { -> {} }
+  describe "#notify" do
+    let(:light) { Stoplight(name) }
+    let(:name) { ("a".."z").to_a.shuffle.join }
     let(:from_color) { Stoplight::Color::GREEN }
     let(:to_color) { Stoplight::Color::RED }
     let(:notifier) { described_class.new(double.as_null_object) }
 
-    it 'returns the message' do
+    it "returns the message" do
       error = nil
       expect(notifier.notify(light, from_color, to_color, error))
         .to eql(notifier.formatter.call(light, from_color, to_color, error))
     end
 
-    it 'returns the message with an error' do
-      error = ZeroDivisionError.new('divided by 0')
+    it "returns the message with an error" do
+      error = ZeroDivisionError.new("divided by 0")
       expect(notifier.notify(light, from_color, to_color, error))
         .to eql(notifier.formatter.call(light, from_color, to_color, error))
     end

data/lib/stoplight/rspec.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require 'stoplight/rspec/generic_notifier'
+require "stoplight/rspec/generic_notifier"

data/lib/stoplight/state.rb

@@ -2,8 +2,8 @@
 
 module Stoplight
   module State
-    UNLOCKED = 'unlocked'
-    LOCKED_GREEN = 'locked_green'
-    LOCKED_RED = 'locked_red'
+    UNLOCKED = "unlocked"
+    LOCKED_GREEN = "locked_green"
+    LOCKED_RED = "locked_red"
   end
 end

data/lib/stoplight/traffic_control/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module TrafficControl
+    # Strategies for determining when a Stoplight should change color to red.
+    #
+    # These strategies evaluate the current state and metrics of a Stoplight to decide
+    # if traffic should be stopped (i.e., if the light should turn RED).
+    #
+    # @example Creating a custom strategy
+    #   class ErrorRateStrategy < Stoplight::TrafficControl::Base
+    #     def stop_traffic?(config, metadata)
+    #       total = metadata.successes + metadata.failures
+    #       return false if total < 10 # Minimum sample size
+    #
+    #       error_rate = metadata.failures.fdiv(total)
+    #       error_rate >= 0.5 # Stop traffic when error rate reaches 50%
+    #     end
+    #   end
+    #
+    # @abstract
+    # @api private
+    class Base
+      # Determines whether traffic should be stopped based on the Stoplight's
+      # current state and metrics.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @param metadata [Stoplight::Metadata]
+      # @return [Boolean] true if traffic should be stopped (rec), false otherwise (green)
+      def stop_traffic?(config, metadata)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/stoplight/traffic_control/consecutive_failures.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module TrafficControl
+    # A strategy that stops the traffic based on consecutive failures number.
+    #
+    # This strategy implements two distinct behaviors based on whether a window size
+    # is configured:
+    #
+    # 1. When window_size is set: The Stoplight turns red when the total number of
+    #    failures within the window reaches the threshold.
+    #
+    # 2. When window_size is not set: The Stoplight turns red when consecutive failures
+    #    reach the threshold.
+    #
+    # @example With window-based configuration
+    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: 60)
+    #   strategy = Stoplight::TrafficControlStrategy::ConsecutiveFailures.new
+    #
+    # Will switch to red if 5 consecutive failures occur within the 60-second window
+    #
+    # @example With total number of consecutive failures configuration
+    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: nil)
+    #   strategy = Stoplight::TrafficControlStrategy::ConsecutiveFailures.new
+    #
+    # Will switch to red only if 5 consecutive failures occur regardless of the time window
+    # @api private
+    class ConsecutiveFailures < Base
+      # Determines if traffic should be stopped based on failure counts.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @param metadata [Stoplight::Metadata]
+      # @return [Boolean] true if failures have reached the threshold, false otherwise
+      def stop_traffic?(config, metadata)
+        if config.window_size
+          [metadata.consecutive_errors, metadata.errors].min >= config.threshold
+        else
+          metadata.consecutive_errors >= config.threshold
+        end
+      end
+    end
+  end
+end