stoplight 5.8.3 → 6.0.0.rc2

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

@@ -6,167 +6,77 @@ module Stoplight
       module Storage
         # Distributed storage for time-windowed light metrics using Redis.
         #
-        # This class implements sliding window metrics using Redis sorted sets (ZSETs)
-        # for efficient time-range queries. Events are bucketed by hour to bound memory
-        # usage and enable automatic expiration via Redis TTLs.
-        #
         # == Storage Structure
         #
-        # Events are stored in hourly buckets as ZSETs:
-        #   stoplight:{version}:{system}:{light}:window_metrics:success:1696154400
-        #   stoplight:{version}:{system}:{light}:window_metrics:failure:1696154400
-        #
-        # Each ZSET member is a unique event ID with its timestamp as the score,
-        # enabling O(log N) range queries via ZCOUNT.
-        #
-        # Metadata (consecutive counters, last error) is stored in a hash:
-        #   stoplight:{version}:{system}:{light}:window_metrics
-        #
-        # == Bucket Strategy
-        #
-        # Fixed 1-hour buckets provide a balance between:
-        # - Query efficiency: At most ~25 buckets for a 24-hour window
-        # - Memory efficiency: Natural expiration without manual cleanup
-        # - Precision: Sub-bucket accuracy via ZSET scores
-        #
-        # == Atomicity
-        #
-        # All operations use Lua scripts to ensure atomicity:
-        # - record_success: Increments counter and updates metadata in one round-trip
-        # - record_failure: Same, plus stores serialized error details
-        # - metrics_snapshot: Aggregates across buckets atomically
+        # Maintains a running sum and stores per-second counts in a redis Hash. Eviction reads
+        # only the out-of-window entries from the sorted set index, subtracts their counts from
+        # the running totals, then deletes both the hash fields and the sorted-set members.
         #
         class WindowMetrics < Metrics
+          METRICS_FIELDS = %w[last_success_at last_error_json consecutive_errors consecutive_successes].freeze
+          private_constant :METRICS_FIELDS
+
           def initialize(redis:, scripting:, config:, clock:, key_space:)
             @clock = clock
-            @scripting = scripting
             @redis = redis
-            @config = config
-            @key_space = key_space
-            @metrics_key = key_space.key(:window_metrics)
-            @window_size = T.must(config.window_size).to_i
+            @scripting = scripting
+            @metrics_key = key_space.join("window_metrics")
+            @ts_index_key = key_space.join("window_metrics", "ts_idx")
+            @window_size = T.must(config.window_size)
           end
 
-          # Get metrics for the current light
-          #
-          # @return [Stoplight::Domain::Metrics]
           def metrics_snapshot
-            window_end_ts = clock.current_time.to_f
-            window_start_ts = window_end_ts - @window_size
-            failure_keys = failure_bucket_keys(window_end_ts)
-            success_keys = success_bucket_keys(window_end_ts)
-
-            successes, errors, last_success_at, last_error_json, consecutive_errors, consecutive_successes = scripting.call(
-              :"window_metrics/metrics_snapshot",
-              args: [
-                failure_keys.count,
-                window_start_ts,
-                window_end_ts,
-                "last_success_at", "last_error_json", "consecutive_errors", "consecutive_successes"
-              ],
-              keys: [
-                metrics_key,
-                *success_keys,
-                *failure_keys
-              ]
-            )
-            Domain::MetricsSnapshot.new(
-              successes:, errors:,
-              consecutive_errors: [consecutive_errors.to_i, errors].min,
-              consecutive_successes: [consecutive_successes.to_i, successes].min,
-              last_error: deserialize_failure(last_error_json),
-              last_success_at: (clock.at(last_success_at.to_f) if last_success_at)
-            )
+            successes, errors, last_success_at, last_error_json, consecutive_errors, consecutive_successes =
+              @scripting.call(
+                "window_metrics/metrics_snapshot",
+                args: [@window_size, *METRICS_FIELDS],
+                keys: [@metrics_key, @ts_index_key]
+              )
+
+            build_metrics_snapshot(successes:, errors:, consecutive_errors:, consecutive_successes:,
+              last_error_json:, last_success_at:)
           end
 
-          # Records successful circuit breaker execution
-          #
-          # @return [void]
           def record_success
