stoplight 5.5.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 297bbf636a9d6fa8e47b2241a3bfe0ccf357954044dc9cd02b79735012d92148
-  data.tar.gz: 7e539fac482dbde352b0e971b20d29968758c85017c2f917859d5130ef8ed7a1
+  metadata.gz: f540f78d771a711da32d2e50cc150c4072cf805e4ef7e52e0b5ea07dd2435fea
+  data.tar.gz: 2b859ca65577026db5e1e5af4bc2900e178edc0e230b1cfc75728ffcadc9efc8
 SHA512:
-  metadata.gz: 53277c7ec692204dc99c96dbf4d8e224d47424b6f5605445de2dc9122d09adedcb683ca783be7f0496db0b6e9aef9045636100da889055e0cb0ee4a4c398ab1e
-  data.tar.gz: f0dd133ab0aa988a9bac5d9b2954299c5cf47ee86f08482b0199c8108fe953ae6e44c5f781457cda74063a93d1686da9ce76b4e4780ffb16d66dd70790b17815
+  metadata.gz: 88eaa1d335e4b956cc354d4c8295e46acd6f4dbb0188cc4cd5ecef99a13c4cf666e09e9c2d4c4f926f2ed0c5a582c9283341de028dc4489645cbde256d805504
+  data.tar.gz: d94325879c511730d6b53b40d13fed577e10119813ec3be5f18f92caccf42d1a886d8c0fe8d6c887ff3d96610f7ac2c53e3d992d25e257cf38fea33795260272

data/README.md

@@ -534,7 +534,7 @@ class ApplicationController < ActionController::Base
 
   def stoplight(&block)
     Stoplight("#{params[:controller]}##{params[:action]}")
