stoplight 5.8.3 → 6.0.0.rc2

data/lib/stoplight/domain/traffic_control/error_rate.rb

@@ -10,22 +10,22 @@ module Stoplight
       #   config = Stoplight::Domain::Config.new(threshold: 0.6, window_size: 300, traffic_control:)
       #
       # Will switch to red if 60% error rate reached within the 5-minute (300 seconds) sliding window.
-      # By default this traffic control strategy starts evaluating only after 10 requests have been made. You can
-      # adjust this by passing a different value for `min_requests` when initializing the strategy.
-      #
-      #   traffic_control = Stoplight::Domain::TrafficControl::ErrorRate.new(min_requests: 100)
       #
       # @api private
       class ErrorRate
-        # @param min_requests Minimum number of requests before traffic control is applied.
-        #   until this number of requests is reached, the error rate will not be considered.
-        def initialize(min_requests: 10)
-          @min_requests = min_requests
+        NAME = :error_rate
+
+        MIN_REQUESTS = 100
+        private_constant :MIN_REQUESTS
+
+        def initialize
         end
 
         def check_compatibility(config)
           if config.window_size.nil?
             CompatibilityResult.incompatible("`window_size` should be set")
+          elsif !config.threshold.is_a?(Numeric)
+            CompatibilityResult.incompatible("`threshold` should be a number")
           elsif config.threshold < 0 || config.threshold > 1
             CompatibilityResult.incompatible("`threshold` should be between 0 and 1")
           else
@@ -39,16 +39,20 @@ module Stoplight
 
           raise ArgumentError, "accepts only windowed metrics" if error_rate.nil? || requests.nil?
 
-          requests >= min_requests && error_rate >= config.threshold
+          requests >= MIN_REQUESTS && error_rate >= config.threshold
         end
 
+        def name = NAME.to_s
+
         def ==(other)
-          other.is_a?(self.class) && min_requests == other.min_requests
+          other.is_a?(self.class)
         end
 
-        protected
+        def eql?(other)
+          self == other
+        end
 
-        attr_reader :min_requests
+        def hash = self.class.hash
       end
     end
   end

data/lib/stoplight/domain/traffic_recovery/consecutive_successes.rb

@@ -34,11 +34,13 @@ module Stoplight
       #
       # @api private
       class ConsecutiveSuccesses
+        NAME = :consecutive_successes
+
         def check_compatibility(config)
-          if config.recovery_threshold <= 0
-            CompatibilityResult.incompatible("`recovery_threshold` should be bigger than 0")
-          elsif !config.recovery_threshold.is_a?(Integer)
+          if !config.recovery_threshold.is_a?(Integer)
             CompatibilityResult.incompatible("`recovery_threshold` should be an integer")
+          elsif config.recovery_threshold <= 0
+            CompatibilityResult.incompatible("`recovery_threshold` should be bigger than 0")
           else
             CompatibilityResult.compatible
           end
@@ -55,7 +57,11 @@ module Stoplight
           end
         end
 
+        def hash = self.class.hash
+
         def ==(other) = other.is_a?(self.class)
+
+        def name = NAME.to_s
       end
     end
   end

data/lib/stoplight/error.rb

@@ -5,13 +5,22 @@ module Stoplight
     class Base < StandardError
     end
 
+    class UnregisteredLightError < Base
+    end
+
     class ConfigurationError < Base
     end
 
     class IncorrectColor < Base
     end
 
+    class TooManySubscriptions < Base
+    end
+
     class RedLight < Base
+      EXCEPTION_MESSAGE = 'Stoplight "%{light_name}" is red - traffic stopped until recovery.'
+      private_constant :EXCEPTION_MESSAGE
+
       # @!attribute light_name
       #   @return [String] The light's name
       attr_reader :light_name
@@ -39,7 +48,7 @@ module Stoplight
         @cool_off_time = cool_off_time
         @retry_after = retry_after
 
