stoplight 5.6.0 → 5.8.0

data/lib/stoplight/domain/compatibility_result.rb

@@ -9,28 +9,28 @@ module Stoplight
       class << self
         # Creates a new +CompatibilityResult+ instance representing a compatible strategy.
         #
-        # @return [CompatibilityResult] An instance with no errors.
+        # @return An instance with no errors.
         def compatible
           new(errors: [])
         end
 
         # Creates a new +CompatibilityResult+ instance representing an incompatible strategy.
         #
-        # @param errors [Array<String>] List of error messages indicating incompatibility.
-        # @return [CompatibilityResult] An instance with the provided errors.
+        # @param errors List of error messages indicating incompatibility.
+        # @return An instance with the provided errors.
         def incompatible(*errors)
           new(errors:)
         end
       end
 
       # Initializes a new `CompatibilityResult` instance.
-      # @param errors [Array<String>] List of error messages if the strategy is not compatible.
+      # @param errors List of error messages if the strategy is not compatible.
       def initialize(errors: [])
         @errors = errors.freeze
       end
 
       # Checks if the strategy is compatible.
-      # @return [Boolean] `true` if there are no errors, `false` otherwise.
+      # @return `true` if there are no errors, `false` otherwise.
       def compatible?
         @errors.empty?
       end
@@ -38,11 +38,11 @@ module Stoplight
       def incompatible? = !compatible?
 
       # Retrieves the list of error messages.
-      # @return [Array<String>] The list of error messages.
+      # @return  The list of error messages.
       attr_reader :errors
 
       # Retrieves a concatenated error message string.
-      # @return [String, nil] A string containing all error messages joined by "; ",
+      # @return A string containing all error messages joined by "; ",
       #   or `nil` if the strategy is compatible.
       def error_messages
         unless compatible?

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
-    #   @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,25 +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
+      :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
 
-      # 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
+      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
         #
@@ -15,9 +16,22 @@ module Stoplight
         #
         # @param data_store [DataStore::Base]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_data_store(data_store)
-          with(data_store:)
+          deprecate(<<~MSG)
+            Light#with_data_store is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_data_store(data_stare)
+
+            Configure correctly from the start:
+              Stoplight('api-call', data_store:)
+          MSG
+          with_without_warning(data_store:)
         end
 
         # Configures cool off time. Stoplight automatically tries to recover
@@ -29,9 +43,22 @@ module Stoplight
         #
         # @param cool_off_time [Numeric] number of seconds
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_cool_off_time(cool_off_time)
-          with(cool_off_time:)
+          deprecate(<<~MSG)
+            Light#with_cool_off_time is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_cool_off_time(cool_off_time)
+
+            Configure correctly from the start:
+              Stoplight('api-call', cool_off_time:)
+          MSG
+          with_without_warning(cool_off_time:)
         end
 
         # Configures custom threshold. After this number of failures Stoplight
@@ -43,9 +70,22 @@ module Stoplight
         #
         # @param threshold [Numeric]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_threshold(threshold)
-          with(threshold:)
+          deprecate(<<~MSG)
+            Light#with_threshold is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_threshold(threshold)
+
+            Configure correctly from the start:
+              Stoplight('api-call', threshold:)
+          MSG
+          with_without_warning(threshold:)
         end
 
         # Configures custom window size which Stoplight uses to count failures. For example,
@@ -60,9 +100,22 @@ module Stoplight
         #
         # @param window_size [Numeric] number of seconds
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_window_size(window_size)
-          with(window_size:)
+          deprecate(<<~MSG)
+            Light#with_window_size is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_window_size(window_size)
+
+            Configure correctly from the start:
+              Stoplight('api-call', window_size:)
+          MSG
+          with_without_warning(window_size:)
         end
 
         # Configures custom notifier
@@ -75,17 +128,43 @@ module Stoplight
         #
         # @param notifiers [Array<Notifier::Base>]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_notifiers(notifiers)
-          with(notifiers:)
+          deprecate(<<~MSG)
+            Light#with_notifiers is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_notifiers(notifiers)
+
+            Configure correctly from the start:
+              Stoplight('api-call', notifiers:)
+          MSG
+          with_without_warning(notifiers:)
         end
 
         # @param error_notifier [Proc]
         # @return [Stoplight::Light]
         # @api private
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_error_notifier(&error_notifier)
-          with(error_notifier: error_notifier)
+          deprecate(<<~MSG)
+            Light#with_error_notifier is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_error_notifier { |error| warn error }
+
+            Configure correctly from the start:
+              Stoplight('api-call', error_notifier: ->(error) { warn error })
+          MSG
+          with_without_warning(error_notifier: error_notifier)
         end
 
         # Configures a custom list of tracked errors that counts toward the threshold.