-      .run(-> { render(nothing: true, status: :service_unavailable) }, &block)
+      .run(-> (*) { render(nothing: true, status: :service_unavailable) }, &block)
   end
 end
 ```

data/lib/stoplight/admin/actions/remove.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Stoplight
+  class Admin
+    module Actions
+      # This action removes a light's metadata from Redis
+      class Remove < Action
+        # @param params [Hash] query parameters
+        # @return [void]
+        def call(params)
+          light_names(params).each do |name|
+            lights_repository.remove(name)
+          end
+        end
+
+        private def light_names(params)
+          Array(params[:names])
+            .map { |name| CGI.unescape(name) }
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/admin/dependencies.rb

@@ -45,6 +45,11 @@ module Stoplight
       def green_all_action
         Stoplight::Admin::Actions::LockAllGreen.new(lights_repository: lights_repository)
       end
+
+      # @return [Stoplight::Admin::Actions::Remove]
+      def remove_action
+        Stoplight::Admin::Actions::Remove.new(lights_repository: lights_repository)
+      end
     end
   end
 end

data/lib/stoplight/admin/lights_repository.rb

@@ -53,16 +53,25 @@ module Stoplight
         build_light(name).unlock
       end
 
+      # @param name [String] removes light metadata by its name
+      # @return [void]
+      def remove(name)
+        light = build_light(name)
+
+        data_store.delete_light(light.config)
+      end
+
       private def load_light(name)
         light = build_light(name)
         # failures, state
-        metadata = data_store.get_metadata(light.config)
+        state_snapshot = data_store.get_state_snapshot(light.config)
+        metrics = data_store.get_metrics(light.config)
 
         Light.new(
           name: name,
           color: light.color,
-          state: metadata.locked_state,
-          failures: [metadata.last_error].compact
+          state: state_snapshot.locked_state,
+          failures: [metrics.last_error].compact
         )
       end
 

data/lib/stoplight/admin/views/_card.erb

@@ -1,6 +1,6 @@
 <div class="max-w-xl mr-5 p-6 border border-gray-200 rounded-lg shadow-sm dark:bg-gray-800 dark:border-gray-700">
   <div class="flex items-center">
-    <% light_name = ERB::Util.html_escape(light.name) %>
+    <% light_name = CGI.escape(light.name) %>
 
     <div class="relative">
       <div class="relative inline-flex items-center justify-center w-10 h-10 overflow-hidden bg-<%= color %>-100 rounded-full dark:bg-<%= color %>-600">
@@ -83,6 +83,18 @@
             Lock Green
           </a>
         </li>
+        <li>
+          <a href="<%= url("/remove?names=#{light_name}") %>" data-turbo-method="post" data-turbo-confirm="Are you sure you want to remove this light?" class="flex items-center py-2 px-4 text-sm hover:bg-gray-100 dark:hover:bg-gray-600 dark:hover:text-white">
+            <svg class="flex w-4 h-4 me-1.5 text-red-600 shrink-0" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <polyline points="3 6 5 6 21 6"/>
+              <path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/>
+              <path d="M10 11v6"/>
+              <path d="M14 11v6"/>
+              <path d="M9 6V4a2 2 0 0 1 2-2h2a2 2 0 0 1 2 2v2"/>
+            </svg>
+            Remove
+          </a>
+        </li>
       </ul>
     </div>
   </div>

data/lib/stoplight/admin.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cgi" # Ruby 3.2 needs this
+
 begin
   require "sinatra/base"
   require "sinatra/json"
@@ -63,5 +65,11 @@ module Stoplight
 
       redirect to("/")
     end
+
+    post "/remove" do
+      dependencies.remove_action.call(params)
+
+      redirect to("/")
+    end
   end
 end

data/lib/stoplight/domain/data_store.rb

@@ -14,11 +14,37 @@ module Stoplight
         raise NotImplementedError
       end
 
-      # Retrieves metadata for a specific light configuration.
+      # Retrieves metrics for a specific light configuration.
+      #
+      # @param config [Stoplight::Domain::Config]
+      # @return [Stoplight::Domain::Metrics]
+      def get_metrics(config)
+        raise NotImplementedError
+      end
+
+      # Retrieves recovery metrics for a specific light configuration.
+      #
+      # @param config [Stoplight::Domain::Config]
+      # @return [Stoplight::Domain::Metrics]
+      def get_recovery_metrics(config)
+        raise NotImplementedError
+      end
+
+      # Retrieves State Snapshot for a specific light configuration.
+      #
+      # @param config [Stoplight::Domain::Config] The light configuration.
+      # @return [Stoplight::Domain::StateSnapshot]
+      def get_state_snapshot(config)
+        raise NotImplementedError
+      end
+
+      # Clears windowed metrics (successes/errors) to prevent
+      # stale failures from before recovery from affecting post-recovery decisions.
+      # Consecutive counts are intentionally preserved as they track current streaks.
       #
       # @param config [Stoplight::Domain::Config] The light configuration.
-      # @return [Stoplight::Domain::Metadata] The metadata associated with the light.
-      def get_metadata(config)
+      # @return [void]
+      def clear_windowed_metrics(config)
         raise NotImplementedError
       end
 
@@ -26,7 +52,7 @@ module Stoplight
       #
       # @param config [Stoplight::Domain::Config]
       # @param exception [Exception]
-      # @return [Stoplight::Domain::Metadata] The metadata associated with the light.
+      # @return [void]
       def record_failure(config, exception)
         raise NotImplementedError
       end
@@ -43,7 +69,7 @@ module Stoplight
       #
       # @param config [Stoplight::Domain::Config]
       # @param failure [Failure]
-      # @return [Stoplight::Domain::Metadata]
+      # @return [void]
       def record_recovery_probe_failure(config, failure)
         raise NotImplementedError
       end
@@ -51,7 +77,7 @@ module Stoplight
       # Records a successful recovery probe for a specific light configuration.
       #
       # @param config [Stoplight::Domain::Config]
-      # @return [Stoplight::Domain::Metadata]
+      # @return [void]
       def record_recovery_probe_success(config)
         raise NotImplementedError
       end
@@ -88,6 +114,16 @@ module Stoplight
       def transition_to_color(config, color)
         raise NotImplementedError
       end
+
+      # Deletes metadata (and related persistent state) for the given light.
+      #
+      # Implementations may choose to only remove metadata; metrics may expire via TTL.
+      #
+      # @param config [Stoplight::Domain::Config]
+      # @return [void]
+      def delete_light(config)
+        raise NotImplementedError
+      end
     end
     # :nocov:
   end

data/lib/stoplight/domain/failure.rb

@@ -29,6 +29,8 @@ module Stoplight
         @time = time
       end
 
+      alias_method :occurred_at, :time
+
       # @param other [Failure]
       # @return [Boolean]
       def ==(other)

data/lib/stoplight/domain/light.rb

@@ -57,7 +57,7 @@ module Stoplight
       #
       # @return [String]
       def state
-        metadata.locked_state
+        state_snapshot.locked_state
       end
 
       # Returns current color:
@@ -71,7 +71,7 @@ module Stoplight
       #
       # @return [String] returns current light color
       def color
-        metadata.color
+        state_snapshot.color
       end
 
       # Runs the given block of code with this circuit breaker
@@ -91,9 +91,9 @@ module Stoplight
       def run(fallback = nil, &code)
         raise ArgumentError, "nothing to run. Please, pass a block into `Light#run`" unless block_given?
 