-        super(light_name)
+        super(format(EXCEPTION_MESSAGE, light_name: light_name))
       end
     end
   end

data/lib/stoplight/infrastructure/config_serializer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    class ConfigSerializer
+      class << self
+        def call(config)
+          {
+            "id" => config.id,
+            "name" => config.name,
+            "cool_off_time" => config.cool_off_time,
+            "threshold" => config.threshold,
+            "recovery_threshold" => config.recovery_threshold,
+            "window_size" => config.window_size,
+            "tracked_errors" => config.tracked_errors.map(&:name),
+            "skipped_errors" => config.skipped_errors.map(&:name),
+            "traffic_control" => {
+              "strategy" => serialize_traffic_control(config.traffic_control)
+            },
+            "traffic_recovery" => {
+              "strategy" => serialize_traffic_recovery(config.traffic_recovery)
+            }
+          }
+        end
+
+        private
+
+        def serialize_traffic_control(traffic_control)
+          case traffic_control
+          when Domain::TrafficControl::ConsecutiveErrors
+            Domain::TrafficControl::ConsecutiveErrors::NAME.to_s
+          when Domain::TrafficControl::ErrorRate
+            Domain::TrafficControl::ErrorRate::NAME.to_s
+          else
+            raise TypeError, "unable to serialize traffic_control: #{traffic_control}"
+          end
+        end
+
+        def serialize_traffic_recovery(traffic_recovery)
+          case traffic_recovery
+          when Domain::TrafficRecovery::ConsecutiveSuccesses
+            Domain::TrafficRecovery::ConsecutiveSuccesses::NAME.to_s
+          else
+            raise TypeError, "unable to serialize traffic_recovery: #{traffic_recovery}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/fail_safe/error_notifier.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      # Wraps a user-provided error notifier so a failure in the notifier itself
+      # cannot escape to callers of fail-safe components.
+      #
+      # @api private
+      class ErrorNotifier
+        attr_reader :error_notifier
+
+        def initialize(error_notifier:)
+          @error_notifier = error_notifier
+        end
+
+        def call(error)
+          error_notifier.call(error)
+        rescue => notifier_error
+          warn "Stoplight error_notifier raised: #{notifier_error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/fail_safe/storage/registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      module Storage
+        class Registry
+          def initialize(primary_registry:, error_notifier:, failover_registry:, circuit_breaker:)
+            @primary_registry = primary_registry
+            @error_notifier = error_notifier
+            @failover_registry = failover_registry
+            @circuit_breaker = circuit_breaker
+          end
+
+          def ids
+            fallback = ->(error) {
+              @error_notifier.call(error) if error
+              @failover_registry.ids
+            }
+            @circuit_breaker.run(fallback) do
+              @primary_registry.ids
+            end
+          end
+
+          def all_configs
+            fallback = ->(error) {
+              @error_notifier.call(error) if error
+              @failover_registry.all_configs
+            }
+            @circuit_breaker.run(fallback) do
+              @primary_registry.all_configs
+            end
+          end
+
+          def register(config)
+            fallback = ->(error) {
+              @error_notifier.call(error) if error
+              @failover_registry.register(config)
+            }
+            @circuit_breaker.run(fallback) do
+              @primary_registry.register(config)
+            end
+          end
+
+          def unregister(id)
+            fallback = ->(error) {
+              @error_notifier.call(error) if error
+              @failover_registry.unregister(id)
+            }
+            @circuit_breaker.run(fallback) do
+              @primary_registry.unregister(id)
+            end
+          end
+
+          def config_for(id)
+            fallback = ->(error) {
+              @error_notifier.call(error) if error
+              @failover_registry.config_for(id)
+            }
+            @circuit_breaker.run(fallback) do
+              @primary_registry.config_for(id)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/memory/storage/registry.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        class Registry
+          def ids = []
+          def all_configs = []
+
+          def register(config) = nil
+          def unregister(id) = nil
+          def config_for(id) = nil
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/memory/storage/unbounded_metrics.rb

