stoplight 5.7.0 → 5.8.0

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

@@ -10,69 +10,50 @@ module Stoplight
       # 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] stare_store
-        #   @return [Stoplight::Domain::Storage::State]
-        protected attr_reader :state_store
-
-        # @!attribute [r] metrics_store
-        #   @return [Stoplight::Domain::Storage::Metrics]
-        protected attr_reader :metrics_store
-
-        # @!attribute [r] recovery_lock_store
-        #   @return [Stoplight::Domain::Storage::RecoveryLock]
-        protected attr_reader :recovery_lock_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
-
-        # @!attribute [r] red_run_strategy
-        #   @return [Stoplight::Domain::Strategies::RedRunStrategy]
-        protected attr_reader :red_run_strategy
-
-        # @param config [Stoplight::Domain::Config]
-        # @param notifiers [Array<Stoplight::Domain::StateTransitionNotifier>]
-        # @param request_tracker [Stoplight::Domain::Tracker::RecoveryProbe]
-        # @param red_run_strategy [Stoplight::Domain::Strategies::RedRunStrategy]
-        # @param recovery_lock_store [Stoplight::Domain::Storage::RecoveryLock]
-        def initialize(config:, notifiers:, request_tracker:, red_run_strategy:, state_store:, metrics_store:, recovery_lock_store:)
-          @config = config
+      class YellowRunStrategy
+        def initialize(
+          name:,
+          error_tracking_policy:,
+          notifiers:,
+          request_tracker:,
+          red_run_strategy:,
+          state_store:,
+          metrics_store:,
+          recovery_lock_store:,
+          config: # FIXME: needed for backward compatibility, remove when notifier accepts light config
+        )
           @notifiers = notifiers
           @request_tracker = request_tracker
           @red_run_strategy = red_run_strategy
           @state_store = state_store
           @metrics_store = metrics_store
           @recovery_lock_store = recovery_lock_store
+          @name = name
+          @error_tracking_policy = error_tracking_policy
+          @config = config
         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 state_snapshot [Stoplight::Domain::StateSnapshot]
+        # @param fallback A fallback proc to execute in case of an error.
+        # @param state_snapshot
         # @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.
+        # @return The result of the code block if successful.
+        # @raise Re-raises the error if it is not tracked or no fallback is provided.
         def execute(fallback, state_snapshot:, &code)
           # Everything withing this block executed exclusively:
           #   - enter recovery
           #   - execute user's code
           #   - record outcome
           #   - transition to green or red if needed
-          with_recovery_lock(fallback:, state_snapshot:) do
+          with_recovery_lock(fallback:, state_snapshot:, code:) do
             enter_recovery(state_snapshot)
 
-            code.call.tap { record_recovery_probe_success }
+            result = code.call
+            record_recovery_probe_success
+            result
           rescue => error
-            if config.track_error?(error)
+            if @error_tracking_policy.track?(error)
               record_recovery_probe_failure(error)
 
               if fallback
@@ -87,10 +68,19 @@ module Stoplight
           end
         end
 
-        def with_recovery_lock(fallback:, state_snapshot:)
+        private
+
+        attr_reader :notifiers
+        attr_reader :request_tracker
+        attr_reader :red_run_strategy
+        attr_reader :state_store
+        attr_reader :metrics_store
+        attr_reader :recovery_lock_store
+
+        def with_recovery_lock(fallback:, state_snapshot:, code:)
           recovery_lock_token = recovery_lock_store.acquire_lock
           if recovery_lock_token.nil?
-            return red_run_strategy.execute(fallback, state_snapshot:)
+            return red_run_strategy.execute(fallback, state_snapshot:, &code)
           end
 
           begin
@@ -100,23 +90,23 @@ module Stoplight
           end
         end
 
-        private def record_recovery_probe_success
+        def record_recovery_probe_success
           request_tracker.record_success
         end
 
-        private def record_recovery_probe_failure(error)
+        def record_recovery_probe_failure(error)
           request_tracker.record_failure(error)
         end
 
-        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
-        # @return [void]
-        private def enter_recovery(state_snapshot)
+        def enter_recovery(state_snapshot)
           return if state_snapshot.recovery_started?
 
           state_store.transition_to_color(Color::YELLOW)
           metrics_store.clear
+          # FIXME: use light config instead of @_config
+          # light_info = LightInfo.new(name: @name)
           notifiers.each do |notifier|
