stoplight 5.7.0 → 5.8.0

data/lib/stoplight/domain/config.rb

@@ -4,24 +4,6 @@ module Stoplight
   module Domain
     # A +Stoplight::Light+ configuration object.
     #
-    # # @!attribute [r] name
-    #   @return [String]
-    #
-    # @!attribute [r] cool_off_time - cool-off time in seconds
-    #   @return [Numeric]
-    #
-    # @!attribute [r] threshold
-    #   @return [Numeric]
-    #
-    # @!attribute [r] window_size
-    #   @return [Numeric]
-    #
-    # @!attribute [r] tracked_errors
-    #   @return [Array<StandardError>]
-    #
-    # @!attribute [r] skipped_errors
-    #  @return [Array<Exception>]
-    #
     # @api private
     Config = Data.define(
       :name,
@@ -30,29 +12,46 @@ module Stoplight
       :recovery_threshold,
       :window_size,
       :tracked_errors,
-      :skipped_errors
-    ) do
-      class << self
-        # Creates a new NULL configuration object.
-        # @return [Stoplight::Domain::Config]
-        def empty
-          new(**members.map { |key| [key, nil] }.to_h)
-        end
-      end
-
-      # Checks if the given error should be tracked
-      #
-      # @param error [#==] The error to check, e.g. an Exception, Class or Proc
-      # @return [Boolean]
-      def track_error?(error)
-        skip = skipped_errors.any? { |klass| klass === error }
-        track = tracked_errors.any? { |klass| klass === error }
-
-        !skip && track
+      :skipped_errors,
+      :traffic_control,
+      :traffic_recovery,
+      :error_notifier,
+      :notifiers,
+      :data_store
+    )
+    class Config
+      def cool_off_time_in_milliseconds
+        (cool_off_time * 1_000).to_i
       end
 
-      def cool_off_time_in_milliseconds
-        cool_off_time * 1_000
+      def with(
+        name: T.undefined,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        skipped_errors: T.undefined,
+        tracked_errors: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined,
+        error_notifier: T.undefined,
+        notifiers: T.undefined,
+        data_store: T.undefined
+      )
+        super(
+          name: name.is_a?(Undefined) ? self.name : name,
+          cool_off_time: cool_off_time.is_a?(Undefined) ? self.cool_off_time : cool_off_time,
+          threshold: threshold.is_a?(Undefined) ? self.threshold : threshold,
+          recovery_threshold: recovery_threshold.is_a?(Undefined) ? self.recovery_threshold : recovery_threshold,
+          window_size: window_size.is_a?(Undefined) ? self.window_size : window_size,
+          skipped_errors: skipped_errors.is_a?(Undefined) ? self.skipped_errors : skipped_errors,
+          tracked_errors: tracked_errors.is_a?(Undefined) ? self.tracked_errors : tracked_errors,
+          traffic_control: traffic_control.is_a?(Undefined) ? self.traffic_control : traffic_control,
+          traffic_recovery: traffic_recovery.is_a?(Undefined) ? self.traffic_recovery : traffic_recovery,
+          error_notifier: error_notifier.is_a?(Undefined) ? self.error_notifier : error_notifier,
+          notifiers: notifiers.is_a?(Undefined) ? self.notifiers : notifiers,
+          data_store: data_store.is_a?(Undefined) ? self.data_store : data_store,
+        )
       end
     end
   end

data/lib/stoplight/domain/error_tracking_policy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Determines which errors should be traced
+    class ErrorTrackingPolicy
+      def initialize(tracked:, skipped:)
+        @tracked = tracked
+        @skipped = skipped
+      end
+
+      def track?(error)
+        !skipped?(error) && tracked?(error)
+      end
+
+      private
+
+      def skipped?(error)
+        @skipped.any? { |matcher| matcher === error }
+      end
+
+      def tracked?(error)
+        @tracked.any? { |matcher| matcher === error }
+      end
+    end
+  end
+end

data/lib/stoplight/domain/failure.rb

@@ -16,7 +16,7 @@ module Stoplight
 
       # @param error [Exception]
       # @return (see #initialize)
-      def self.from_error(error, time: Time.now)
+      def self.from_error(error, time:)
         new(error.class.name, error.message, time)
       end
 

data/lib/stoplight/domain/light/configuration_builder_interface.rb

@@ -6,6 +6,7 @@ module Stoplight
   module Domain
     class Light
       # Implements light configuration behavior
+      # steep:ignore:start
       module ConfigurationBuilderInterface
         # Configures data store to be used with this circuit breaker
         #
@@ -229,6 +230,7 @@ module Stoplight
           with_without_warning(skipped_errors:)
         end
       end
+      # steep:ignore:end
     end
   end
 end

data/lib/stoplight/domain/light.rb

@@ -1,49 +1,23 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module Stoplight
   module Domain
     #
     # @api private use +Stoplight()+ method instead
     class Light
