stoplight 4.1.0 → 5.0.1

data/lib/stoplight/data_store/memory.rb

@@ -1,93 +1,300 @@
 # frozen_string_literal: true
 
-require 'monitor'
+require "monitor"
 
 module Stoplight
   module DataStore
     # @see Base
     class Memory < Base
       include MonitorMixin
-      KEY_SEPARATOR = ':'
+      KEY_SEPARATOR = ":"
 
       def initialize
-        @failures = Hash.new { |h, k| h[k] = [] }
-        @states = Hash.new { |h, k| h[k] = State::UNLOCKED }
-        @last_notifications = {}
-        super() # MonitorMixin
+        @errors = Hash.new { |h, k| h[k] = [] }
+        @successes = Hash.new { |h, k| h[k] = [] }
+
+        @recovery_probe_errors = Hash.new { |h, k| h[k] = [] }
+        @recovery_probe_successes = Hash.new { |h, k| h[k] = [] }
+
+        @metadata = Hash.new { |h, k| h[k] = Metadata.new }
+        super # MonitorMixin
       end
 
+      # @return [Array<String>]
       def names
-        synchronize { @failures.keys | @states.keys }
+        synchronize { @metadata.keys }
       end
 
-      def get_all(light)
-        synchronize { [query_failures(light), @states[light.name]] }
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Metadata]
+      def get_metadata(config)
+        light_name = config.name
+        window_end = Time.now
+        recovery_window = (window_end - config.cool_off_time + 1)..window_end
+
+        synchronize do
+          recovered_at = @metadata[light_name].recovered_at
+          window = if config.window_size
+            window_start = [recovered_at, (window_end - config.window_size + 1)].compact.max
+            (window_start..window_end)
+          else
+            (..window_end)
+          end
+
+          errors = @errors[config.name].count do |request_time|
+            window.cover?(request_time)
+          end
+
+          successes = @successes[config.name].count do |request_time|
+            window.cover?(request_time)
+          end
+
+          recovery_probe_errors = @recovery_probe_errors[config.name].count do |request_time|
+            recovery_window.cover?(request_time)
+          end
+          recovery_probe_successes = @recovery_probe_successes[config.name].count do |request_time|
+            recovery_window.cover?(request_time)
+          end
+
+          @metadata[light_name].with(
+            errors:,
+            successes:,
+            recovery_probe_errors:,
+            recovery_probe_successes:
+          )
+        end
       end
 
-      def get_failures(light)
-        synchronize { query_failures(light) }
+      # @param metrics [<Time>]
+      # @param window_size [Numeric, nil]
+      # @return [void]
+      def cleanup(metrics, window_size:)
+        min_age = Time.now - [window_size&.*(3), METRICS_RETENTION_TIME].compact.min
+
+        metrics.reject! { _1 < min_age }
       end
 
-      def record_failure(light, failure)
+      # @param config [Stoplight::Light::Config]
+      # @param failure [Stoplight::Failure]
+      # @return [Stoplight::Metadata]
+      def record_failure(config, failure)
+        light_name = config.name
+
         synchronize do
-          light_name = light.name
-
-          # Keep at most +light.threshold+ number of errors
-          @failures[light_name] = @failures[light_name].first(light.threshold - 1)
-          @failures[light_name].unshift(failure)
-          # Remove all errors happened before the window start
-          @failures[light_name] = query_failures(light, failure.time)
-          @failures[light_name].size
+          @errors[light_name].unshift(failure.time) if config.window_size
+
+          cleanup(@errors[light_name], window_size: config.window_size)
+
+          metadata = @metadata[light_name]
+          @metadata[light_name] = if metadata.last_error_at.nil? || failure.time > metadata.last_error_at
+            metadata.with(
+              last_error_at: failure.time,
+              last_error: failure,
+              consecutive_errors: metadata.consecutive_errors.succ,
+              consecutive_successes: 0
+            )
+          else
+            metadata.with(
+              consecutive_errors: metadata.consecutive_errors.succ,
+              consecutive_successes: 0
+            )
+          end
+          get_metadata(config)
         end
       end
 
-      def clear_failures(light)
-        synchronize { @failures.delete(light.name) }
-      end
+      # @param config [Stoplight::Light::Config]
+      # @param request_id [String]
+      # @param request_time [Time]
+      # @return [void]
+      def record_success(config, request_time: Time.now, request_id: SecureRandom.hex(12))
+        light_name = config.name
 
-      def get_state(light)
-        synchronize { @states[light.name] }
-      end
+        synchronize do
+          @successes[light_name].unshift(request_time) if config.window_size
+          cleanup(@successes[light_name], window_size: config.window_size)
 