@@ -28,64 +28,50 @@ module Stoplight
 
           # Get metrics for the current light
           def metrics_snapshot
-            mutex.synchronize do
-              Domain::MetricsSnapshot.new(
-                errors: nil,
-                successes: nil,
-                consecutive_errors: consecutive_errors.to_i,
-                consecutive_successes: consecutive_successes.to_i,
-                last_error: last_error,
-                last_success_at: last_success_at
-              )
-            end
+            @mutex.synchronize { build_metrics_snapshot }
           end
 
           # Records successful circuit breaker execution
           def record_success
-            current_time = clock.current_time
+            current_time = @clock.current_time
 
-            mutex.synchronize do
-              if last_success_at.nil? || current_time > last_success_at
-                self.last_success_at = current_time
+            @mutex.synchronize do
+              if @last_success_at.nil? || current_time > T.must(@last_success_at)
+                @last_success_at = current_time
               end
 
-              self.consecutive_errors = 0
-              self.consecutive_successes += 1
+              @consecutive_errors = 0
+              @consecutive_successes += 1
             end
           end
 
           # Records failed circuit breaker execution
           def record_failure(exception)
-            current_time = clock.current_time
+            current_time = @clock.current_time
             failure = Domain::Failure.from_error(exception, time: current_time)
-            last_error_at = self.last_error_at
 
-            mutex.synchronize do
+            @mutex.synchronize do
+              last_error_at = self.last_error_at
+
               if last_error_at.nil? || failure.occurred_at > last_error_at
-                self.last_error = failure
+                @last_error = failure
               end
 
-              self.consecutive_errors += 1
-              self.consecutive_successes = 0
+              @consecutive_errors += 1
+              @consecutive_successes = 0
+
+              build_metrics_snapshot
             end
           end
 
           def clear
-            mutex.synchronize do
+            @mutex.synchronize do
               initialize_metrics
             end
           end
 
           private
 
-          attr_accessor :consecutive_errors
-          attr_accessor :consecutive_successes
-          attr_accessor :last_error
-          attr_accessor :last_success_at
-
-          attr_reader :mutex
-          attr_reader :clock
-
           def initialize_metrics
             @consecutive_errors = 0
             @consecutive_successes = 0
@@ -94,7 +80,18 @@ module Stoplight
           end
 
           def last_error_at
-            last_error&.occurred_at
+            @last_error&.occurred_at
+          end
+
+          def build_metrics_snapshot
+            Domain::MetricsSnapshot.new(
+              errors: nil,
+              successes: nil,
+              consecutive_errors: @consecutive_errors,
+              consecutive_successes: @consecutive_successes,
+              last_error: @last_error,
+              last_success_at: @last_success_at
+            )
           end
         end
       end

data/lib/stoplight/infrastructure/memory/storage/window_metrics/sliding_window.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Memory
+      module Storage
+        class WindowMetrics
+          # Hash-based sliding window for O(1) amortized operations.
+          #
+          # Maintains a running sum and stores per-second counts in a Hash. Ruby's Hash
+          # preserves insertion order (FIFO), allowing efficient removal of expired
+          # buckets from the front via +Hash#shift+, with their counts subtracted from
+          # the running sum.
+          #
+          # Performance: O(1) amortized for both reads and writes
+          # Memory: Bounded to the number of buckets
+          #
+          # @note Not thread-safe; synchronization must be handled externally
+          # @api private
+          class SlidingWindow
+            def initialize(clock:, window_size:)
+              # A hash mapping time buckets to their counts
+              @buckets = Hash.new { |buckets, bucket| buckets[bucket] = 0 }
+              # The running sum of all increments in the current window
+              @running_sum = 0
+              @evicted_through = nil
+              @clock = clock
+              @window_size = window_size
+            end
+
+            # Increment the count at the current monotonic second
+            def increment
+              timestamp = @clock.monotonic_seconds
+              slide_window!(timestamp - @window_size)
+              @buckets[timestamp.to_i] += 1
+              @running_sum += 1
+            end
+
+            def sum_in_window
+              slide_window!(@clock.monotonic_seconds - @window_size)
+              @running_sum
+            end
+
+            def inspect
+              "#<#{self.class.name} #{@buckets}>"
+            end
+
+            private
+
+            def slide_window!(window_start)
+              # A bucket is keyed at the second it was written, which for a whole-second window is
+              # always past the boundary in force then, so a boundary already evicted can expire
+              # nothing.
+              boundary = window_start.floor
+              return if boundary == @evicted_through
+
+              @evicted_through = boundary
+
+              loop do
+                timestamp, sum = @buckets.first
+                if timestamp.nil? || timestamp > boundary
+                  break
+                else
+                  @running_sum -= sum.to_i
+                  @buckets.shift
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/memory/storage/window_metrics.rb