-      extend Forwardable
       include Common::Deprecations
-      include ConfigurationBuilderInterface
-
-      # @!attribute [r] config
-      #   @return [Stoplight::Domain::Config]
-      #   @api private
-      attr_reader :config
-
-      # @!attribute [r] name
-      #   The name of the light.
-      #   @return [String]
-      def_delegator :config, :name
-
-      # @!attribute [r] green_run_strategy
-      #   @return [Stoplight::Domain::Strategies::GreenRunStrategy]
-      protected attr_reader :green_run_strategy
+      include ConfigurationBuilderInterface # steep:ignore
 
-      # @!attribute [r] yellow_run_strategy
-      #   @return [Stoplight::Domain::Strategies::YellowRunStrategy]
-      protected attr_reader :yellow_run_strategy
+      attr_reader :name
 
-      # @!attribute [r] red_run_strategy
-      #   @return [Stoplight::Domain::Strategies::RedRunStrategy]
-      protected attr_reader :red_run_strategy
+      attr_reader :green_run_strategy
+      attr_reader :yellow_run_strategy
+      attr_reader :red_run_strategy
+      attr_reader :factory
+      attr_reader :state_store
 
-      # @!attribute [r] factory
-      #   @return [Stoplight::Domain::LightFactory]
-      protected attr_reader :factory
-
-      # @!attribute state_store
-      #   @param [Stoplight::Domain::Storage::State]
-      protected attr_reader :state_store
-
-      # @param config [Stoplight::Domain::Config]
-      def initialize(config, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, factory:, state_store:)
-        @config = config
+      def initialize(name, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, factory:, state_store:)
+        @name = name
         @green_run_strategy = green_run_strategy
         @yellow_run_strategy = yellow_run_strategy
         @red_run_strategy = red_run_strategy
@@ -56,7 +30,6 @@ module Stoplight
       #  * +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 = state_snapshot.locked_state
 
       # Returns current color:
@@ -68,7 +41,6 @@ module Stoplight
       #   light = Stoplight('example')
       #   light.color #=> Color::GREEN
       #
-      # @return [String] returns current light color
       def color = state_snapshot.color
 
       # Runs the given block of code with this circuit breaker
@@ -81,9 +53,7 @@ module Stoplight
       #   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]
+      # @param fallback fallback code to run if the circuit breaker is open
       # @raise [Stoplight::Error::RedLight]
       def run(fallback = nil, &code)
         raise ArgumentError, "nothing to run. Please, pass a block into `Light#run`" unless block_given?
@@ -100,8 +70,8 @@ module Stoplight
       #   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)
+      # @param color should be either +Color::RED+ or +Color::GREEN+
+      # @return locked light
       def lock(color)
         state = case color
         when Color::RED then State::LOCKED_RED
@@ -121,7 +91,7 @@ module Stoplight
       #   light.lock(Stoplight::Color::RED)
       #   light.unlock
       #
-      # @return [Stoplight::Light] returns unlocked light (circuit breaker)
+      # @return returns unlocked light (circuit breaker)
       def unlock
         state_store.set_state(State::UNLOCKED)
 
@@ -129,9 +99,6 @@ module Stoplight
       end
 
       # Two lights considered equal if they have the same configuration.
-      #
-      # @param other [any]
-      # @return [Boolean]
       def ==(other)
         other.is_a?(self.class) && factory == other.factory
       end
@@ -168,6 +135,7 @@ module Stoplight
       #   payment_light.run(->(error) { nil }) { call_payment_api }
       # @deprecated
       # @see +Stoplight()+
+      # steep:ignore:start
       def with(**settings)
         deprecate(<<~MSG)
           Light#with is deprecated and will be removed in v6.0.0.
@@ -188,6 +156,7 @@ module Stoplight
       private def with_without_warning(**settings)
         factory.build_with(**settings)
       end
+      # steep:ignore:end
 
       private
 

data/lib/stoplight/domain/light_info.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    LightInfo = Data.define(:name)
+  end
+end

data/lib/stoplight/domain/metrics_snapshot.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Request metrics over a given window.
+    #
+    # @api private
+    MetricsSnapshot = Data.define(
+      :successes,
+      :errors,
+      :consecutive_errors,
+      :consecutive_successes,
+      :last_error,
+      :last_success_at
+    )
+
+    class MetricsSnapshot
+      # @!attribute successes
+      #   A number of successes withing requested window. Zero for non-windowed metrics
+      #
+      # @!attribute errors
+      #   A number of errors withing requested window. Zero for non-windowed metrics
+
+      # Calculates the error rate based on the number of successes and errors.
+      #
+      # @return [Float]
+      def error_rate
+        return unless requests # we effectively check if this is windowed metrics
+
+        if (successes! + errors!).zero?
+          0.0
+        else
+          errors!.fdiv(successes! + errors!)
+        end
+      end
+
+      # @return [Integer]
+      def requests
+        if successes && errors # we effectively check if this is windowed metrics
+          successes! + errors!
+        end
+      end
+
+      # @return [Time, nil]
+      def last_error_at
+        last_error&.time
+      end
+
+      def successes!
+        successes or raise TypeError, "success must not be nil"
+      end
+
+      def errors!
+        errors or raise TypeError, "errors must not be nil"
+      end
+    end
+  end
+end