-            timestamp = clock.current_time.to_f
-
-            scripting.call(
-              :"window_metrics/record_success",
-              args: [timestamp, SecureRandom.hex(12), bucket_ttl, metrics_ttl],
-              keys: [
-                metrics_key,
-                successes_key(time: timestamp)
-              ]
+            @scripting.call(
+              "window_metrics/record_success",
+              args: [@window_size, metrics_ttl],
+              keys: [@metrics_key, @ts_index_key]
             )
           end
 
-          # Records failed circuit breaker execution
-          #
-          # @param exception [StandardError]
-          # @return [void]
           def record_failure(exception)
-            timestamp = clock.current_time.to_f
-
-            scripting.call(
-              :"window_metrics/record_failure",
-              args: [timestamp, SecureRandom.hex(12), serialize_exception(exception, timestamp:), bucket_ttl, metrics_ttl],
-              keys: [metrics_key, errors_key(time: timestamp)]
-            )
-          end
-
-          def clear
-            window_end_ts = clock.current_time.to_f
-            failure_keys = failure_bucket_keys(window_end_ts)
-            success_keys = success_bucket_keys(window_end_ts)
+            timestamp = @clock.current_time.to_f
 
-            redis.with do |client|
-              client.del(metrics_key, *failure_keys, *success_keys)
-            end
-          end
+            successes, errors, last_success_at, last_error_json, consecutive_errors, consecutive_successes =
+              @scripting.call(
+                "window_metrics/record_failure",
+                args: [serialize_exception(exception, timestamp:), @window_size, metrics_ttl],
+                keys: [@metrics_key, @ts_index_key]
+              )
 
-          # Generates a Redis key for a specific metric and time.
-          #
-          # @param metric [Symbol] The metric type (e.g., "errors").
-          # @param time [Time, Numeric] The time for which to generate the key.
-          # @return [String] The generated Redis key.
-          def bucket_key(metric:, time:)
-            key_space.key(:window_metrics, metric, (time.to_i / bucket_size) * bucket_size)
+            build_metrics_snapshot(successes:, errors:, consecutive_errors:, consecutive_successes:,
+              last_error_json:, last_success_at:)
           end
 
-          # Retrieves the list of Redis bucket keys required to cover a specific time window.
-          #
-          # @param metric The metric type (e.g., "errors").
-          # @param window_end  The end time of the window (can be a Time object or a numeric timestamp).
-          # @return A list of Redis keys for the buckets that cover the time window.
-          # @api private
-          def buckets_for_window(metric:, window_end:)
-            window_end_ts = window_end.to_i
-            window_start_ts = window_end_ts - @window_size
-
-            # Find bucket timestamps that contain any part of the window
-            start_bucket = (window_start_ts / bucket_size) * bucket_size
-
-            # End bucket is the last bucket that contains data within our window
-            end_bucket = ((window_end_ts - 1) / bucket_size) * bucket_size
-
-            (start_bucket..end_bucket).step(bucket_size).map do |bucket_start|
-              bucket_key(metric: metric, time: bucket_start)
+          def clear
+            @redis.with do |client|
+              client.del(@metrics_key, @ts_index_key)
             end
           end
 
           private
 
-          attr_reader :redis
-          attr_reader :scripting
-          attr_reader :metrics_key
-          attr_reader :clock
-          attr_reader :key_space
-
-          def bucket_size = 3600 # 1 hour
-          def bucket_ttl = @window_size + bucket_size
-
-          def successes_key(time:) = bucket_key(metric: :success, time:)
-
-          def errors_key(time:) = bucket_key(metric: :failure, time:)
-
-          def failure_bucket_keys(window_end) = buckets_for_window(metric: :failure, window_end:)
-
-          def success_bucket_keys(window_end) = buckets_for_window(metric: :success, window_end:)
+          def build_metrics_snapshot(successes:, errors:, consecutive_errors:, consecutive_successes:,
+            last_error_json:, last_success_at:)
+            Domain::MetricsSnapshot.new(
+              successes:, errors:,
+              consecutive_errors: [consecutive_errors.to_i, errors].min,
+              consecutive_successes: [consecutive_successes.to_i, successes].min,
+              last_error: deserialize_failure(last_error_json),
+              last_success_at: (@clock.at(last_success_at.to_f) if last_success_at)
+            )
+          end
         end
       end
     end

data/lib/stoplight/infrastructure/system_clock.rb

@@ -10,6 +10,10 @@ module Stoplight
     class SystemClock
       def current_time = Time.now.utc
 
+      def monotonic_millis = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+
+      def monotonic_seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second)
+
       def at(timestamp) = Time.at(timestamp).utc
     end
   end