-            notifier.notify(config, Color::RED, Color::YELLOW, nil)
+            notifier.notify(@config, Color::RED, Color::YELLOW, nil)
           end
         end
       end

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

@@ -3,32 +3,7 @@
 module Stoplight
   module Domain
     module Tracker
-      class RecoveryProbe < Base
-        # @!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
-
-        # @!attribute [r] metrics_store
-        #   @return [Stoplight::Domain::Storage::Metrics]
-        protected attr_reader :metrics_store
-
-        # @!attribute [r] state_store
-        #   @return [Stoplight::Domain::Storage::State]
-        protected attr_reader :state_store
-
-        # @param traffic_recovery [Stoplight::Domain::TrafficRecovery::Base]
-        # @param notifiers [<Stoplight::Domain::StateTransitionNotifier>]
-        # @param config [Stoplight::Domain::Config]
-        # @param metrics_store [Stoplight::Domain::Storage::Metrics]
-        # @param state_store [Stoplight::Domain::Storage::State]
+      class RecoveryProbe
         def initialize(traffic_recovery:, notifiers:, config:, metrics_store:, state_store:)
           @traffic_recovery = traffic_recovery
           @notifiers = notifiers
@@ -49,25 +24,33 @@ module Stoplight
 
           recover
         end
-        RECOVERY_TRANSITIONS = {
-          TrafficRecovery::GREEN => [Color::YELLOW, Color::GREEN],
-          TrafficRecovery::RED => [Color::YELLOW, Color::RED]
-        }.freeze
 
-        private def recover
+        private
+
+        attr_reader :traffic_recovery
+        attr_reader :notifiers
+        attr_reader :config
+        attr_reader :metrics_store
+        attr_reader :state_store
+
+        def recover
           recovery_metrics = metrics_store.metrics_snapshot
           recovery_result = traffic_recovery.determine_color(config, recovery_metrics)
 
           return if recovery_result == TrafficRecovery::YELLOW
 
-          from_color, to_color = RECOVERY_TRANSITIONS.fetch(recovery_result) do
+          from_color, to_color = case recovery_result
+          when TrafficRecovery::GREEN then [Color::YELLOW, Color::GREEN]
+          when TrafficRecovery::RED then [Color::YELLOW, Color::RED]
+          else
             raise "recovery strategy returned unexpected color: #{recovery_result}"
           end
 
           state_store.transition_to_color(to_color)
           metrics_store.clear
+          info = LightInfo.new(name: config.name)
           notifiers.each do |notifier|
-            notifier.notify(config, from_color, to_color, nil)
+            notifier.notify(info, from_color, to_color, nil)
           end
         end
       end

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

@@ -9,32 +9,7 @@ module Stoplight
       # Used by +GreenRunStrategy+ to track failures and potentially open the circuit.
       #
       # @api private
-      class Request < Base
-        # @!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
-
-        # @!attribute metrics_store
-        #   @return [Stoplight::Storage::Metrics]
-        protected attr_reader :metrics_store
-
-        # @!attribute [r] state_store
-        #   @return [Stoplight::Domain::Storage::State]
-        protected attr_reader :state_store
-
-        # @param traffic_control [Stoplight::Domain::TrafficControl::Base]
-        # @param notifiers [<Stoplight::Domain::StateTransitionNotifier>]
-        # @param config [Stoplight::Domain::Config]
-        # @param metrics_store [Stoplight::Storage::Metrics]
-        # @param state_store [Stoplight::Domain::Storage::State]
+      class Request
         def initialize(traffic_control:, notifiers:, config:, metrics_store:, state_store:)
           @traffic_control = traffic_control
           @notifiers = notifiers
@@ -43,8 +18,6 @@ module Stoplight
           @state_store = state_store
         end
 
-        # @param exception [Exception]
-        # @return [void]
         def record_failure(exception)
           metrics_store.record_failure(exception)
           metrics = metrics_store.metrics_snapshot
@@ -52,16 +25,24 @@ module Stoplight
           transition_to_red(exception, metrics:)
         end
 
-        # @return [void]
         def record_success = metrics_store.record_success
 
