stoplight 5.3.8 → 5.7.0

data/lib/stoplight/infrastructure/data_store/memory.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      # @see +Domain::DataStore+
+      class Memory < Domain::DataStore
+        include MonitorMixin
+
+        KEY_SEPARATOR = ":"
+
+        # @!attribute recovery_lock_store
+        #   @return [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockStore]
+        #   @api private
+        private attr_reader :recovery_lock_store
+
+        # @param recovery_lock_store [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockStore]
+        def initialize(recovery_lock_store:)
+          @recovery_lock_store = recovery_lock_store
+          @errors = Hash.new { |errors, light_name| errors[light_name] = SlidingWindow.new }
+          @successes = Hash.new { |successes, light_name| successes[light_name] = SlidingWindow.new }
+          @metrics = Hash.new { |metrics, light_name| metrics[light_name] = Metrics.new }
+
+          @recovery_metrics = Hash.new { |metrics, light_name| metrics[light_name] = Metrics.new }
+
+          @states = Hash.new { |states, light_name| states[light_name] = State.new }
+
+          super() # MonitorMixin
+        end
+
+        # @return [Array<String>]
+        def names
+          synchronize { @metrics.keys | @states.keys | @recovery_metrics.keys }
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Domain::Metrics]
+        def get_metrics(config)
+          light_name = config.name
+
+          synchronize do
+            current_time = self.current_time
+            window_start = if config.window_size
+              (current_time - config.window_size)
+            else
+              current_time
+            end
+
+            metrics = @metrics[light_name]
+
+            errors = @errors[light_name].sum_in_window(window_start) if config.window_size
+            successes = @successes[light_name].sum_in_window(window_start) if config.window_size
+            consecutive_errors = config.window_size ? [metrics.consecutive_errors, errors].min : metrics.consecutive_errors
+            consecutive_successes = config.window_size ? [metrics.consecutive_successes.to_i, successes].min : metrics.consecutive_successes.to_i
+
+            Domain::Metrics.new(
+              errors:,
+              successes:,
+              consecutive_errors:,
+              consecutive_successes:,
+              last_error: metrics.last_error,
+              last_success_at: metrics.last_success_at
+            )
+          end
+        end
+
+        # @return [Stoplight::Domain::Metrics]
+        def get_recovery_metrics(config)
+          light_name = config.name
+
+          synchronize do
+            metrics = @recovery_metrics[light_name]
+
+            Domain::Metrics.new(
+              errors: nil, successes: nil,
+              consecutive_errors: metrics.consecutive_errors,
+              consecutive_successes: metrics.consecutive_successes,
+              last_error: metrics.last_error,
+              last_success_at: metrics.last_success_at
+            )
+          end
+        end
+
+        # @return [Stoplight::Domain::StateSnapshot]
+        def get_state_snapshot(config)
+          time, state = synchronize do
+            [current_time, @states[config.name]]
+          end
+
+          Domain::StateSnapshot.new(
+            time:,
+            locked_state: state.locked_state,
+            recovery_scheduled_after: state.recovery_scheduled_after,
+            recovery_started_at: state.recovery_started_at,
+            breached_at: state.breached_at
+          )
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @param exception [Exception]
+        # @return [void]
+        def record_failure(config, exception)
+          current_time = self.current_time
+          light_name = config.name
+          failure = Domain::Failure.from_error(exception, time: current_time)
+
+          synchronize do
+            @errors[light_name].increment if config.window_size
+
+            metrics = @metrics[light_name]
+
+            if metrics.last_error_at.nil? || failure.occurred_at > metrics.last_error_at
+              metrics.last_error = failure
+            end
+
+            metrics.consecutive_errors += 1
+            metrics.consecutive_successes = 0
+          end
+        end
+
+        def clear_metrics(config)
+          light_name = config.name
+          synchronize do
+            if config.window_size
+              @errors[light_name] = SlidingWindow.new
+              @successes[light_name] = SlidingWindow.new
+            end
+            @metrics[light_name] = Metrics.new
+          end
+        end
+
+        def clear_recovery_metrics(config)
+          synchronize do
+            @recovery_metrics[config.name] = Metrics.new
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [void]
+        def record_success(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            @successes[light_name].increment if config.window_size
+
+            metrics = @metrics[light_name]
+
+            if metrics.last_success_at.nil? || current_time > metrics.last_success_at
+              metrics.last_success_at = current_time
+            end
+
+            metrics.consecutive_errors = 0
+            metrics.consecutive_successes += 1
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @param exception [Exception]
+        # @return [void]
+        def record_recovery_probe_failure(config, exception)
+          light_name = config.name
+          current_time = self.current_time
+          failure = Domain::Failure.from_error(exception, time: current_time)
+
+          synchronize do
+            metrics = @recovery_metrics[light_name]
+
+            if metrics.last_error_at.nil? || failure.occurred_at > metrics.last_error_at
+              metrics.last_error = failure
+            end
+
+            metrics.consecutive_errors += 1
+            metrics.consecutive_successes = 0
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [void]
+        def record_recovery_probe_success(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            metrics = @recovery_metrics[light_name]
+            if metrics.last_success_at.nil? || current_time > metrics.last_success_at
+              metrics.last_success_at = current_time
+            end
+
+            metrics.consecutive_errors = 0
+            metrics.consecutive_successes += 1
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @param state [String]
+        # @return [String]
+        def set_state(config, state)
+          light_name = config.name
+
+          synchronize do
+            @states[light_name].locked_state = state
+          end
+          state
+        end
+
+        # @return [String]
+        def inspect
+          "#<#{self.class.name}>"
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [void]
+        def delete_light(config)
+          light_name = config.name
+
+          synchronize do
+            @states.delete(light_name)
+            @recovery_metrics.delete(light_name)
+            @metrics.delete(light_name)
+            @errors.delete(light_name)
+            @successes.delete(light_name)
+          end
+        end
+
+        # Combined method that performs the state transition based on color
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @param color [String] The color to transition to ("GREEN", "YELLOW", or "RED")
+        # @return [Boolean] true if this is the first instance to detect this transition
+        def transition_to_color(config, color)
+          case color
+          when Domain::Color::GREEN
+            transition_to_green(config)
+          when Domain::Color::YELLOW
+            transition_to_yellow(config)
+          when Domain::Color::RED
+            transition_to_red(config)
+          else
+            raise ArgumentError, "Invalid color: #{color}"
+          end
+        end
+
+        # @param config [Stoplight::Domain::Config]
+        # @return [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockToken, nil]
+        def acquire_recovery_lock(config)
+          recovery_lock_store.acquire_lock(config.name)
+        end
+
+        # @param lock [Stoplight::Infrastructure::DataStore::Memory::RecoveryLockToken]
+        # @return [void]
+        def release_recovery_lock(lock)
+          recovery_lock_store.release_lock(lock)
+        end
+
+        # Transitions to GREEN state and ensures only one notification
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @return [Boolean] true if this is the first instance to detect this transition
+        private def transition_to_green(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            state = @states[light_name]
+
+            if state.recovered_at
+              false
+            else
+              state.recovered_at = current_time
+              state.recovery_started_at = nil
+              state.breached_at = nil
+              state.recovery_scheduled_after = nil
+              true
+            end
+          end
+        end
+
+        # Transitions to YELLOW (recovery) state and ensures only one notification
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @return [Boolean] true if this is the first instance to detect this transition
+        private def transition_to_yellow(config)
+          light_name = config.name
+          current_time = self.current_time
+
+          synchronize do
+            state = @states[light_name]
+            if state.recovery_started_at.nil?
+              state.recovery_started_at = current_time
+              state.recovery_scheduled_after = nil
+              state.recovered_at = nil
+              state.breached_at = nil
+              true
+            else
+              state.recovery_scheduled_after = nil
+              state.recovered_at = nil
+              state.breached_at = nil
+              false
+            end
+          end
+        end
+
+        # Transitions to RED state and ensures only one notification
+        #
+        # @param config [Stoplight::Domain::Config] The light configuration
+        # @return [Boolean] true if this is the first instance to detect this transition
+        private def transition_to_red(config)
+          light_name = config.name
+          current_time = self.current_time
+          recovery_scheduled_after = current_time + config.cool_off_time
+
+          synchronize do
+            state = @states[light_name]
+            if state.breached_at
+              state.recovery_scheduled_after = recovery_scheduled_after
+              state.recovery_started_at = nil
+              state.recovered_at = nil
+              false
+            else
+              state.breached_at = current_time
+              state.recovery_scheduled_after = recovery_scheduled_after
+              state.recovery_started_at = nil
+              state.recovered_at = nil
+              true
+            end
+          end
+        end
+
+        private def current_time
+          Time.now
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/data_store/redis/lua_scripts/get_metrics.lua

@@ -0,0 +1,26 @@
+local number_of_metric_buckets = tonumber(ARGV[1])
+local window_start_ts = tonumber(ARGV[2])
+local window_end_ts = tonumber(ARGV[3])
+local metrics_keys = {}
+for idx = 4, #ARGV do
+  table.insert(metrics_keys, ARGV[idx])
+end
+
+local metadata_key = KEYS[1]
+
+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)
+
+local metrics = redis.call('HMGET',  metadata_key, unpack(metrics_keys))
+return {successes, errors, unpack(metrics)}

data/lib/stoplight/infrastructure/data_store/redis/lua_scripts/record_recovery_probe_failure.lua

@@ -0,0 +1,27 @@
+local failure_ts = tonumber(ARGV[1])
+local failure_json = ARGV[2]
+
+local metadata_key = KEYS[1]
+
+
+-- 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
+

data/lib/stoplight/infrastructure/data_store/redis/lua_scripts/record_recovery_probe_success.lua

@@ -0,0 +1,23 @@
+local request_ts = tonumber(ARGV[1])
+
+local metadata_key = KEYS[1]
+
+-- 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

data/lib/stoplight/infrastructure/data_store/redis/lua_scripts/release_lock.lua

@@ -0,0 +1,6 @@
+local token = ARGV[1]
+local lock_key = KEYS[1]
+
+if redis.call("get", lock_key) == token then
+  return redis.call("del", lock_key)
+end

data/lib/stoplight/infrastructure/data_store/redis/recovery_lock_store.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "forwardable"
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      class Redis
+        # Distributed recovery recovery_lock using Redis SET NX (set-if-not-exists).
+        #
+        # Lock Acquisition:
+        # - Uses unique UUID token to prevent accidental release of others' locks
+        # - Atomic SET with NX flag ensures only one process acquires recovery_lock
+        # - TTL (px: lock_timeout) auto-releases recovery_lock if process crashes
+        #
+        # Lock Release:
+        # - Lua script ensures only token holder can release (token comparison)
+        # - Best-effort release; TTL cleanup handles failures
+        #
+        # Failure Modes:
+        # - Lock contention: Returns false, caller should skip probe
+        # - Redis unavailable: raises an error and let caller decide
+        # - Crashed holder: raises an error and let caller decide. Lock auto-expires after lock_timeout
+        # - Release failure: Lock auto-expires after lock_timeout
+        #
+        class RecoveryLockStore
+          # @!attribute redis
+          #   @return [RedisClient]
+          protected attr_reader :redis
+
+          # @!attribute lock_timeout
+          #   @return [Integer]
+          protected attr_reader :lock_timeout
+
+          # @!attribute scripting
+          #   @return [Stoplight::Infrastructure::DataStore::Redis::Scripting]
+          protected attr_reader :scripting
+
+          # @param redis [RedisClient | ConnectionPool]
+          # @param lock_timeout [Integer] recovery_lock timeout in milliseconds
+          # @param scripting [Stoplight::Infrastructure::DataStore::Redis::Scripting]
+          def initialize(redis:, lock_timeout:, scripting:)
+            @redis = redis
+            @lock_timeout = lock_timeout
+            @scripting = scripting
+          end
+
+          # @param light_name [String]
+          # @return [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockToken, nil]
+          def acquire_lock(light_name)
+            recovery_lock = RecoveryLockToken.new(light_name:)
+
+            acquired = !!redis.then do |client|
+              client.set(recovery_lock.lock_key, recovery_lock.token, nx: true, px: lock_timeout)
+            end
+
+            recovery_lock if acquired
+          end
+
+          # @param recovery_lock [Stoplight::Infrastructure::DataStore::Redis::RecoveryLockToken]
+          # @return [void]
+          def release_lock(recovery_lock)
+            scripting.call(
+              :release_lock,
+              keys: [recovery_lock.lock_key], args: [recovery_lock.token]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/data_store/redis/recovery_lock_token.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "forwardable"
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      class Redis
+        class RecoveryLockToken < Domain::RecoveryLockToken
+          extend Forwardable
+
+          def_delegator "Stoplight::Infrastructure::DataStore::Redis", :key
+          private :key
+
+          # @!attribute light_name
+          #   @return [String]
+          attr_reader :light_name
+
+          # @!attribute token
+          #   @return [String]
+          attr_reader :token
+
+          # @param light_name [String]
+          def initialize(light_name:)
+            @light_name = light_name
+            @token = SecureRandom.uuid
+          end
+
+          def lock_key = key(:locks, :recovery, light_name)
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/data_store/redis/scripting.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module DataStore
+      class Redis
+        # Manages Lua scripts for Redis operations.
+        #
+        # This class provides execution of Lua scripts by caching their SHA digests
+        # and automatically reloading scripts if they're evicted from Redis memory.
+        #
+        # @example
+        #   script_manager = ScriptManager.new(redis: redis_client)
+        #   script_manager.call(:increment_counter, keys: ["counter:1"], args: [5])
+        #
+        # @note Scripts are loaded lazily on first use and cached in memory
+        # @note Script files must be named `<script_name>.lua` and located in scripts_root
+        class Scripting
+          SCRIPTS_ROOT = File.join(__dir__, "lua_scripts")
+          # @!attribute scripts_root
+          #   @return [String]
+          protected attr_reader :scripts_root
+
+          # @!attribute shas
+          #   @return [Hash{Symbol, String}]
+          private attr_reader :shas
+
+          # @!attribute redis
+          #   @return [RedisClient | ConnectionPool]
+          protected attr_reader :redis
+
+          # @param redis [RedisClient | ConnectionPool]
+          # @param scripts_root [String]
+          def initialize(redis:, scripts_root: SCRIPTS_ROOT)
+            @scripts_root = scripts_root
+            @redis = redis
+            @shas = {}
+          end
+
+          def call(script_name, keys: [], args: [])
+            redis.then do |client|
+              client.evalsha(script_sha(script_name), keys: keys, argv: args)
+            end
+          rescue ::Redis::CommandError => error
+            if error.message.include?("NOSCRIPT")
+              reload_script(script_name)
+              retry
+            else
+              raise
+            end
+          end
+
+          private def reload_script(script_name)
+            shas.delete(script_name)
+            script_sha(script_name)
+          end
+
+          private def script_sha(script_name)
+            if shas.key?(script_name)
+              shas[script_name]
+            else
+              script = File.read(File.join(scripts_root, "#{script_name}.lua"))
+
+              shas[script_name] = redis.then { |client| client.script("load", script) }
+            end
+          end
+        end
+      end
+    end
+  end
+end