-      def set_state(light, state)
-        synchronize { @states[light.name] = state }
+          metadata = @metadata[light_name]
+          @metadata[light_name] = if metadata.last_success_at.nil? || request_time > metadata.last_success_at
+            metadata.with(
+              last_success_at: request_time,
+              consecutive_errors: 0,
+              consecutive_successes: metadata.consecutive_successes.succ
+            )
+          else
+            metadata.with(
+              consecutive_errors: 0,
+              consecutive_successes: metadata.consecutive_successes.succ
+            )
+          end
+        end
       end
 
-      def clear_state(light)
-        synchronize { @states.delete(light.name) }
+      # @param config [Stoplight::Light::Config]
+      # @param failure [Stoplight::Failure]
+      # @return [Stoplight::Metadata]
+      def record_recovery_probe_failure(config, failure)
+        light_name = config.name
+
+        synchronize do
+          @recovery_probe_errors[light_name].unshift(failure.time)
+          cleanup(@recovery_probe_errors[light_name], window_size: config.cool_off_time)
+
+          metadata = @metadata[light_name]
+          @metadata[light_name] = if metadata.last_error_at.nil? || failure.time > metadata.last_error_at
+            metadata.with(
+              last_error_at: failure.time,
+              last_error: failure,
+              consecutive_errors: metadata.consecutive_errors.succ,
+              consecutive_successes: 0
+            )
+          else
+            metadata.with(
+              consecutive_errors: metadata.consecutive_errors.succ,
+              consecutive_successes: 0
+            )
+          end
+          get_metadata(config)
+        end
       end
 
-      def with_notification_lock(light, from_color, to_color)
+      # @param config [Stoplight::Light::Config]
+      # @param request_id [String]
+      # @param request_time [Time]
+      # @return [Stoplight::Metadata]
+      def record_recovery_probe_success(config, request_time: Time.now, request_id: SecureRandom.hex(12))
+        light_name = config.name
+
         synchronize do
-          if last_notification(light) != [from_color, to_color]
-            set_last_notification(light, from_color, to_color)
+          @recovery_probe_successes[light_name].unshift(request_time)
+          cleanup(@recovery_probe_successes[light_name], window_size: config.cool_off_time)
 
-            yield
+          metadata = @metadata[light_name]
+          recovery_started_at = metadata.recovery_started_at || request_time
+          @metadata[light_name] = if metadata.last_success_at.nil? || request_time > metadata.last_success_at
+            metadata.with(
+              last_success_at: request_time,
+              recovery_started_at:,
+              consecutive_errors: 0,
+              consecutive_successes: metadata.consecutive_successes.succ
+            )
+          else
+            metadata.with(
+              recovery_started_at:,
+              consecutive_errors: 0,
+              consecutive_successes: metadata.consecutive_successes.succ
+            )
           end
+          get_metadata(config)
         end
       end
 
-      private
+      # @param config [Stoplight::Light::Config]
+      # @param state [String]
+      # @return [String]
+      def set_state(config, state)
+        light_name = config.name
 
-      # @param light [Stoplight::Light]
-      # @return [Array, nil]
-      def last_notification(light)
-        @last_notifications[light.name]
+        synchronize do
+          metadata = @metadata[light_name]
+          @metadata[light_name] = metadata.with(locked_state: state)
+        end
+        state
       end
 
-      # @param light [Stoplight::Light]
-      # @param from_color [String]
-      # @param to_color [String]
-      # @return [void]
-      def set_last_notification(light, from_color, to_color)
-        @last_notifications[light.name] = [from_color, to_color]
+      # Combined method that performs the state transition based on color
+      #
+      # @param config [Stoplight::Light::Config] The light configuration
+      # @param color [String] The color to transition to ("GREEN", "YELLOW", or "RED")
+      # @param current_time [Time]
+      # @return [Boolean] true if this is the first instance to detect this transition
+      def transition_to_color(config, color, current_time: Time.now)
+        case color
+        when Color::GREEN
+          transition_to_green(config)
+        when Color::YELLOW
+          transition_to_yellow(config, current_time:)
+        when Color::RED
+          transition_to_red(config, current_time:)
+        else
+          raise ArgumentError, "Invalid color: #{color}"
+        end
       end
 