data/lib/stoplight/domain/state_snapshot.rb

@@ -2,39 +2,34 @@
 
 module Stoplight
   module Domain
-    # @!attribute breached_at
-    #   The time when the light became red (breached threshold)
-    #   @return [Time, nil]
-    #
-    # @!attribute locked_state
-    #   @return [State::UNLOCKED | State::LOCKED_GREEN | State::LOCKED_RED]
-    #
-    # @!attribute recovery_scheduled_after
-    #   When Light transitions to RED, it schedules recovery after the Cool Off Time.
-    #   @return [Time, nil]
-    #
-    # @!attribute recovery_started_at
-    #   When in YELLOW state, this time indicates the time of transitioning to YELLOW
-    #   @return [Time, nil]
-    #
-    # @!attribute time
-    #   The time when the snapshot was taken
-    #   @return [Time]
-    #
     StateSnapshot = Data.define(
       :breached_at,
       :locked_state,
       :recovery_scheduled_after,
       :recovery_started_at,
       :time
-    ) do
+    )
+
+    class StateSnapshot
+      # @!attribute breached_at
+      #   The time when the light became red (breached threshold)
+      #
+      # @!attribute recovery_scheduled_after
+      #   When Light transitions to RED, it schedules recovery after the Cool Off Time.
+      #
+      # @!attribute recovery_started_at
+      #   When in YELLOW state, this time indicates the time of transitioning to YELLOW
+      #
+      # @!attribute time
+      #   The time when the snapshot was taken
+
       # @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 < time) || recovery_started_at
+        elsif (recovery_scheduled_after && recovery_scheduled_after! < time) || recovery_started_at
           Color::YELLOW
         elsif breached_at
           Color::RED
@@ -48,9 +43,20 @@ module Stoplight
       #
       # This method indicates whether the recovery has already started explicitly
       #
-      # @return [Boolean]
       def recovery_started?
-        recovery_started_at && recovery_started_at <= time
+        if recovery_started_at.nil?
+          false
+        else
+          recovery_started_at! <= time
+        end
+      end
+
+      def recovery_started_at!
+        recovery_started_at or raise TypeError, "recovery_started_at must not be nil"
+      end
+
+      def recovery_scheduled_after!
+        recovery_scheduled_after or raise TypeError, "recovery_scheduled_after must not be nil"
       end
     end
   end

data/lib/stoplight/domain/storage/recovery_lock_token.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Storage
+      class RecoveryLockToken
+        attr_reader :token
+
+        def initialize
+          @token = SecureRandom.uuid
+        end
+      end
+    end
+  end
+end

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

@@ -9,34 +9,26 @@ module Stoplight
       # 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
+      class GreenRunStrategy
+        def initialize(error_tracking_policy:, request_tracker:)
+          @error_tracking_policy = error_tracking_policy
           @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 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)
           # TODO: Consider implementing sampling rate to limit the memory footprint
-          code.call.tap { record_success }
+          result = code.call
+          record_success
+          result
         rescue => error
-          if config.track_error?(error)
+          if @error_tracking_policy.track?(error)
             record_error(error)
 
             if fallback
@@ -51,18 +43,18 @@ module Stoplight
           end
         end
 
-        private def record_error(error)
+        private
+
+        attr_reader :config
+        attr_reader :request_tracker
+
+        def record_error(error)
           request_tracker.record_failure(error)
         end
 
-        private def record_success
+        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

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

@@ -9,28 +9,25 @@ module Stoplight
       # 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
+      class RedRunStrategy
+        def initialize(name:, cool_off_time:)
+          @name = name
+          @cool_off_time = cool_off_time
         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 state_snapshot [Stoplight::Domain::StateSnapshot]
-        # @return [Object, nil] The result of the fallback proc if provided.
+        # @param fallback A fallback proc to execute instead of the code block.
+        # @param state_snapshot
+        # @return The result of the fallback proc if provided.
         # @raise [Stoplight::Error::RedLight] Raises an error if no fallback is provided.
         def execute(fallback, state_snapshot:)
           if fallback
             fallback.call(nil)
           else
             raise Error::RedLight.new(
-              config.name,
-              cool_off_time: config.cool_off_time,
+              @name,
+              cool_off_time: @cool_off_time,
               retry_after: state_snapshot.recovery_scheduled_after
             )
           end