stoplight 5.8.3 → 6.0.0.rc2

data/lib/stoplight/data_store.rb

@@ -5,21 +5,31 @@ module Stoplight
     end
 
     class Redis < Base
+      KEY_SPACE = Infrastructure::Redis::Key.new("stoplight", "v6")
+      private_constant :KEY_SPACE
+
       # @!attribute redis
       #   @return [::Redis, ConnectionPool<::Redis>]
       attr_reader :redis
 
-      # @!attribute warn_on_clock_skew
-      #   @return [Boolean]
-      attr_reader :warn_on_clock_skew
-
       # @param redis [::Redis, ConnectionPool<::Redis>]
-      # @param warn_on_clock_skew [Boolean] (true) Whether to warn about clock skew between Redis and
-      #   the application server
-      def initialize(redis, warn_on_clock_skew: true)
-        @warn_on_clock_skew = warn_on_clock_skew
+      def initialize(redis)
         @redis = redis
       end
+
+      # Immutable key namespace for a light within a system.
+      #
+      # Produces keys following entity-first structure:
+      #   stoplight:{version}:{system_id}:{{light_id}}:locks:recovery
+      #   stoplight:{version}:{system_id}:{{light_id}}:metrics:successes
+      #   stoplight:{version}:{system_id}:{{light_id}}:state
+      #
+      # Identifiers are derived from SHA-256 and truncated to 12 characters. Collisions are extremely
+      # unlikely at expected system scale.
+      #
+      # @see Stoplight::Infrastructure::Redis::Key
+      def self.key_space = KEY_SPACE
+      def key_space = self.class.key_space
     end
 
     class Memory < Base

data/lib/stoplight/domain/config.rb

@@ -6,6 +6,7 @@ module Stoplight
     #
     # @api private
     Config = Data.define(
+      :id,
       :name,
       :cool_off_time,
       :threshold,
@@ -21,10 +22,11 @@ module Stoplight
     )
     class Config
       def cool_off_time_in_milliseconds
