stoplight 5.4.0 → 5.5.0

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

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Tracker
+      class RecoveryProbe < Base
+        # @!attribute [r] data_store
+        #   @return [Stoplight::DataStore::Base] The data store associated with the light.
+        protected attr_reader :data_store
+
+        # @!attribute [r] traffic_recovery
+        #   @return [Stoplight::Domain::TrafficRecovery::Base]
+        protected attr_reader :traffic_recovery
+
+        # @!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
+
+        # @param data_store [Stoplight::Domain::DataStore]
+        # @param traffic_recovery [Stoplight::Domain::TrafficRecovery::Base]
+        # @param notifiers [<Stoplight::Domain::StateTransitionNotifier>]
+        # @param config [Stoplight::Domain::Config]
+        def initialize(data_store:, traffic_recovery:, notifiers:, config:)
+          @data_store = data_store
+          @traffic_recovery = traffic_recovery
+          @notifiers = notifiers
+          @config = config
+        end
+
+        # @param exception [Exception]
+        def record_failure(exception)
+          metadata = data_store.record_recovery_probe_failure(config, exception)
+
+          recover(metadata)
+        end
+
+        def record_success
+          metadata = data_store.record_recovery_probe_success(config)
+
+          recover(metadata)
+        end
+        RECOVERY_TRANSITIONS = {
+          TrafficRecovery::GREEN => [Color::YELLOW, Color::GREEN],
+          TrafficRecovery::YELLOW => [Color::RED, Color::YELLOW],
+          TrafficRecovery::RED => [Color::YELLOW, Color::RED]
+        }.freeze
+
+        private def recover(metadata)
+          recovery_result = traffic_recovery.determine_color(config, metadata)
+
+          return if recovery_result == TrafficRecovery::PASS
+
+          from_color, to_color = RECOVERY_TRANSITIONS.fetch(recovery_result) do
+            raise "recovery strategy returned unexpected color: #{recovery_result}"
+          end
+
+          transition_and_notify(from_color, to_color, nil)
+        end
+
+        # @param other [any]
+        # @return [bool]
+        def ==(other)
+          super && traffic_recovery == other.traffic_recovery
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Tracker
+      # Tracks request outcomes (success/failure) and manages state transitions
+      # for normal traffic.
+      #
+      # Used by +GreenRunStrategy+ to track failures and potentially open the circuit.
+      #
+      # @api private
+      class Request < 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 :traffic_control
+
+        # @!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
+
+        # @param data_store [Stoplight::Domain::DataStore]
+        # @param traffic_control [Stoplight::Domain::TrafficControl::Base]
+        # @param notifiers [<Stoplight::Domain::StateTransitionNotifier>]
+        # @param config [Stoplight::Domain::Config]
+        def initialize(data_store:, traffic_control:, notifiers:, config:)
+          @data_store = data_store
+          @traffic_control = traffic_control
+          @notifiers = notifiers
+          @config = config
+        end
+
+        # @param exception [Exception]
+        # @return [void]
+        def record_failure(exception)
+          metadata = data_store.record_failure(config, exception)
+
+          transition_to_red(exception, metadata:)
+        end
+
+        # @return [void]
+        def record_success
+          data_store.record_success(config)
+        end
+
+        private def transition_to_red(exception, metadata:)
+          if traffic_control.stop_traffic?(config, metadata)
+            transition_and_notify(Color::GREEN, Color::RED, exception)
+          end
+        end
+
+        # @param other [any]
+        # @return [bool]
+        def ==(other)
+          super && traffic_control == other.traffic_control
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    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::Domain::TrafficControl::Base
+      #     def check_compatibility(config)
+      #       if config.window_size.nil?
+      #         incompatible("`window_size` should be set")
+      #       else
+      #         compatible
+      #       end
+      #     end
+      #
+      #     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
+        # Checks if the strategy is compatible with the given Stoplight configuration.
+        #
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Domain::CompatibilityResult]
+        # :nocov:
+        def check_compatibility(config)
+          raise NotImplementedError
+        end
+        # :nocov:
+
+        # Determines whether traffic should be stopped based on the Stoplight's
+        # current state and metrics.
+        #
+        # @param config [Stoplight::Domain::Config]
+        # @param metadata [Stoplight::Domain::Metadata]
+        # @return [Boolean] true if traffic should be stopped (rec), false otherwise (green)
+        # :nocov:
+        def stop_traffic?(config, metadata)
+          raise NotImplementedError
+        end
+        # :nocov:
+
+        # @param other [any]
+        # @return [Boolean]
+        def ==(other)
+          other.is_a?(self.class)
+        end
+
+        # Returns a compatibility result indicating the strategy is compatible.
+        #
+        # @return [Stoplight::Domain::CompatibilityResult] A compatible result.
+        private def compatible = CompatibilityResult.compatible
+
+        # Returns a compatibility result indicating the strategy is incompatible.
+        #
+        # @param errors [Array<String>] The list of error messages describing incompatibility.
+        # @return [Stoplight::Domain::CompatibilityResult] An incompatible result.
+        private def incompatible(*errors) = CompatibilityResult.incompatible(*errors)
+      end
+    end
+  end
+end