@@ -27,28 +27,16 @@ module Stoplight
 
           # Get metrics for the current light
           def metrics_snapshot
-            mutex.synchronize do
-              window_start = (clock.current_time - @window_size)
-              errors = @errors.sum_in_window(window_start)
-              successes = @successes.sum_in_window(window_start)
-
-              Domain::MetricsSnapshot.new(
-                errors:,
-                successes:,
-                consecutive_errors: [@consecutive_errors, errors].min,
-                consecutive_successes: [@consecutive_successes, successes].min,
-                last_error: @last_error,
-                last_success_at: @last_success_at
-              )
-            end
+            @mutex.synchronize { build_metrics_snapshot }
           end
 
           # Records successful circuit breaker execution
           def record_success
-            mutex.synchronize do
-              current_time = clock.current_time
+            @mutex.synchronize do
               @successes.increment
 
+              current_time = @clock.current_time
+
               if @last_success_at.nil? || current_time > T.must(@last_success_at)
                 @last_success_at = current_time
               end
@@ -60,10 +48,10 @@ module Stoplight
 
           # Records failed circuit breaker execution
           def record_failure(exception)
-            mutex.synchronize do
+            @mutex.synchronize do
               @errors.increment
 
-              failure = Domain::Failure.from_error(exception, time: clock.current_time)
+              failure = Domain::Failure.from_error(exception, time: @clock.current_time)
               last_error_at = @last_error&.occurred_at
 
               if last_error_at.nil? || failure.occurred_at > last_error_at
@@ -72,27 +60,40 @@ module Stoplight
 
               @consecutive_errors += 1
               @consecutive_successes = 0
+
+              build_metrics_snapshot
             end
           end
 
           def clear
-            mutex.synchronize do
+            @mutex.synchronize do
               initialize_metrics
             end
           end
 
           private
 
-          attr_reader :mutex
-          attr_reader :clock
-
           def initialize_metrics
             @consecutive_errors = 0
             @consecutive_successes = 0
             @last_error = nil
             @last_success_at = nil
-            @successes = Infrastructure::Memory::DataStore::SlidingWindow.new(clock:)
-            @errors = Infrastructure::Memory::DataStore::SlidingWindow.new(clock:)
+            @successes = SlidingWindow.new(clock: @clock, window_size: @window_size)
+            @errors = SlidingWindow.new(clock: @clock, window_size: @window_size)
+          end
+
+          def build_metrics_snapshot
+            errors = @errors.sum_in_window
+            successes = @successes.sum_in_window
+
+            Domain::MetricsSnapshot.new(
+              errors:,
+              successes:,
+              consecutive_errors: [@consecutive_errors, errors].min,
+              consecutive_successes: [@consecutive_successes, successes].min,
+              last_error: @last_error,
+              last_success_at: @last_success_at
+            )
           end
         end
       end

data/lib/stoplight/infrastructure/notifier/fail_safe.rb

@@ -13,12 +13,14 @@ module Stoplight
         attr_reader :notifier
         # The underlying notifier being wrapped.
         attr_reader :error_notifier