@@ -101,9 +180,22 @@ module Stoplight
         #
         # @param tracked_errors [Array<StandardError>]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_tracked_errors(*tracked_errors)
-          with(tracked_errors:)
+          deprecate(<<~MSG)
+            Light#with_tracked_errors is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_tracked_errors(TimeoutError, NetworkError)
+
+            Configure correctly from the start:
+              Stoplight('api-call', tracked_errors: [TimeoutError, NetworkError])
+          MSG
+          with_without_warning(tracked_errors:)
         end
 
         # Configures a custom list of skipped errors that do not count toward the threshold.
@@ -120,11 +212,25 @@ module Stoplight
         #
         # @param skipped_errors [Array<Exception>]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_skipped_errors(*skipped_errors)
-          with(skipped_errors:)
+          deprecate(<<~MSG)
+            Light#with_skipped_errors is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_skipped_errors(ActiveRecord::RecordNotFound)
+
+            Configure correctly from the start:
+              Stoplight('api-call', skipped_errors: [ActiveRecord::RecordNotFound])
+          MSG
+          with_without_warning(skipped_errors:)
         end
       end
+      # steep:ignore:end
     end
   end
 end

data/lib/stoplight/domain/light.rb

@@ -1,53 +1,28 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module Stoplight
   module Domain
     #
     # @api private use +Stoplight()+ method instead
     class Light
-      extend Forwardable
-      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
-
-      # @!attribute [r] yellow_run_strategy
-      #   @return [Stoplight::Domain::Strategies::YellowRunStrategy]
-      protected attr_reader :yellow_run_strategy
-
-      # @!attribute [r] red_run_strategy
-      #   @return [Stoplight::Domain::Strategies::RedRunStrategy]
-      protected attr_reader :red_run_strategy
-
-      # @!attribute [r] data_store
-      #   @return [Stoplight::Light::Base]
-      protected attr_reader :data_store
-
-      # @!attribute [r] factory
-      #   @return [Stoplight::Domain::LightFactory]
-      protected attr_reader :factory
-
-      # @param config [Stoplight::Domain::Config]
-      def initialize(config, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, data_store:, factory:)
-        @config = config
-        @data_store = data_store
+      include Common::Deprecations
+      include ConfigurationBuilderInterface # steep:ignore
+
+      attr_reader :name
+
+      attr_reader :green_run_strategy
+      attr_reader :yellow_run_strategy
+      attr_reader :red_run_strategy
+      attr_reader :factory
+      attr_reader :state_store
+
+      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
         @factory = factory
+        @state_store = state_store
       end
 
       # Returns the current state of the light:
@@ -55,10 +30,7 @@ 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
-      end
+      def state = state_snapshot.locked_state
 
       # Returns current color:
       #   * +Stoplight::Color::GREEN+ -- circuit breaker is closed
@@ -69,10 +41,7 @@ module Stoplight
       #   light = Stoplight('example')
       #   light.color #=> Color::GREEN
       #
-      # @return [String] returns current light color
-      def color
-        state_snapshot.color
-      end
+      def color = state_snapshot.color
 
       # Runs the given block of code with this circuit breaker
       #
@@ -84,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?
@@ -103,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
@@ -112,7 +79,7 @@ module Stoplight
         else raise Error::IncorrectColor
         end
 
-        data_store.set_state(config, state)
+        state_store.set_state(state)
 
         self
       end
@@ -124,21 +91,16 @@ 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
-        data_store.set_state(config, State::UNLOCKED)
+        state_store.set_state(State::UNLOCKED)
 
         self
       end
 
       # 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 && data_store == other.data_store &&
-          green_run_strategy == other.green_run_strategy && yellow_run_strategy == other.yellow_run_strategy &&
-          red_run_strategy == other.red_run_strategy && factory == other.factory
+        other.is_a?(self.class) && factory == other.factory
       end
 
       # Reconfigures the light with updated settings and returns a new instance.
@@ -171,10 +133,30 @@ module Stoplight
       #   # Run the lights with their respective configurations
       #   invoices_light.run(->(error) { [] }) { call_invoices_api }
       #   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.
+
+          Circuit breakers should be configured once at creation, not cloned with
+          modifications.
+
+          Instead of:
+            light = Stoplight('api-call', threshold: 5)
+            modified = light.with(threshold: 10)
+
+          Configure correctly from the start:
+            Stoplight('api-call', threshold: 10)
+        MSG
+        with_without_warning(**settings)
+      end
+
+      private def with_without_warning(**settings)
         factory.build_with(**settings)
       end
+      # steep:ignore:end
 
       private
 
@@ -189,9 +171,7 @@ module Stoplight
         end
       end
 
-      def state_snapshot
-        data_store.get_state_snapshot(config)
-      end
+      def state_snapshot = state_store.state_snapshot
     end
   end
 end

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