-        (cool_off_time * 1_000).to_i
+        cool_off_time * 1_000
       end
 
       def with(
+        id: T.undefined,
         name: T.undefined,
         cool_off_time: T.undefined,
         threshold: T.undefined,
@@ -39,6 +41,7 @@ module Stoplight
         data_store: T.undefined
       )
         super(
+          id: id.is_a?(Undefined) ? self.id : id,
           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,

data/lib/stoplight/domain/error_tracking_policy.rb

@@ -9,6 +9,15 @@ module Stoplight
         @skipped = skipped
       end
 
+      def with(tracked: T.undefined, skipped: T.undefined)
+        return self if tracked.is_a?(Undefined) && skipped.is_a?(Undefined)
+
+        self.class.new(
+          tracked: tracked.is_a?(Undefined) ? @tracked : Array(tracked),
+          skipped: skipped.is_a?(Undefined) ? @skipped : Array(skipped)
+        )
+      end
+
       def track?(error)
         !skipped?(error) && tracked?(error)
       end

data/lib/stoplight/domain/failure.rb

@@ -39,6 +39,10 @@ module Stoplight
           error_message == other.error_message &&
           time == other.time
       end
+
+      alias_method :eql?, :==
+
+      def hash = [self.class, error_class, error_message, time].hash
     end
   end
 end

data/lib/stoplight/domain/id.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Stoplight
+  module Domain
+    # Helper to generate light/systems ids
+    module Id
+      # Derives id from a string
+      def self.for(name) = T.must(Digest::SHA256.hexdigest(name)[0, 12])
+    end
+  end
+end

data/lib/stoplight/domain/light.rb

@@ -5,24 +5,34 @@ module Stoplight
     #
     # @api private use +Stoplight()+ method instead
     class Light
-      include Common::Deprecations
-      include ConfigurationBuilderInterface # steep:ignore
-
+      # @api public
       attr_reader :name
-
+      # @api private
       attr_reader :green_run_strategy
+      # @api private
       attr_reader :yellow_run_strategy
+      # @api private
       attr_reader :red_run_strategy
-      attr_reader :factory
+      # @api private
       attr_reader :state_store
 
-      def initialize(name, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, factory:, state_store:)
+      # @api private
+      def initialize(
+        name,
+        green_run_strategy:,
+        yellow_run_strategy:,
+        red_run_strategy:,
+        state_store:,
+        lock_control:,
+        error_tracking_policy:
+      )
         @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
+        @lock_control = lock_control
+        @error_tracking_policy = error_tracking_policy
       end
 
       # Returns the current state of the light:
@@ -30,6 +40,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
       #
+      # @api public
       def state = state_snapshot.locked_state
 
       # Returns current color:
@@ -41,6 +52,7 @@ module Stoplight
       #   light = Stoplight('example')
       #   light.color #=> Color::GREEN
       #
+      # @api public
       def color = state_snapshot.color
 
       # Runs the given block of code with this circuit breaker
@@ -53,14 +65,22 @@ module Stoplight
       #   light = Stoplight('example')
       #   light.run(->(error) { 0 }) { 1 / 0 } #=> 0
       #
+      # @example Overriding tracked errors for one run
+      #   light.run(tracked_errors: [Timeout::Error]) { fetch_data }
+      #
       # @param fallback fallback code to run if the circuit breaker is open
+      # @param tracked_errors errors to track for this run; replaces the configured list
+      # @param skipped_errors errors to skip for this run; replaces the configured list
       # @raise [Stoplight::Error::RedLight]
-      def run(fallback = nil, &code)
+      #
+      # @api public
+      def run(fallback = nil, tracked_errors: T.undefined, skipped_errors: T.undefined, &code)
         raise ArgumentError, "nothing to run. Please, pass a block into `Light#run`" unless block_given?
 
         state_snapshot.then do |state_snapshot|
           strategy = state_strategy_factory(state_snapshot.color)
-          strategy.execute(fallback, state_snapshot:, &code)
+          error_tracking_policy = @error_tracking_policy.with(tracked: tracked_errors, skipped: skipped_errors)
+          strategy.execute(fallback, state_snapshot:, error_tracking_policy:, &code)
         end
       end
 
@@ -72,14 +92,10 @@ module Stoplight
       #
       # @param color should be either +Color::RED+ or +Color::GREEN+
       # @return locked light
+      #
+      # @api public
       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
-
-        state_store.set_state(state)
+        @lock_control.lock(color)
 
         self
       end
@@ -92,72 +108,14 @@ module Stoplight
       #   light.unlock
       #
       # @return returns unlocked light (circuit breaker)
+      #
+      # @api public
       def unlock
-        state_store.set_state(State::UNLOCKED)
+        @lock_control.unlock
 
         self
       end
 
-      # Two lights considered equal if they have the same configuration.
-      def ==(other)
-        other.is_a?(self.class) && factory == other.factory
-      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::Domain::AbstractStateTransitionNotifier>] :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 }
-      # @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
 
       def state_strategy_factory(color)

data/lib/stoplight/domain/lock_control.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Pins a light to a color (or releases the pin), writing the lock state and emitting +Telemetry::LockChanged+.
+    #
+    # @example
+    #   lock_control = Stoplight::Domain::LockControl.new(state_store:, emitter:)
+    #   lock_control.lock(Stoplight::Color::RED)
+    #   lock_control.unlock
+    #
+    # @api private
+    class LockControl
+      def initialize(state_store:, emitter:)
+        @state_store = state_store
+        @emitter = emitter
+      end
+
+      # @param color - +Color::RED+ or +Color::GREEN+
+      # @raise [Stoplight::Error::IncorrectColor] for any other color
+      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
+
+        @emitter.emit(Telemetry::LockChanged) do
+          state_snapshot = @state_store.state_snapshot
+
+          Telemetry::LockChanged.new(from_color: state_snapshot.color, to_color: color,
+            from_state: state_snapshot.locked_state, to_state: state)
+        end
+
+        @state_store.set_state(state)
+      end
+
+      def unlock
+        @emitter.emit(Telemetry::LockChanged) do
+          state_snapshot = @state_store.state_snapshot
+          from_color = state_snapshot.color
+          from_state = state_snapshot.locked_state
+          to_state = State::UNLOCKED
+          # Reuses StateSnapshot#color instead of re-deriving it: unlocking can reveal a
+          # breach/recovery color that isn't RED or GREEN, unlike a lock's fixed color.
+          to_color = state_snapshot.with(locked_state: to_state).color
+
+          Telemetry::LockChanged.new(from_color:, to_color:, from_state:, to_state:)
+        end
+
+        @state_store.set_state(State::UNLOCKED)
+      end
+    end
+  end
+end