+        attr_reader :circuit_breaker
 
         # @param notifier The notifier to wrap.
         # @param error_notifier called when wrapped data store fails
-        def initialize(notifier:, error_notifier:)
+        def initialize(notifier:, error_notifier:, circuit_breaker:)
           @notifier = notifier
           @error_notifier = error_notifier
+          @circuit_breaker = circuit_breaker
         end
 
         # Sends a notification using the wrapped notifier with fail-safe mechanisms.
@@ -37,13 +39,6 @@ module Stoplight
         def ==(other)
           other.is_a?(self.class) && notifier == other.notifier
         end
-
-        private def circuit_breaker
-          @circuit_breaker ||= Stoplight.system_light(
-            "stoplight:notifier:fail_safe:#{notifier.class.name}",
-            notifiers: []
-          )
-        end
       end
     end
   end

data/lib/stoplight/infrastructure/notifier/generic.rb

@@ -8,7 +8,7 @@ module Stoplight
       #
       # @example Custom Notifier Implementation and Usage
       #     # Custom notifier that writes notifications to a file
-      #     class FileNotifier < Stoplight::Domain::StateTransitionNotifier
+      #     class FileNotifier
       #       include Stoplight::Notifier::Generic
       #
       #       def initialize(file_path)
@@ -69,11 +69,11 @@ module Stoplight
 
         # Processes the notification message.
         #
-        # :nocov:
+        # simplecov:disable
         def put(message)
           raise NotImplementedError
         end
-        # :nocov:
+        # simplecov:enable
       end
     end
   end

data/lib/stoplight/infrastructure/redis/key.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module Redis
+      # Immutable key namespace for a light within a system.
+      #
+      # @example
+      #   key_space #=> "stoplight:v6:df384ae97c77:{cfe6861fa39e}"
+      #   key_space.join(:locks, :recovery)  #=> "stoplight:v6:df384ae97c77:{cfe6861fa39e}:locks:recovery"
+      class Key < String
+        def initialize(*segments)
+          super(segments.join(":"))
+          freeze
+        end
+
+        # Builds a Redis key.
+        #
+        # @param segments to append
+        # @return Full Redis key
+        def join(*segments) = Key.new(self, *segments)
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/redis/storage/now.lua

@@ -0,0 +1,9 @@
+-- Returns current time in milliseconds since epoch.
+-- In production: calls redis.call("TIME") for server time.
+-- In tests: overridden with test double that reads from a Redis key.
+local function now()
+  local time = redis.call("TIME")
+  local seconds = tonumber(time[1])
+  local microseconds = tonumber(time[2])
+  return seconds * 1000 + math.floor(microseconds / 1000)
+end

data/lib/stoplight/infrastructure/redis/storage/recovery_lock.rb

@@ -39,11 +39,9 @@ module Stoplight
             recovery_lock if acquired
           end
 
-          # @param recovery_lock [Stoplight::Infrastructure::Redis::DataStore::RecoveryLockToken]
-          # @return [void]
           def release_lock(recovery_lock)
             scripting.call(
-              :"recovery_lock/release_lock",
+              "recovery_lock/release_lock",
               keys: [lock_key], args: [recovery_lock.token]
             )
           end
@@ -55,7 +53,7 @@ module Stoplight
           attr_reader :scripting
           attr_reader :key_space
 
-          def lock_key = key_space.key(:locks, :recovery)
+          def lock_key = key_space.join("locks", "recovery")
           def lock_timeout = config.cool_off_time_in_milliseconds
         end
       end

data/lib/stoplight/infrastructure/redis/storage/recovery_metrics.rb

@@ -11,7 +11,7 @@ module Stoplight
         class RecoveryMetrics < UnboundedMetrics
           def initialize(redis:, scripting:, key_space:, clock:)
             super
-            @metrics_key = key_space.key(:recovery_metrics)
+            @metrics_key = key_space.join("recovery_metrics")
           end
         end
       end