-        metadata.then do |metadata|
-          strategy = state_strategy_factory(metadata.color)
-          strategy.execute(fallback, metadata:, &code)
+        state_snapshot.then do |state_snapshot|
+          strategy = state_strategy_factory(state_snapshot.color)
+          strategy.execute(fallback, state_snapshot:, &code)
         end
       end
 
@@ -189,9 +189,8 @@ module Stoplight
         end
       end
 
-      # @return [Stoplight::Domain::Metadata]
-      def metadata
-        data_store.get_metadata(config)
+      def state_snapshot
+        data_store.get_state_snapshot(config)
       end
     end
   end

data/lib/stoplight/domain/metrics.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # Request metrics over a given window.
+    #
+    # @!attribute successes
+    #   A number of successes withing requested window. Zero for non-windowed metrics
+    #   @return [Integer]
+    #
+    # @!attribute errors
+    #   A number of errors withing requested window. Zero for non-windowed metrics
+    #   @return [Integer]
+    #
+    # @!attribute total_consecutive_errors
+    #   A total number of consecutive errors
+    #   @return [Integer]
+    #
+    # @!attribute total_consecutive_successes
+    #   A total number of consecutive successes
+    #   @return [Integer]
+    #
+    # @!attribute last_error
+    #   @return [Stoplight::Domain::Failure, nil]
+    #
+    # @!attribute last_success_at
+    #   @return [Time, nil]
+    #
+    # @api private
+    Metrics = Data.define(
+      :successes,
+      :errors,
+      :total_consecutive_errors,
+      :total_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]
+      def error_rate
+        return unless requests # we effectively check if this is windowed metrics
+
+        if (successes + errors).zero?
+          0.0
+        else
+          errors.fdiv(successes + errors)
+        end
+      end
+
+      # @return [Integer]
+      def requests
+        if successes && errors # we effectively check if this is windowed metrics
+          successes + errors
+        end
+      end
+
+      # @return [Time, nil]
+      def last_error_at
+        last_error&.time
+      end
+    end
+  end
+end

data/lib/stoplight/domain/{metadata.rb → state_snapshot.rb}

@@ -2,41 +2,39 @@
 
 module Stoplight
   module Domain