data/lib/stoplight/domain/matcher_validator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    class MatcherValidator
+      class << self
+        def call(error_matcher)
+          name = error_matcher.is_a?(Module) ? error_matcher.name : nil
+          raise ArgumentError, message(error_matcher) if name.nil?
+
+          name
+        end
+
+        private
+
+        def message(error_matcher)
+          "error matcher #{error_matcher.inspect} must be a named class or module (e.g. StandardError, " \
+            "or a custom class/module overriding `===`) - procs, anonymous classes, and instances have no " \
+            "stable name and cannot be used here."
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/state_snapshot.rb

@@ -29,7 +29,7 @@ module Stoplight
           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?
           Color::YELLOW
         elsif breached_at
           Color::RED
@@ -44,11 +44,7 @@ module Stoplight
       # This method indicates whether the recovery has already started explicitly
       #
       def recovery_started?
-        if recovery_started_at.nil?
-          false
-        else
-          recovery_started_at! <= time
-        end
+        !!recovery_started_at
       end
 
       def recovery_started_at!

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

@@ -10,9 +10,10 @@ module Stoplight
       #
       # @api private
       class GreenRunStrategy
-        def initialize(error_tracking_policy:, request_tracker:)
-          @error_tracking_policy = error_tracking_policy
+        def initialize(request_tracker:, run_recorder:, clock:)
           @request_tracker = request_tracker
+          @run_recorder = run_recorder
+          @clock = clock
         end
 
         # Executes the provided code block when the light is in the green state.
@@ -22,37 +23,50 @@ module Stoplight
         # @yield The code block to execute.
         # @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
-          result = code.call
-          record_success
-          result
-        rescue => error
-          if @error_tracking_policy.track?(error)
-            record_error(error)
-
-            if fallback
-              fallback.call(error)
+        def execute(fallback, state_snapshot:, error_tracking_policy:, &code)
+          started_at = capture_started_at
+
+          begin
+            result = code.call
+          rescue => error
+            if error_tracking_policy.track?(error)
+              record_error(error, duration_ms: duration_since(started_at), fallback_used: !fallback.nil?)
+
+              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(duration_ms: duration_since(started_at), error: error)
               raise
             end
           else
-            # User chose to not track the error, so we record it as a success
-            record_success
-            raise
+            record_success(duration_ms: duration_since(started_at))
+            result
           end
         end
 
         private
 
-        attr_reader :config
         attr_reader :request_tracker
 
-        def record_error(error)
+        def capture_started_at
+          @clock.monotonic_millis if @run_recorder.subscribed?
+        end
+
+        def duration_since(started_at)
+          @clock.monotonic_millis - started_at if started_at
+        end
+
+        def record_error(error, duration_ms:, fallback_used:)
+          @run_recorder.record_failure(error, duration_ms:, fallback_used:)
           request_tracker.record_failure(error)
         end
 
-        def record_success
+        def record_success(duration_ms:, error: nil)
+          @run_recorder.record_success(duration_ms:, error:)
           request_tracker.record_success
         end
       end

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

@@ -10,9 +10,10 @@ module Stoplight
       #
       # @api private
       class RedRunStrategy