data/lib/stoplight/telemetry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stoplight
+  # Public face of the telemetry bus. The bus and its events live in the domain layer
+  # (+Domain::Telemetry+); this namespace re-exports them so callers never reference the
+  # +Domain::+ boundary - mirroring +Stoplight::Notifier+ and +Stoplight::DataStore+.
+  module Telemetry
+    RunCompleted = Domain::Telemetry::RunCompleted
+    TrafficBreached = Domain::Telemetry::TrafficBreached
+    RecoveryStarted = Domain::Telemetry::RecoveryStarted
+    RecoverySucceeded = Domain::Telemetry::RecoverySucceeded
+    RecoveryFailed = Domain::Telemetry::RecoveryFailed
+    LockChanged = Domain::Telemetry::LockChanged
+    RecoveryProbeCompleted = Domain::Telemetry::RecoveryProbeCompleted
+    LightRegistered = Domain::Telemetry::LightRegistered
+
+    StateTransitioned = Domain::Telemetry::StateTransitioned
+  end
+end

data/lib/stoplight/types.rb

@@ -4,7 +4,19 @@ require "singleton"
 
 module Stoplight
   module Types
-    def self.undefined = Undefined.instance
+    UNDEFINED = Undefined.instance
+    def self.undefined = UNDEFINED
+
+    def self.absurd(value = nil)
+      msg = "Control flow reached T.absurd."
+
+      case value
+      when Kernel
+        msg += " Got value: #{value}"
+      end
+
+      TypeError.new(msg)
+    end
 
     # Asserts a value is non-nil, returning it with a narrowed type.
     #
@@ -19,7 +31,8 @@ module Stoplight
     # @return [T] the non-nil value
     #
     def self.must(value)
-      if value.nil?
+      case value
+      when nil
         raise TypeError, "must not have nil value"
       else
         value

data/lib/stoplight/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stoplight
-  VERSION = Gem::Version.new("5.8.3")
+  VERSION = Gem::Version.new("6.0.0.rc2")
 end

data/lib/stoplight/wiring/config_compatibility_validator.rb

@@ -23,18 +23,41 @@ module Stoplight
       end
 
       def call
+        validate_window_size!
+        validate_cool_off_time!
         validate_traffic_control!
         validate_traffic_recovery!
         config
       end
 
+      # A window shorter than one bucket cannot be measured, and a fractional one silently
+      # rounds to a different span than requested.
+      private def validate_window_size!
+        window_size = config.window_size
+        return if window_size.nil?
+        return if window_size.is_a?(Integer) && window_size >= 1
+
+        raise Error::ConfigurationError,
+          "`window_size` should be a whole number of seconds, at least 1, got #{window_size.inspect}",
+          ExternalCaller.backtrace
+      end
+
+      private def validate_cool_off_time!
+        cool_off_time = config.cool_off_time
+        return if cool_off_time.is_a?(Integer) && cool_off_time >= 1
+
+        raise Error::ConfigurationError,
+          "`cool_off_time` should be a whole number of seconds, at least 1, got #{cool_off_time.inspect}",
+          ExternalCaller.backtrace
+      end
+
       private def validate_traffic_control!
         traffic_control = config.traffic_control
         traffic_control.check_compatibility(config).then do |compatibility_result|
           if compatibility_result.incompatible?
             raise Error::ConfigurationError,
               "#{traffic_control} incompatible with config: #{compatibility_result.error_messages}",
-              caller(8)
+              ExternalCaller.backtrace
           end
         end
       end
@@ -45,7 +68,7 @@ module Stoplight
           if compatibility_result.incompatible?
             raise Error::ConfigurationError,
               "#{traffic_recovery} incompatible with config: #{compatibility_result.error_messages}",
-              caller(8)
+              ExternalCaller.backtrace
           end
         end
       end

data/lib/stoplight/wiring/default.rb

@@ -3,7 +3,7 @@
 module Stoplight
   module Wiring
     module Default
-      COOL_OFF_TIME = 60.0
+      COOL_OFF_TIME = 60
 
       DATA_STORE = Stoplight::DataStore::Memory.new
 