-        private def transition_to_red(exception, metrics:)
+        private
+
+        attr_reader :traffic_control
+        attr_reader :notifiers
+        attr_reader :config
+        attr_reader :metrics_store
+        attr_reader :state_store
+
+        def transition_to_red(exception, metrics:)
           if traffic_control.stop_traffic?(config, metrics)
             # Returns true only if not yet in red therefore preventing
             # duplicate notifications
             if state_store.transition_to_color(Color::RED)
+              info = LightInfo.new(name: config.name)
               notifiers.each do |notifier|
-                notifier.notify(config, Color::GREEN, Color::RED, exception)
+                notifier.notify(info, Color::GREEN, Color::RED, exception)
               end
             end
           end

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

@@ -26,27 +26,24 @@ module Stoplight
       #
       # Will switch to red only if 5 consecutive failures occur regardless of the time window
       # @api private
-      class ConsecutiveErrors < Base
-        # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Domain::CompatibilityResult]
+      class ConsecutiveErrors
         def check_compatibility(config)
           if config.threshold <= 0
-            incompatible("`threshold` should be bigger than 0")
+            CompatibilityResult.incompatible("`threshold` should be bigger than 0")
           elsif !config.threshold.is_a?(Integer)
-            incompatible("`threshold` should be an integer")
+            CompatibilityResult.incompatible("`threshold` should be an integer")
           else
-            compatible
+            CompatibilityResult.compatible
           end
         end
 
-        # Determines if traffic should be stopped based on failure counts.
-        #
-        # @param config [Stoplight::Domain::Config]
-        # @param metrics [Stoplight::Domain::Metrics]
-        # @return [Boolean] true if failures have reached the threshold, false otherwise
         def stop_traffic?(config, metrics)
           metrics.consecutive_errors >= config.threshold
         end
+
+        def ==(other)
+          other.is_a?(self.class)
+        end
       end
     end
   end

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

@@ -16,35 +16,39 @@ module Stoplight
       #   traffic_control = Stoplight::Domain::TrafficControl::ErrorRate.new(min_requests: 100)
       #
       # @api private
-      class ErrorRate < Base
-        # @!attribute min_requests
-        #   @return [Integer]
-        attr_reader :min_requests
-
-        # @param min_requests [Integer] Minimum number of requests before traffic control is applied.
+      class ErrorRate
+        # @param min_requests Minimum number of requests before traffic control is applied.
         #   until this number of requests is reached, the error rate will not be considered.
         def initialize(min_requests: 10)
           @min_requests = min_requests
         end
 
-        # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Domain::CompatibilityResult]
         def check_compatibility(config)
           if config.window_size.nil?
-            incompatible("`window_size` should be set")
+            CompatibilityResult.incompatible("`window_size` should be set")
           elsif config.threshold < 0 || config.threshold > 1
-            incompatible("`threshold` should be between 0 and 1")
+            CompatibilityResult.incompatible("`threshold` should be between 0 and 1")
           else
-            compatible
+            CompatibilityResult.compatible
           end
         end
 
-        # @param config [Stoplight::Domain::Config]
-        # @param metrics [Stoplight::Domain::Metrics]
-        # @return [Boolean]
         def stop_traffic?(config, metrics)
-          metrics.requests >= min_requests && metrics.error_rate >= config.threshold
+          error_rate = metrics.error_rate
+          requests = metrics.requests
+
+          raise ArgumentError, "accepts only windowed metrics" if error_rate.nil? || requests.nil?
+
+          requests >= min_requests && error_rate >= config.threshold
         end
+
+        def ==(other)
+          other.is_a?(self.class) && min_requests == other.min_requests
+        end
+
+        protected
+
+        attr_reader :min_requests
       end
     end
   end

data/lib/stoplight/domain/traffic_recovery/consecutive_successes.rb

@@ -33,24 +33,18 @@ module Stoplight
       # conservative approach prioritizes stability over recovery speed.
       #
       # @api private
-      class ConsecutiveSuccesses < Base
-        # @param config [Stoplight::Domain::Config]
-        # @return [Stoplight::Domain::CompatibilityResult]
+      class ConsecutiveSuccesses
         def check_compatibility(config)
           if config.recovery_threshold <= 0
-            incompatible("`recovery_threshold` should be bigger than 0")
+            CompatibilityResult.incompatible("`recovery_threshold` should be bigger than 0")
           elsif !config.recovery_threshold.is_a?(Integer)
-            incompatible("`recovery_threshold` should be an integer")
+            CompatibilityResult.incompatible("`recovery_threshold` should be an integer")
           else
