stoplight 5.5.0 → 5.7.0

data/lib/stoplight/domain/light.rb

@@ -8,6 +8,7 @@ module Stoplight
     # @api private use +Stoplight()+ method instead
     class Light
       extend Forwardable
+      include Common::Deprecations
       include ConfigurationBuilderInterface
 
       # @!attribute [r] config
@@ -32,22 +33,22 @@ module Stoplight
       #   @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
 
+      # @!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:, data_store:, factory:)
+      def initialize(config, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, factory:, state_store:)
         @config = config
-        @data_store = data_store
         @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:
@@ -56,9 +57,7 @@ module Stoplight
       #  * +Stoplight::State::UNLOCKED+ -- light is not locked and follow the configured rules
       #
       # @return [String]
-      def state
-        metadata.locked_state
-      end
+      def state = state_snapshot.locked_state
 
       # Returns current color:
       #   * +Stoplight::Color::GREEN+ -- circuit breaker is closed
@@ -70,9 +69,7 @@ module Stoplight
       #   light.color #=> Color::GREEN
       #
       # @return [String] returns current light color
-      def color
-        metadata.color
-      end
+      def color = state_snapshot.color
 
       # Runs the given block of code with this circuit breaker
       #
@@ -91,9 +88,9 @@ module Stoplight
       def run(fallback = nil, &code)
         raise ArgumentError, "nothing to run. Please, pass a block into `Light#run`" unless block_given?
 
-        metadata.then do |metadata|
-          strategy = state_strategy_factory(metadata.color)
-          strategy.execute(fallback, metadata:, &code)
+        state_snapshot.then do |state_snapshot|
+          strategy = state_strategy_factory(state_snapshot.color)
+          strategy.execute(fallback, state_snapshot:, &code)
         end
       end
 
@@ -112,7 +109,7 @@ module Stoplight
         else raise Error::IncorrectColor
         end
 
-        data_store.set_state(config, state)
+        state_store.set_state(state)
 
         self
       end
@@ -126,7 +123,7 @@ module Stoplight
       #
       # @return [Stoplight::Light] returns unlocked light (circuit breaker)
       def unlock
-        data_store.set_state(config, State::UNLOCKED)
+        state_store.set_state(State::UNLOCKED)
 
         self
       end
@@ -136,9 +133,7 @@ module Stoplight
       # @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,8 +166,26 @@ 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()+
       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
 
@@ -189,10 +202,7 @@ module Stoplight
         end
       end
 
-      # @return [Stoplight::Domain::Metadata]
-      def metadata
-        data_store.get_metadata(config)
-      end
+      def state_snapshot = state_store.state_snapshot
     end
   end
 end

data/lib/stoplight/domain/metrics.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Request metrics over a given window.
+    #
+    # @!attribute successes
+    #   A number of successes withing requested window. Zero for non-windowed metrics
+    #   @return [Integer]
+    #
+    # @!attribute errors
+    #   A number of errors withing requested window. Zero for non-windowed metrics
+    #   @return [Integer]
+    #
+    # @!attribute consecutive_errors
+    #   A number of consecutive errors
+    #   @return [Integer]
+    #
+    # @!attribute consecutive_successes
+    #   A number of consecutive successes
+    #   @return [Integer]
+    #
+    # @!attribute last_error
+    #   @return [Stoplight::Domain::Failure, nil]
+    #
+    # @!attribute last_success_at
+    #   @return [Time, nil]
+    #
+    # @api private
+    Metrics = Data.define(
+      :successes,
+      :errors,
+      :consecutive_errors,
+      :consecutive_successes,
+      :last_error,
+      :last_success_at
+    ) do
+      # 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
+    end
+  end
+end

data/lib/stoplight/domain/recovery_lock_token.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Token representing an acquired recovery lock.
+    #
+    # Returned by +DataStore#acquire_recovery_lock+ and passed to
+    # +DataStore#release_recovery_lock+ to identify which lock to release.
+    #
+    # The actual locking mechanism lives in DataStore implementations,
+    # not in these tokens.
+    class RecoveryLockToken
+    end
+  end
+end

data/lib/stoplight/domain/{metadata.rb → state_snapshot.rb}

@@ -2,41 +2,39 @@
 
 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,