-      # @param light [Stoplight::Light]
-      # @return [<Stoplight::Failure>]
-      def query_failures(light, time = Time.now)
-        @failures[light.name].select do |failure|
-          failure.time.to_i > time.to_i - light.window_size
+      # Transitions to GREEN state and ensures only one notification
+      #
+      # @param config [Stoplight::Light::Config] The light configuration
+      # @return [Boolean] true if this is the first instance to detect this transition
+      private def transition_to_green(config, current_time: Time.now)
+        light_name = config.name
+
+        synchronize do
+          metadata = @metadata[light_name]
+          if metadata.recovered_at
+            false
+          else
+            @metadata[light_name] = metadata.with(
+              recovered_at: current_time,
+              recovery_started_at: nil,
+              breached_at: nil,
+              recovery_scheduled_after: nil
+            )
+            true
+          end
+        end
+      end
+
+      # Transitions to YELLOW (recovery) state and ensures only one notification
+      #
+      # @param config [Stoplight::Light::Config] The light configuration
+      # @param current_time [Time]
+      # @return [Boolean] true if this is the first instance to detect this transition
+      private def transition_to_yellow(config, current_time: Time.now)
+        light_name = config.name
+
+        synchronize do
+          metadata = @metadata[light_name]
+          if metadata.recovery_started_at
+            false
+          else
+            @metadata[light_name] = metadata.with(
+              recovery_started_at: current_time,
+              recovery_scheduled_after: nil,
+              recovered_at: nil,
+              breached_at: nil
+            )
+            true
+          end
+        end
+      end
+
+      # Transitions to RED state and ensures only one notification
+      #
+      # @param config [Stoplight::Light::Config] The light configuration
+      # @param current_time [Time]
+      # @return [Boolean] true if this is the first instance to detect this transition
+      private def transition_to_red(config, current_time: Time.now)
+        light_name = config.name
+        recovery_scheduled_after = current_time + config.cool_off_time
+
+        synchronize do
+          metadata = @metadata[light_name]
+          if metadata.breached_at
+            @metadata[light_name] = metadata.with(
+              recovery_scheduled_after: recovery_scheduled_after,
+              recovery_started_at: nil,
+              recovered_at: nil
+            )
+            false
+          else
+            @metadata[light_name] = metadata.with(
+              breached_at: current_time,
+              recovery_scheduled_after: recovery_scheduled_after,
+              recovery_started_at: nil,
+              recovered_at: nil
+            )
+            true
+          end
         end
       end
     end

data/lib/stoplight/data_store/redis/get_metadata.lua

@@ -0,0 +1,38 @@
+local number_of_metric_buckets = tonumber(ARGV[1])
+local number_of_recovery_buckets = tonumber(ARGV[2])
+local window_start_ts = tonumber(ARGV[3])
+local window_end_ts = tonumber(ARGV[4])
+local recovery_window_start_ts = tonumber(ARGV[5])
+
+local metadata_key = KEYS[1]
+
+-- It possible that after a successful recovery, Stoplight still see metrics
+-- that are older than the recovery window. To prevent this from happening,
+-- we need to limit the start time of the window to the time of the last recovery.
+local recovered_at = redis.call('HGET', metadata_key, "recovered_at")
+if recovered_at then
+  window_start_ts = math.max(window_start_ts, recovered_at)
+end
+
+local function count_events(start_idx, bucket_count, start_ts)
+  local total = 0
+  for idx = start_idx, start_idx + bucket_count - 1 do
+    total = total + tonumber(redis.call('ZCOUNT', KEYS[idx], start_ts, window_end_ts))
+  end
+  return total
+end
+
+local offset = 2
+local successes = count_events(2, number_of_metric_buckets, window_start_ts)
+
+offset = offset + number_of_metric_buckets
+local errors = count_events(offset, number_of_metric_buckets, window_start_ts)
+
+offset = offset + number_of_metric_buckets
+local recovery_probe_successes = count_events(offset, number_of_recovery_buckets, recovery_window_start_ts)
+
+offset = offset + number_of_recovery_buckets
+local recovery_probe_errors = count_events(offset, number_of_recovery_buckets, recovery_window_start_ts)
+
+local metadata = redis.call('HGETALL',  metadata_key)
+return {successes, errors, recovery_probe_successes, recovery_probe_errors, metadata}

data/lib/stoplight/data_store/redis/lua.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module DataStore
+    class Redis
+      # @api private
+      module Lua
+        class << self
+          def read_lua_file(name_without_extension)
+            File.read(File.join(__dir__, "#{name_without_extension}.lua"))
+          end
+        end
+
+        RECORD_FAILURE = read_lua_file("record_failure")
+        RECORD_SUCCESS = read_lua_file("record_success")
+        GET_METADATA = read_lua_file("get_metadata")
+        TRANSITION_TO_YELLOW = read_lua_file("transition_to_yellow")
+        TRANSITION_TO_RED = read_lua_file("transition_to_red")
+        TRANSITION_TO_GREEN = read_lua_file("transition_to_green")
+      end
+    end
+  end
+end

data/lib/stoplight/data_store/redis/record_failure.lua