-            compatible
+            CompatibilityResult.compatible
           end
         end
 
         # Determines if traffic should be resumed based on successes counts.
-        #
-        # @param config [Stoplight::Domain::Config]
-        # @param recovery_metrics [Stoplight::Domain::Metrics]
-        # @return [TrafficRecovery::Decision]
         def determine_color(config, recovery_metrics)
           if recovery_metrics.consecutive_errors > 0
             TrafficRecovery::RED
@@ -60,6 +54,8 @@ module Stoplight
             TrafficRecovery::YELLOW
           end
         end
+
+        def ==(other) = other.is_a?(self.class)
       end
     end
   end

data/lib/stoplight/domain/traffic_recovery.rb

@@ -3,10 +3,9 @@
 module Stoplight
   module Domain
     module TrafficRecovery
-      Decision = Data.define(:decision)
-      GREEN = Decision.new("green")
-      YELLOW = Decision.new("yellow")
-      RED = Decision.new("red")
+      GREEN = :green
+      YELLOW = :yellow
+      RED = :red
     end
   end
 end

data/lib/stoplight/error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Error
+    class Base < StandardError
+    end
+
+    class ConfigurationError < Base
+    end
+
+    class IncorrectColor < Base
+    end
+
+    class RedLight < Base
+      # @!attribute light_name
+      #   @return [String] The light's name
+      attr_reader :light_name
+
+      # @!attribute cool_off_time
+      #   @return [Numeric] Cool-off period in seconds
+      attr_reader :cool_off_time
+
+      # @!attribute retry_after
+      #   @return [Time | nil] Absolute Time after which a recovery attempt can occur
+      #     could be nil if the light is locked red
+      attr_reader :retry_after
+
+      # Initializes a new RedLight error.
+      #
+      # @param light_name [String] The light's name
+      #
+      # @option cool_off_time [Numeric] Cool-off period in seconds
+      #
+      # @option retry_after [Time | nil] Absolute Time after which a recovery attempt can occur
+      #
+      # @return [Stoplight::Error::RedLight]
+      def initialize(light_name, cool_off_time:, retry_after:)
+        @light_name = light_name
+        @cool_off_time = cool_off_time
+        @retry_after = retry_after
+
+        super(light_name)
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/{data_store/fail_safe.rb → fail_safe/data_store.rb}

@@ -4,33 +4,22 @@ require "securerandom"
 
 module Stoplight
   module Infrastructure
-    module DataStore
+    module FailSafe
       # A wrapper around a data store that provides fail-safe mechanisms using a
       # circuit breaker. It ensures that operations on the data store can gracefully
       # handle failures by falling back to default values when necessary.
       #
       # @api private
-      class FailSafe < Domain::DataStore
-        # @!attribute data_store
-        #  @return [Stoplight::DataStore::Base] The underlying primary data store being used
+      # steep:ignore:start
+      class DataStore
+        # The underlying primary data store being used
         attr_reader :data_store
-
-        # @!attribute error_notifier
-        #   @return [Proc]
         attr_reader :error_notifier
-
-        # @!attribute failover_data_store
-        #   @return [Stoplight::DataStore::Base] The fallback data store used when the primary fails.
+        # The fallback data store used when the primary fails.
         attr_reader :failover_data_store
-
-        # @!attribute circuit_breaker
-        #   @return [Stoplight::Light] The circuit breaker used to handle data store failures.
+        # The circuit breaker used to handle data store failures.
         private attr_reader :circuit_breaker
 
-        # @param data_store [Stoplight::Domain::DataStore]
-        # @param error_notifier [Proc]
-        # @param failover_data_store [Stoplight::Domain::DataStore]
-        # @param circuit_breaker [Stoplight::Domain::Light]
         def initialize(data_store:, error_notifier:, failover_data_store:, circuit_breaker:)
           @data_store = data_store
           @error_notifier = error_notifier
@@ -44,15 +33,15 @@ module Stoplight
           end
         end
 
-        def get_metrics(config, *args, **kwargs)
-          with_fallback(:get_metrics, config, *args, **kwargs) do
-            data_store.get_metrics(config, *args, **kwargs)
+        def get_metrics(config)
+          with_fallback(:get_metrics, config) do
+            data_store.get_metrics(config)
           end
         end
 