data/lib/stoplight/wiring/default_config.rb

@@ -4,7 +4,8 @@ module Stoplight
   module Wiring
     # Provides default settings for the Stoplight library.
     DefaultConfig = Domain::Config.new(
-      name: "DEFAULT_CONFIG",
+      id: Domain::Id.for("Default"),
+      name: "Default",
       cool_off_time: Default::COOL_OFF_TIME,
       threshold: Default::THRESHOLD,
       recovery_threshold: Default::RECOVERY_THRESHOLD,

data/lib/stoplight/wiring/default_configuration.rb

@@ -46,7 +46,7 @@ module Stoplight
     #
     class DefaultConfiguration
       def initialize
-        @config = DefaultConfig.with
+        @config = DefaultConfig
         @cool_off_time = T.undefined
         @threshold = T.undefined
         @recovery_threshold = T.undefined
@@ -76,7 +76,8 @@ module Stoplight
 
       # Builds and validates configuration
       def to_config!
-        ConfigurationDsl.new(
+        SystemConfigurationDsl.new(
+          "Default",
           cool_off_time: @cool_off_time,
           threshold: @threshold,
           recovery_threshold: @recovery_threshold,

data/lib/stoplight/wiring/external_caller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Locates the application code that called into Stoplight, so configuration errors point at
+    # the light's call site instead of Stoplight's own internals.
+    #
+    # @api private
+    module ExternalCaller
+      LIB_ROOT = "#{File.expand_path("../../..", __FILE__)}/"
+
+      class << self
+        def backtrace
+          frames = caller_locations(1) || []
+          external = frames.reject { |frame| internal?(frame) }
+          external = frames if external.empty?
+          external.map(&:to_s)
+        end
+
+        private def internal?(frame)
+          path = frame.path.to_s
+          path.start_with?(LIB_ROOT, "<internal:")
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/fail_safe_config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Empty notifiers prevent notification loops; inherited Memory data store prevents infinite recursion if Redis is down.
+    FailSafeConfig = DefaultConfig.with(
+      notifiers: [],
+      data_store: DataStore::Memory.new
+    )
+  end
+end

data/lib/stoplight/wiring/global_state.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class GlobalState
+      attr_reader :default_system
+      attr_reader :default_config
+
+      def initialize(default_config:)
+        @default_config = default_config
+        @systems = Concurrent::Map.new
+        @default_system = register_system_with_config(@default_config)
+      end
+
+      def register_system(
+        name,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        tracked_errors: T.undefined,
+        skipped_errors: T.undefined,
+        data_store: T.undefined,
+        error_notifier: T.undefined,
+        notifiers: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined
+      )
+        register_system_with_config(
+          Wiring::SystemConfigurationDsl.new(
+            name,
+            cool_off_time:,
+            threshold:,
+            recovery_threshold:,
+            window_size:,
+            tracked_errors:,
+            skipped_errors:,
+            traffic_control:,
+            traffic_recovery:,
+            data_store:,
+            error_notifier:,
+            notifiers:
+          ).configure!(@default_config)
+        )
+      end
+
+      private
+
+      def register_system_with_config(config)
+        @systems.compute(config.name) do |existing_system|
+          if existing_system
+            raise ArgumentError, "system `#{config.name}` is already in use"
+          else
+            failover_system = Wiring::System.new(
+              config: Wiring::FailSafeConfig.with(
+                name: "__stoplight__:failover:#{config.name}",
+                data_store: DataStore::Memory.new
+              ),
+              failover_system: nil,
+              registry: Infrastructure::Memory::Storage::Registry.new
+            )
+            Wiring::System.new(
+              config: config,
+              failover_system: failover_system,
+              registry: create_registry(config, failover_system)
+            )
+          end
+        end
+      end
+
+      def create_registry(config, failover_system)
+        case config.data_store
+        when DataStore::Redis
+          Infrastructure::FailSafe::Storage::Registry.new(
+            primary_registry: Infrastructure::Redis::Storage::Registry.new(
+              redis: config.data_store.redis,
+              key_space: config.data_store.key_space.join(config.id),
+              clock: Infrastructure::SystemClock.new,
+              config_serializer: Infrastructure::ConfigSerializer
+            ),
+            error_notifier: config.error_notifier,
+            failover_registry: Infrastructure::Memory::Storage::Registry.new,
+            circuit_breaker: failover_system.register("registry")
+          )
+        when DataStore::Memory
+          Infrastructure::Memory::Storage::Registry.new
+        else
+          raise TypeError, "unsupported data store type"
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/{light_factory → light_configuration_dsl}/traffic_control_dsl.rb

@@ -2,17 +2,15 @@
 
 module Stoplight
   module Wiring
-    class LightFactory
+    class LightConfigurationDsl
       TrafficControlDsl = ->(value) {
         case value
         in _ if value.respond_to?(:stop_traffic?) # TODO: can be removed in 6.0
           value
-        in :consecutive_errors
+        in Domain::TrafficControl::ConsecutiveErrors::NAME
           Domain::TrafficControl::ConsecutiveErrors.new
-        in :error_rate
+        in Domain::TrafficControl::ErrorRate::NAME
           Domain::TrafficControl::ErrorRate.new
-        in {error_rate: error_rate_settings}
-          Domain::TrafficControl::ErrorRate.new(**error_rate_settings)
         else
           raise Stoplight::Error::ConfigurationError, <<~ERROR
             unsupported traffic_control strategy provided (`#{value}`). Supported options:

data/lib/stoplight/wiring/{light_factory → light_configuration_dsl}/traffic_recovery_dsl.rb

@@ -2,12 +2,12 @@
 
 module Stoplight
   module Wiring
-    class LightFactory
+    class LightConfigurationDsl
       TrafficRecoveryDsl = ->(value) {
         case value
         in _ if value.respond_to?(:determine_color) # TODO: remove in 6.0
           value
-        in :consecutive_successes
+        in Domain::TrafficRecovery::ConsecutiveSuccesses::NAME
           Domain::TrafficRecovery::ConsecutiveSuccesses.new
         else
           raise Error::ConfigurationError, <<~ERROR

data/lib/stoplight/wiring/light_configuration_dsl.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class LightConfigurationDsl
+      def initialize(
+        name:,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        tracked_errors: T.undefined,
+        skipped_errors: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined
+      )
+        @name = name.to_s
+        @id = Domain::Id.for(@name)
+        @cool_off_time = cool_off_time
+        @threshold = threshold
+        @recovery_threshold = recovery_threshold
+        @window_size = window_size
+        @tracked_errors = if tracked_errors.is_a?(Undefined)
+          tracked_errors
+        elsif tracked_errors.is_a?(Array)
+          tracked_errors
+        else
+          [tracked_errors]
+        end
+        @skipped_errors = if skipped_errors.is_a?(Undefined)
+          skipped_errors
+        elsif skipped_errors.is_a?(Array)
+          skipped_errors
+        else
+          [skipped_errors]
+        end
+        @traffic_control = traffic_control.is_a?(Undefined) ? traffic_control : TrafficControlDsl.call(traffic_control)
+        @traffic_recovery = traffic_recovery.is_a?(Undefined) ? traffic_recovery : TrafficRecoveryDsl.call(traffic_recovery)
+
+        @digest = calculate_digest
+      end
+
+      def configure!(default_config)
+        ConfigCompatibilityValidator.call(
+          config: default_config.with(
+            id: @id,
+            name:,
+            cool_off_time:,
+            threshold:,
+            recovery_threshold:,
+            window_size:,
+            tracked_errors:,
+            skipped_errors:,
+            traffic_control:,
+            traffic_recovery:
+          )
+        )
+      end
+
+      attr_reader :digest
+
+      private
+
+      def calculate_digest
+        [
+          @id,
+          @cool_off_time,
+          @threshold,
+          @recovery_threshold,
+          @window_size,
+          errors_for_digest(@tracked_errors),
+          errors_for_digest(@skipped_errors),
+          @traffic_control,
+          @traffic_recovery
+        ].hash
+      end
+
+      attr_reader :name
+      attr_reader :cool_off_time
+      attr_reader :threshold
+      attr_reader :recovery_threshold
+      attr_reader :window_size
+      attr_reader :tracked_errors
+      attr_reader :skipped_errors
+      attr_reader :traffic_control
+      attr_reader :traffic_recovery
+
+      def errors_for_digest(errors)
+        if errors.is_a?(Undefined)
+          errors
+        else
+          errors.map { |matcher| Domain::MatcherValidator.call(matcher) }
+        end
+      end
+    end
+  end
+end