-    # @api private
-    Metadata = Data.define(
-      :successes,
-      :errors,
-      :recovery_probe_successes,
-      :recovery_probe_errors,
-      :last_error_at,
-      :last_success_at,
-      :consecutive_errors,
-      :consecutive_successes,
-      :last_error,
+    # @!attribute breached_at
+    #   The time when the light became red (breached threshold)
+    #   @return [Time, nil]
+    #
+    # @!attribute locked_state
+    #   @return [State::UNLOCKED | State::LOCKED_GREEN | State::LOCKED_RED]
+    #
+    # @!attribute recovery_scheduled_after
+    #   When Light transitions to RED, it schedules recovery after the Cool Off Time.
+    #   @return [Time, nil]
+    #
+    # @!attribute recovery_started_at
+    #   When in YELLOW state, this time indicates the time of transitioning to YELLOW
+    #   @return [Time, nil]
+    #
+    # @!attribute time
+    #   The time when the snapshot was taken
+    #   @return [Time]
+    #
+    StateSnapshot = Data.define(
       :breached_at,
       :locked_state,
       :recovery_scheduled_after,
       :recovery_started_at,
-      :recovered_at,
-      :current_time
+      :time
     ) do
-      # YELLOW color could be entered implicitly through a timeout
-      # and explicitly through a transition.
-      #
-      # This method indicates whether the recovery has already started explicitly
-      #
-      # @return [Boolean]
-      def recovery_started?
-        recovery_started_at && recovery_started_at <= current_time
-      end
-
       # @return [String] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
       def color
         if locked_state == State::LOCKED_GREEN
           Color::GREEN
         elsif locked_state == State::LOCKED_RED
           Color::RED
-        elsif (recovery_scheduled_after && recovery_scheduled_after < current_time) || recovery_started_at
+        elsif (recovery_scheduled_after && recovery_scheduled_after < time) || recovery_started_at
           Color::YELLOW
         elsif breached_at
           Color::RED
@@ -45,20 +43,14 @@ module Stoplight
         end
       end
 
-      # Calculates the error rate based on the number of successes and errors.
+      # YELLOW color could be entered implicitly through a timeout
+      # and explicitly through a transition.
       #
-      # @return [Float]
-      def error_rate
-        if (successes + errors).zero?
-          0.0
-        else
-          errors.fdiv(successes + errors)
-        end
-      end
-
-      # @return [Integer]
-      def requests
-        successes + errors
+      # This method indicates whether the recovery has already started explicitly
+      #
+      # @return [Boolean]
+      def recovery_started?
+        recovery_started_at && recovery_started_at <= time
       end
     end
   end

data/lib/stoplight/domain/strategies/green_run_strategy.rb

@@ -28,11 +28,11 @@ module Stoplight
         # Executes the provided code block when the light is in the green state.
         #
         # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
-        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # @yield The code block to execute.
         # @return [Object] The result of the code block if successful.
         # @raise [Exception] Re-raises the error if it is not tracked or no fallback is provided.
-        def execute(fallback, metadata:, &code)
+        def execute(fallback, state_snapshot:, &code)
           # TODO: Consider implementing sampling rate to limit the memory footprint
           code.call.tap { record_success }
         rescue => error

data/lib/stoplight/domain/strategies/red_run_strategy.rb

@@ -21,17 +21,17 @@ module Stoplight
         # Executes the fallback proc when the light is in the red state.
         #
         # @param fallback [Proc, nil] A fallback proc to execute instead of the code block.
-        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # @return [Object, nil] The result of the fallback proc if provided.
         # @raise [Stoplight::Error::RedLight] Raises an error if no fallback is provided.
-        def execute(fallback, metadata:)
+        def execute(fallback, state_snapshot:)
           if fallback
             fallback.call(nil)
           else
             raise Error::RedLight.new(
               config.name,
               cool_off_time: config.cool_off_time,
-              retry_after: metadata.recovery_scheduled_after
+              retry_after: state_snapshot.recovery_scheduled_after
             )
           end
         end

data/lib/stoplight/domain/strategies/run_strategy.rb

@@ -10,9 +10,9 @@ module Stoplight
       # @abstract
       class RunStrategy
         # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
-        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # :nocov:
-        def execute(fallback, metadata:, &code)
+        def execute(fallback, state_snapshot:, &code)
           raise NotImplementedError, "Subclasses must implement the execute method"
         end
         # :nocov:

data/lib/stoplight/domain/strategies/yellow_run_strategy.rb

@@ -41,12 +41,12 @@ module Stoplight
         # Executes the provided code block when the light is in the yellow state.
         #
         # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
-        # @param metadata [Stoplight::Domain::Metadata] Metadata capturing the current state of the light.
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # @yield The code block to execute.
         # @return [Object] The result of the code block if successful.
         # @raise [Exception] Re-raises the error if it is not tracked or no fallback is provided.
-        def execute(fallback, metadata:, &code)
-          enter_recovery(metadata)
+        def execute(fallback, state_snapshot:, &code)
+          enter_recovery(state_snapshot)
           # TODO: We need to employ a probabilistic approach here to avoid "thundering herd" problem
           code.call.tap { record_recovery_probe_success }
         rescue => error
@@ -72,12 +72,13 @@ module Stoplight
           request_tracker.record_failure(error)
         end
 
-        # @param metadata [Stoplight::Domain::Metadata]
+        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
         # @return [void]
-        private def enter_recovery(metadata)
-          return if metadata.recovery_started?
+        private def enter_recovery(state_snapshot)
+          return if state_snapshot.recovery_started?
 
           if data_store.transition_to_color(config, Color::YELLOW)
+            data_store.clear_windowed_metrics(config)
             notifiers.each do |notifier|
               notifier.notify(config, Color::RED, Color::YELLOW, nil)
             end

data/lib/stoplight/domain/tracker/recovery_probe.rb

@@ -33,15 +33,15 @@ module Stoplight
 
         # @param exception [Exception]
         def record_failure(exception)
-          metadata = data_store.record_recovery_probe_failure(config, exception)
+          data_store.record_recovery_probe_failure(config, exception)
 
-          recover(metadata)
+          recover
         end
 
         def record_success
-          metadata = data_store.record_recovery_probe_success(config)
+          data_store.record_recovery_probe_success(config)
 
-          recover(metadata)
+          recover
         end
         RECOVERY_TRANSITIONS = {
           TrafficRecovery::GREEN => [Color::YELLOW, Color::GREEN],
@@ -49,8 +49,11 @@ module Stoplight
           TrafficRecovery::RED => [Color::YELLOW, Color::RED]
         }.freeze
 
-        private def recover(metadata)
-          recovery_result = traffic_recovery.determine_color(config, metadata)
+        private def recover
+          recovery_metrics = data_store.get_recovery_metrics(config)
+          state_snapshot = data_store.get_state_snapshot(config) # TODO: is this really necessary?
+
+          recovery_result = traffic_recovery.determine_color(config, recovery_metrics, state_snapshot)
 
           return if recovery_result == TrafficRecovery::PASS
 

data/lib/stoplight/domain/tracker/request.rb

@@ -40,9 +40,10 @@ module Stoplight
         # @param exception [Exception]
         # @return [void]
         def record_failure(exception)
-          metadata = data_store.record_failure(config, exception)
+          data_store.record_failure(config, exception)
+          metrics = data_store.get_metrics(config)
 
-          transition_to_red(exception, metadata:)
+          transition_to_red(exception, metrics:)
         end
 
         # @return [void]
@@ -50,8 +51,8 @@ module Stoplight
           data_store.record_success(config)
         end
 
-        private def transition_to_red(exception, metadata:)
-          if traffic_control.stop_traffic?(config, metadata)
+        private def transition_to_red(exception, metrics:)
+          if traffic_control.stop_traffic?(config, metrics)
             transition_and_notify(Color::GREEN, Color::RED, exception)
           end
         end

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

@@ -18,11 +18,11 @@ module Stoplight
       #       end
       #     end
       #
-      #     def stop_traffic?(config, metadata)
-      #       total = metadata.successes + metadata.failures
+      #     def stop_traffic?(config, metrics)
+      #       total = metrics.successes + metrics.failures
       #       return false if total < 10 # Minimum sample size
       #
-      #       error_rate = metadata.failures.fdiv(total)
+      #       error_rate = metrics.failures.fdiv(total)
       #       error_rate >= 0.5 # Stop traffic when error rate reaches 50%
       #     end
       #   end
@@ -44,10 +44,10 @@ module Stoplight
         # current state and metrics.
         #
         # @param config [Stoplight::Domain::Config]
-        # @param metadata [Stoplight::Domain::Metadata]
+        # @param metrics [Stoplight::Domain::Metrics]
         # @return [Boolean] true if traffic should be stopped (rec), false otherwise (green)
         # :nocov:
-        def stop_traffic?(config, metadata)
+        def stop_traffic?(config, metrics)
           raise NotImplementedError
         end
         # :nocov:

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

@@ -42,14 +42,10 @@ module Stoplight
         # Determines if traffic should be stopped based on failure counts.
         #
         # @param config [Stoplight::Domain::Config]
-        # @param metadata [Stoplight::Domain::Metadata]
+        # @param metrics [Stoplight::Domain::Metrics]
         # @return [Boolean] true if failures have reached the threshold, false otherwise
-        def stop_traffic?(config, metadata)
-          if config.window_size
-            [metadata.consecutive_errors, metadata.errors].min >= config.threshold
-          else
-            metadata.consecutive_errors >= config.threshold
-          end
+        def stop_traffic?(config, metrics)
+          metrics.consecutive_errors >= config.threshold
         end
       end
     end

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

@@ -40,10 +40,10 @@ module Stoplight
         end
 
         # @param config [Stoplight::Domain::Config]
-        # @param metadata [Stoplight::Domain::Metadata]
+        # @param metrics [Stoplight::Domain::Metrics]
         # @return [Boolean]
-        def stop_traffic?(config, metadata)
-          metadata.requests >= min_requests && metadata.error_rate >= config.threshold
+        def stop_traffic?(config, metrics)
+          metrics.requests >= min_requests && metrics.error_rate >= config.threshold
         end
       end
     end