-        def get_recovery_metrics(config, *args, **kwargs)
-          with_fallback(:get_recovery_metrics, config, *args, **kwargs) do
-            data_store.get_recovery_metrics(config, *args, **kwargs)
+        def get_recovery_metrics(config)
+          with_fallback(:get_recovery_metrics, config) do
+            data_store.get_recovery_metrics(config)
           end
         end
 
@@ -74,45 +63,45 @@ module Stoplight
           end
         end
 
-        def record_failure(config, *args, **kwargs)
-          with_fallback(:record_failure, config, *args, **kwargs) do
-            data_store.record_failure(config, *args, **kwargs)
+        def record_failure(config, exception)
+          with_fallback(:record_failure, config, exception) do
+            data_store.record_failure(config, exception)
           end
         end
 
-        def record_success(config, *args, **kwargs)
-          with_fallback(:record_success, config, *args, **kwargs) do
-            data_store.record_success(config, *args, **kwargs)
+        def record_success(config)
+          with_fallback(:record_success, config) do
+            data_store.record_success(config)
           end
         end
 
-        def record_recovery_probe_success(config, *args, **kwargs)
-          with_fallback(:record_recovery_probe_success, config, *args, **kwargs) do
-            data_store.record_recovery_probe_success(config, *args, **kwargs)
+        def record_recovery_probe_success(config)
+          with_fallback(:record_recovery_probe_success, config) do
+            data_store.record_recovery_probe_success(config)
           end
         end
 
-        def record_recovery_probe_failure(config, *args, **kwargs)
-          with_fallback(:record_recovery_probe_failure, config, *args, **kwargs) do
-            data_store.record_recovery_probe_failure(config, *args, **kwargs)
+        def record_recovery_probe_failure(config, exception)
+          with_fallback(:record_recovery_probe_failure, config, exception) do
+            data_store.record_recovery_probe_failure(config, exception)
           end
         end
 
-        def set_state(config, *args, **kwargs)
-          with_fallback(:set_state, config, *args, **kwargs) do
-            data_store.set_state(config, *args, **kwargs)
+        def set_state(config, state)
+          with_fallback(:set_state, config, state) do
+            data_store.set_state(config, state)
           end
         end
 
-        def transition_to_color(config, *args, **kwargs)
-          with_fallback(:transition_to_color, config, *args, **kwargs) do
-            data_store.transition_to_color(config, *args, **kwargs)
+        def transition_to_color(config, color)
+          with_fallback(:transition_to_color, config, color) do
+            data_store.transition_to_color(config, color)
           end
         end
 
-        def delete_light(config, *args, **kwargs)
-          with_fallback(:delete_light, config, *args, **kwargs) do
-            data_store.delete_light(config, *args, **kwargs)
+        def delete_light(config)
+          with_fallback(:delete_light, config) do
+            data_store.delete_light(config)
           end
         end
 
@@ -127,10 +116,9 @@ module Stoplight
         # Redis tokens release via primary (with error notification on failure).
         # Memory tokens release via failover directly.
         #
-        # @param recovery_lock_token [Stoplight::Domain::RecoveryLockToken]
         def release_recovery_lock(recovery_lock_token)
           case recovery_lock_token
-          in Redis::RecoveryLockToken
+          in Redis::DataStore::RecoveryLockToken
             fallback = proc do |error|
               error_notifier.call(error) if error
             end
@@ -138,7 +126,7 @@ module Stoplight
             circuit_breaker.run(fallback) do
               data_store.release_recovery_lock(recovery_lock_token)
             end
-          in Memory::RecoveryLockToken
+          in Memory::DataStore::RecoveryLockToken
             failover_data_store.release_recovery_lock(recovery_lock_token)
           end
         end
@@ -148,17 +136,17 @@ module Stoplight
             other.failover_data_store == failover_data_store
         end
 
-        # @param method_name [Symbol] protected method name
         private def with_fallback(method_name, *args, **kwargs, &code)
-          fallback = proc do |error|
+          fallback = ->(error) {
             config = args.first
             error_notifier.call(error) if config && error
-            @failover_data_store.public_send(method_name, *args, **kwargs)
-          end
+            failover_data_store.public_send(method_name, *args, **kwargs)
+          }
 
           circuit_breaker.run(fallback, &code)
         end
       end
+      # steep:ignore:end
     end
   end
 end