-        def initialize(name:, cool_off_time:)
+        def initialize(name:, cool_off_time:, run_recorder:)
           @name = name
           @cool_off_time = cool_off_time
+          @run_recorder = run_recorder
         end
 
         # Executes the fallback proc when the light is in the red state.
@@ -21,7 +22,12 @@ module Stoplight
         # @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:)
+        def execute(fallback, state_snapshot:, error_tracking_policy:)
+          @run_recorder.record_blocked(
+            fallback_used: !fallback.nil?,
+            retry_after: state_snapshot.recovery_scheduled_after
+          )
+
           if fallback
             fallback.call(nil)
           else

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

@@ -13,24 +13,24 @@ module Stoplight
       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
+          config:,
+          clock:,
+          run_recorder:,
+          emitter:
         )
-          @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
+          @clock = clock
+          @run_recorder = run_recorder
+          @emitter = emitter
         end
 
         # Executes the provided code block when the light is in the yellow state.
@@ -40,62 +40,84 @@ module Stoplight
         # @yield The code block to execute.
         # @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)
+        def execute(fallback, state_snapshot:, error_tracking_policy:, &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:, code:) do
+          with_recovery_lock(fallback:, state_snapshot:) do |started_at|
             enter_recovery(state_snapshot)
 
-            result = code.call
-            record_recovery_probe_success
-            result
-          rescue => error
-            if @error_tracking_policy.track?(error)
-              record_recovery_probe_failure(error)
+            begin
+              result = code.call
+            rescue => error
+              if error_tracking_policy.track?(error)
+                record_recovery_probe_failure(error, duration_ms: duration_since(started_at), fallback_used: !fallback.nil?)
 
-              if fallback
-                fallback.call(error)
+                if fallback
+                  fallback.call(error)
+                else
+                  raise
+                end
               else
+                record_recovery_probe_success(duration_ms: duration_since(started_at), error:)
                 raise
               end
             else
-              record_recovery_probe_success
-              raise
+              record_recovery_probe_success(duration_ms: duration_since(started_at))
+              result
             end
           end
         end
 
         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:)
+        def with_recovery_lock(fallback:, state_snapshot:)
           recovery_lock_token = recovery_lock_store.acquire_lock
           if recovery_lock_token.nil?
-            return red_run_strategy.execute(fallback, state_snapshot:, &code)
+            @run_recorder.record_blocked(
+              fallback_used: !fallback.nil?,
+              retry_after: state_snapshot.recovery_scheduled_after
+            )
+
+            return fallback.call(nil) if fallback
+
+            raise Error::RedLight.new(
+              @name,
+              cool_off_time: @config.cool_off_time,
+              retry_after: state_snapshot.recovery_scheduled_after
+            )
           end
 
           begin
-            yield
+            yield capture_started_at
           ensure
             recovery_lock_store.release_lock(recovery_lock_token)
           end
         end
 
-        def record_recovery_probe_success
-          request_tracker.record_success
+        def capture_started_at
+          @clock.monotonic_millis
+        end
+
+        def duration_since(started_at)
+          @clock.monotonic_millis - started_at
+        end
+
+        def record_recovery_probe_success(duration_ms:, error: nil)
+          @run_recorder.record_success(duration_ms:, error:)
+          request_tracker.record_success(duration_ms:)
         end
 
-        def record_recovery_probe_failure(error)
-          request_tracker.record_failure(error)
+        def record_recovery_probe_failure(error, duration_ms:, fallback_used:)
+          @run_recorder.record_failure(error, duration_ms:, fallback_used:)
+          request_tracker.record_failure(error, duration_ms:)
         end
 
         def enter_recovery(state_snapshot)
@@ -103,10 +125,12 @@ module Stoplight
 
           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)
+          @emitter.emit(Telemetry::RecoveryStarted) do
+            Telemetry::RecoveryStarted.new(
+              from_color: Color::RED,
+              to_color: Color::YELLOW,
+              breached_at: T.must(state_snapshot.breached_at)
+            )
           end
         end
       end