stoplight 5.6.0 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f540f78d771a711da32d2e50cc150c4072cf805e4ef7e52e0b5ea07dd2435fea
-  data.tar.gz: 2b859ca65577026db5e1e5af4bc2900e178edc0e230b1cfc75728ffcadc9efc8
+  metadata.gz: d96e1b5dcce81c642d059b07b2e274b8c7dbd7f246b86ee25ce40567eaba8418
+  data.tar.gz: e6b04f0ff592f89f345ff3f9ec9e26b86463ff0baeb56ef752cbd00b7f8952b8
 SHA512:
-  metadata.gz: 88eaa1d335e4b956cc354d4c8295e46acd6f4dbb0188cc4cd5ecef99a13c4cf666e09e9c2d4c4f926f2ed0c5a582c9283341de028dc4489645cbde256d805504
-  data.tar.gz: d94325879c511730d6b53b40d13fed577e10119813ec3be5f18f92caccf42d1a886d8c0fe8d6c887ff3d96610f7ac2c53e3d992d25e257cf38fea33795260272
+  metadata.gz: 01c5c2356f84eaeade94edba7113e700682911558d165b8b60186abbe0cda3d0f453427b8ab6e96f4ab51948e3ec5a109e53e1b51cc15c46c3fd79aad4865768
+  data.tar.gz: 94633b744ef88219f66289d9aae91bbb35b013bbea82c84f0f253abd15d4e5bd7ea5a123c39dffc36911479b1663cee71f786110be0ee15c3c8f56d035032e76

data/lib/stoplight/admin/dependencies.rb

@@ -8,7 +8,7 @@ module Stoplight
       attr_reader :data_store
       private :data_store
 
-      # @param data_store [Stoplight::DataStore::Base]
+      # @param data_store [Stoplight::Domain::DataStore]
       def initialize(data_store:)
         @data_store = data_store
       end

data/lib/stoplight/admin/helpers.rb

@@ -15,11 +15,16 @@ module Stoplight
       end
 
       private def data_store
-        settings.data_store.tap do |data_store|
-          if data_store.is_a?(Stoplight::DataStore::Memory)
-            raise "Stoplight Admin requires a persistent data store, but the current data store is Memory. " \
-              "Please configure a different data store in your Stoplight configuration."
-          end
+        if settings.data_store.is_a?(Stoplight::DataStore::Memory)
+          raise "Stoplight Admin requires a persistent data store, but the current data store is Memory. " \
+            "Please configure a different data store in your Stoplight configuration."
+        else
+          Stoplight::Wiring::LightBuilder.new(
+            {
+              data_store: settings.data_store,
+              config: Wiring::Light::DefaultConfig
+            }
+          ).__send__(:data_store)
         end
       end
     end

data/lib/stoplight/admin/lights_repository.rb

@@ -4,11 +4,11 @@ module Stoplight
   class Admin
     class LightsRepository
       # @!attribute data_store
-      #   @return [Stoplight::DataStore::Base]
+      #   @return [Stoplight::Domain::DataStore]
       attr_reader :data_store
       private :data_store
 
-      #  @param data_store [Stoplight::DataStore::Base]
+      #  @param data_store [Stoplight::Domain::DataStore]
       def initialize(data_store:)
         @data_store = data_store
       end
@@ -37,46 +37,49 @@ module Stoplight
       #   color
       # @return [void]
       def lock(name, color = nil)
-        light = build_light(name)
+        config = build_config(name)
+        color ||= data_store.get_state_snapshot(config).color
 
-        case color || light.color
+        case color
         when Stoplight::Color::GREEN
-          light.lock(Stoplight::Color::GREEN)
+          data_store.set_state(config, Stoplight::State::LOCKED_GREEN)
         else
-          light.lock(Stoplight::Color::RED)
+          data_store.set_state(config, Stoplight::State::LOCKED_RED)
         end
       end
 
       # @param name [String] unlocks light by its name
       # @return [void]
       def unlock(name)
-        build_light(name).unlock
+        config = build_config(name)
+        data_store.set_state(config, Domain::State::UNLOCKED)
       end
 
       # @param name [String] removes light metadata by its name
       # @return [void]
       def remove(name)
-        light = build_light(name)
+        config = build_config(name)
 
-        data_store.delete_light(light.config)
+        data_store.delete_light(config)
       end
 
       private def load_light(name)
-        light = build_light(name)
+        config = build_config(name)
+
         # failures, state