@@ -0,0 +1,36 @@
+local failure_ts = tonumber(ARGV[1])
+local failure_id = ARGV[2]
+local failure_json = ARGV[3]
+local bucket_ttl = tonumber(ARGV[4])
+local metadata_ttl = tonumber(ARGV[5])
+
+local metadata_key = KEYS[1]
+local errors_key = KEYS[2]
+
+-- Record failure
+if errors_key ~= nil then
+  redis.call('ZADD', errors_key, failure_ts, failure_id)
+  redis.call('EXPIRE', errors_key, bucket_ttl) -- Not supported in Redis 6.2:, 'NX')
+end
+
+-- Update metadata
+local meta = redis.call('HMGET', metadata_key, 'last_error_at', 'consecutive_errors')
+local prev_failure_ts = tonumber(meta[1])
+local prev_consecutive_errors = tonumber(meta[2])
+
+if not prev_failure_ts or failure_ts > prev_failure_ts then
+  redis.call(
+    'HSET', metadata_key,
+    'last_error_at', failure_ts,
+    'last_error_json', failure_json,
+    'consecutive_errors', (prev_consecutive_errors or 0) + 1,
+    'consecutive_successes', 0
+  )
+else
+  redis.call(
+    'HSET', metadata_key,
+    'consecutive_errors', (prev_consecutive_errors or 0) + 1,
+    'consecutive_successes', 0
+  )
+end
+redis.call('EXPIRE', metadata_key, metadata_ttl) -- Not supported in Redis 6.2:, 'GT')

data/lib/stoplight/data_store/redis/record_success.lua

@@ -0,0 +1,35 @@
+local request_ts = tonumber(ARGV[1])
+local request_id = ARGV[2]
+local bucket_ttl = tonumber(ARGV[3])
+local metadata_ttl = tonumber(ARGV[4])
+
+local metadata_key = KEYS[1]
+local successes_key = KEYS[2]
+
+-- Record success
+if successes_key ~= nil then
+  redis.call('ZADD', successes_key, request_ts, request_id)
+  redis.call('EXPIRE', successes_key, bucket_ttl) -- Not supported in Redis 6.2:, 'NX')
+end
+
+-- Update metadata
+local meta = redis.call('HMGET', metadata_key, 'last_success_at', 'consecutive_successes')
+local prev_success_ts = tonumber(meta[1])
+local prev_consecutive_successes = tonumber(meta[2])
+
+if not prev_success_ts or request_ts > prev_success_ts then
+  redis.call(
+    'HSET', metadata_key,
+    'last_success_at', request_ts,
+    'consecutive_errors', 0,
+    'consecutive_successes', (prev_consecutive_successes or 0) + 1
+  )
+else
+  redis.call(
+    'HSET', metadata_key,
+    'consecutive_errors', 0,
+    'consecutive_successes', (prev_consecutive_successes or 0) + 1
+  )
+end
+
+redis.call('EXPIRE', metadata_key, metadata_ttl) -- Not supported in Redis 6.2:, 'GT')

data/lib/stoplight/data_store/redis/transition_to_green.lua

@@ -0,0 +1,10 @@
+local meta_key = KEYS[1]
+local current_ts = tonumber(ARGV[1])
+
+--  1 if the field is a new field in the hash and the value was set
+local became_green = redis.call('HSETNX', meta_key, 'recovered_at', current_ts)
+
+if became_green == 1 then
+  redis.call("HDEL", meta_key, 'recovery_started_at', 'recovery_scheduled_after', 'breached_at')
+end
+return became_green

data/lib/stoplight/data_store/redis/transition_to_red.lua

@@ -0,0 +1,10 @@
+local meta_key = KEYS[1]
+local current_ts = tonumber(ARGV[1])
+local recovery_scheduled_after_ts = tonumber(ARGV[2])
+
+--  1 if the field is a new field in the hash and the value was set
+local became_red = redis.call('HSETNX', meta_key, 'breached_at', current_ts)
+
+redis.call('HSET', meta_key, 'recovery_scheduled_after', recovery_scheduled_after_ts)
+redis.call("HDEL", meta_key, "recovery_started_at", "recovered_at")
+return became_red

data/lib/stoplight/data_store/redis/transition_to_yellow.lua

@@ -0,0 +1,9 @@
+local meta_key = KEYS[1]
+local current_ts = tonumber(ARGV[1])
+
+-- HSETNX returns 1 if field is new and was set, 0 if field already exists
+local became_yellow = redis.call('HSETNX', meta_key, 'recovery_started_at', current_ts)
+if became_yellow == 1 then
+  redis.call('HDEL', meta_key, 'recovery_scheduled_after', 'breached_at', 'recovered_at')
+end
+return became_yellow