+    # @!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,
-      :recovered_at,
-      :current_time
+      :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
+        elsif (recovery_scheduled_after && recovery_scheduled_after < time) || recovery_started_at
           Color::YELLOW
         elsif breached_at
           Color::RED
@@ -45,20 +43,14 @@ module Stoplight
         end
       end
 
-      # Calculates the error rate based on the number of successes and errors.
+      # YELLOW color could be entered implicitly through a timeout
+      # and explicitly through a transition.
       #
-      # @return [Float]
-      def error_rate
-        if (successes + errors).zero?
-          0.0
-        else
-          errors.fdiv(successes + errors)
-        end
-      end
-
-      # @return [Integer]
-      def requests
-        successes + errors
+      # This method indicates whether the recovery has already started explicitly
+      #
+      # @return [Boolean]
+      def recovery_started?
+        recovery_started_at && recovery_started_at <= time
       end
     end
   end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Storage
+      # Encapsulates metrics storage for circuit breaker execution tracking.
+      #
+      # This abstraction isolates metrics collection and retrieval from the
+      # broader data store concerns, enabling:
+      # - Purpose-built implementations optimized for time-series data
+      # - Independent scaling and optimization of metrics vs. state storage
+      # - Clearer separation between "what happened" (metrics) and "what to do" (state)
+      #
+      # Lifecycle: A Metrics instance is scoped to a single circuit breaker
+      # configuration. Each circuit gets its own metrics store instance,
+      # allowing different circuits to use different storage strategies.
+      #
+      # @abstract
+      class Metrics
+        # Retrieves a snapshot of current metrics for decision-making.
+        #
+        # @return [Stoplight::Domain::Metrics]
+        def metrics_snapshot = raise NotImplementedError
+
+        # Records a successful circuit breaker execution
+        #
+        # @return [void]
+        def record_success = raise NotImplementedError
+
+        # Records a failed circuit breaker execution
+        #
+        # @param error [StandardError]
+        # @return [void]
+        def record_failure(error) = raise NotImplementedError
+
+        # Clears all metrics for this circuit
+        # @return [void]
+        def clear = raise NotImplementedError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Storage
+      # Encapsulates recovery lock management for coordinating recovery probes.
+      #
+      # When a circuit enters YELLOW state (half-open), it begins sending
+      # "recovery probes" - test requests to check if the protected service
+      # has recovered. In distributed deployments with multiple instances,
+      # recovery locks ensure only ONE instance sends probes at a time.
+      #
+      # Without coordination, all instances would simultaneously:
+      # 1. Detect the circuit is YELLOW
+      # 2. Send recovery probes to the struggling service
+      # 3. Potentially overwhelm it with "test" traffic
+      #
+      # Lock Lifecycle:
+      #
+      #   Instance A: acquire_lock -> probe -> release_lock
+      #   Instance B: acquire_lock -> nil (already held) -> skip probe
+      #   Instance C: acquire_lock -> nil (already held) -> skip probe
+      #
+      # Lock Semantics:
+      # - Returns +nil+ if lock is already held. Never blocks waiting for lock availability
+      # - Locks must automatically expire when persisted storage is used
+      # - Failed releases are acceptable (timeout provides safety)
+      #
+      # @abstract
+      # @see Stoplight::Domain::Strategies::YellowRunStrategy
+      class RecoveryLock
+        # Attempts to acquire recovery lock for exclusive probe execution.
+        #
+        # This method tries to acquire a lock that serializes recovery probe
+        # execution across multiple instances. If the lock is already held by
+        # another instance, returns +nil+ immediately without blocking.
+        #
+        # @return [Stoplight::Domain::RecoveryLockToken, nil]
+        #   - +RecoveryLockToken+: Lock acquired, caller should send probe
+        #   - +nil+: Lock unavailable, another instance is probing
+        #
+        def acquire_lock = raise NotImplementedError
+
+        # Releases a previously acquired lock.
+        #
+        # This method releases the lock token returned by +#acquire_lock+,
+        # allowing other instances to acquire it. Release should be called
+        # in an ensure block to guarantee cleanup even if probe fails.
+        #
+        # @param lock [Stoplight::Domain::RecoveryLockToken] The token returned by +#acquire_lock+
+        # @return [void]
+        def release_lock(lock) = raise NotImplementedError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Storage
+      # Encapsulates circuit breaker state storage.
+      #
+      # State management handles the current operational mode of a circuit breaker:
+      # - Color (GREEN/YELLOW/RED) - whether the circuit is open or closed
+      # - Lock state (LOCKED_GREEN/LOCKED_RED/UNLOCKED) - manual overrides
+      # - State transitions - tracking color changes for notifications #
+      #
+      # State requires stronger consistency than metrics because:
+      # - Multiple instances must agree on circuit color
+      # - Race conditions during transitions must be handled
+      # - Lock states must be immediately visible across instances
+      #
+      # @abstract
+      # @see Stoplight::Domain::Storage::Metrics
+      class State
+        # Retrieves current state snapshot for decision-making.
+        #
+        # The snapshot is an immutable view of the circuit's current state,
+        # including its color and lock status. This method is called on every
+        # circuit breaker invocation to determine whether to allow traffic.
+        #
+        # This is called on every request, so implementations should be fast.
+        #
+        # @return [Stoplight::Domain::StateSnapshot]
+        def state_snapshot = raise NotImplementedError
+
+        # Sets the lock state of the circuit.
+        #
+        # Locks allow manual override of circuit behavior:
+        # - LOCKED_GREEN: Force circuit closed (allow all traffic)
+        # - LOCKED_RED: Force circuit open (block all traffic)
+        # - UNLOCKED: Follow normal circuit breaker rules
+        #
+        # Lock states take precedence over color states. A locked circuit
+        # ignores failure thresholds and stays in the locked state until
+        # explicitly unlocked.
+        #
+        # Use Cases:
+        # - Emergency traffic control during incidents
+        # - Maintenance windows (lock RED to prevent traffic)
+        # - Gradual rollout (lock GREEN during testing)
+        #
+        # @param state [String] The new state to set.
+        # @return [String] The state that was set.
+        def set_state(state) = raise NotImplementedError
+
+        # Transitions the Stoplight to the specified color.
+        #
+        # This method performs a color transition operation that works across distributed instances
+        # of the light. It ensures that in a multi-instance environment, only one instance
+        # is considered the "first" to perform the transition (and therefore responsible for
+        # triggering notifications).
+        #
+        # @param color [String] The target color/state to transition to.
+        #   Should be one of Stoplight::Color::GREEN, Stoplight::Color::YELLOW, or Stoplight::Color::RED.
+        #
+        # @return [Boolean] Returns +true+ if this instance was the first to perform this specific transition
+        #   (and should therefore trigger notifications). Returns +false+ if another instance already
+        #   initiated this transition.
+        #
+        # @note In distributed environments with multiple instances, race conditions can occur when instances
+        #   attempt conflicting transitions simultaneously (e.g., one instance tries to transition from
+        #   YELLOW to GREEN while another tries YELLOW to RED). The implementation handles this, but
+        #   be aware that the last operation may determine the final color of the light.
+        #
+        def transition_to_color(color) = raise NotImplementedError
+
+        # Clears all state data for this circuit.
+        #
+        # This removes the circuit from storage entirely, resetting it to
+        # default (unlocked, green) state. The next invocation will start
+        # with fresh state.
+        #
+        # @note This does NOT clear metrics. If you want to fully
+        # reset a circuit, clear both state and metrics stores.
+        #
+        # @return [void]
+        def clear = raise NotImplementedError
+      end
+    end
+  end
+end

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

@@ -28,11 +28,11 @@ module Stoplight
         # 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.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # @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)
+        def execute(fallback, state_snapshot:, &code)
           # TODO: Consider implementing sampling rate to limit the memory footprint
           code.call.tap { record_success }
         rescue => error

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

@@ -21,17 +21,17 @@ module Stoplight
         # 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.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # @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:)
+        def execute(fallback, state_snapshot:)
           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
+              retry_after: state_snapshot.recovery_scheduled_after
             )
           end
         end

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

@@ -10,17 +10,12 @@ module Stoplight
       # @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.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # :nocov:
-        def execute(fallback, metadata:, &code)
+        def execute(fallback, state_snapshot:, &code)
           raise NotImplementedError, "Subclasses must implement the execute method"
         end
         # :nocov:
-
-        # @return [Boolean]
-        def ==(other)
-          other.is_a?(self.class)
-        end
       end
     end
   end