-        state_snapshot = data_store.get_state_snapshot(light.config)
-        metrics = data_store.get_metrics(light.config)
+        state_snapshot = data_store.get_state_snapshot(config)
+        metrics = data_store.get_metrics(config)
 
         Light.new(
           name: name,
-          color: light.color,
+          color: state_snapshot.color,
           state: state_snapshot.locked_state,
           failures: [metrics.last_error].compact
         )
       end
 
-      private def build_light(name)
-        Stoplight(name, data_store: data_store)
+      private def build_config(name)
+        Wiring::Light::DefaultConfig.with(name:)
       end
     end
   end

data/lib/stoplight/admin.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require "cgi" # Ruby 3.2 needs this
+require "cgi/escape"
+require "cgi/util" if RUBY_VERSION < "3.5"
 
 begin
   require "sinatra/base"

data/lib/stoplight/common/deprecations.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Common
+    module Deprecations
+      extend self
+
+      def deprecate(message) = warn("[DEPRECATION] #{message}")
+    end
+  end
+end

data/lib/stoplight/domain/config.rb

@@ -7,7 +7,7 @@ module Stoplight
     # # @!attribute [r] name
     #   @return [String]
     #
-    # @!attribute [r] cool_off_time
+    # @!attribute [r] cool_off_time - cool-off time in seconds
     #   @return [Numeric]
     #
     # @!attribute [r] threshold
@@ -50,6 +50,10 @@ module Stoplight
 
         !skip && track
       end
+
+      def cool_off_time_in_milliseconds
+        cool_off_time * 1_000
+      end
     end
   end
 end

data/lib/stoplight/domain/data_store.rb

@@ -44,7 +44,11 @@ module Stoplight
       #
       # @param config [Stoplight::Domain::Config] The light configuration.
       # @return [void]
-      def clear_windowed_metrics(config)
+      def clear_metrics(config)
+        raise NotImplementedError
+      end
+
+      def clear_recovery_metrics(config)
         raise NotImplementedError
       end
 
@@ -91,6 +95,18 @@ module Stoplight
         raise NotImplementedError
       end
 
+      # Acquires recovery lock for serializing probe execution.
+      #
+      # @param config [Stoplight::Domain::Config]
+      # @return [Stoplight::Domain::LockToken, nil] Lock if acquired, nil if contended
+      def acquire_recovery_lock(config) = raise NotImplementedError
+
+      # Releases previously acquired lock.
+      #
+      # @param lock [Stoplight::Domain::RecoveryLockToken]
+      # @return [void]
+      def release_recovery_lock(lock) = raise NotImplementedError
+
       # Transitions the Stoplight to the specified color.
       #
       # This method performs a color transition operation that works across distributed instances

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

@@ -15,9 +15,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 +42,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 +69,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 +99,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 +127,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 +179,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,9 +211,22 @@ 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
     end

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
-        state_snapshot.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
-        state_snapshot.color
-      end
+      def color = state_snapshot.color
 
       # Runs the given block of code with this circuit breaker
       #
@@ -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,9 +202,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/metrics.rb

@@ -12,12 +12,12 @@ module Stoplight
     #   A number of errors withing requested window. Zero for non-windowed metrics
     #   @return [Integer]
     #
-    # @!attribute total_consecutive_errors
-    #   A total number of consecutive errors
+    # @!attribute consecutive_errors
+    #   A number of consecutive errors
     #   @return [Integer]
     #
-    # @!attribute total_consecutive_successes
-    #   A total number of consecutive successes
+    # @!attribute consecutive_successes
+    #   A number of consecutive successes
     #   @return [Integer]
     #
     # @!attribute last_error
@@ -30,32 +30,11 @@ module Stoplight
     Metrics = Data.define(
       :successes,
       :errors,
-      :total_consecutive_errors,
-      :total_consecutive_successes,
+      :consecutive_errors,
+      :consecutive_successes,
       :last_error,
       :last_success_at
     ) do
-      # A number of consecutive errors withing requested window
-      #
-      # @return [Integer]
-      def consecutive_errors
-        if errors # we effectively check if this is windowed metrics
-          [total_consecutive_errors, errors].min
-        else
-          total_consecutive_errors
-        end
-      end
-
-      # A number of consecutive successes withing requested window
-      #
-      def consecutive_successes
-        if successes # we effectively check if this is windowed metrics
-          [total_consecutive_successes, successes].min
-        else
-          total_consecutive_successes
-        end
-      end
-
       # Calculates the error rate based on the number of successes and errors.
       #
       # @return [Float]

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/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