stoplight 5.5.0 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 297bbf636a9d6fa8e47b2241a3bfe0ccf357954044dc9cd02b79735012d92148
-  data.tar.gz: 7e539fac482dbde352b0e971b20d29968758c85017c2f917859d5130ef8ed7a1
+  metadata.gz: d96e1b5dcce81c642d059b07b2e274b8c7dbd7f246b86ee25ce40567eaba8418
+  data.tar.gz: e6b04f0ff592f89f345ff3f9ec9e26b86463ff0baeb56ef752cbd00b7f8952b8
 SHA512:
-  metadata.gz: 53277c7ec692204dc99c96dbf4d8e224d47424b6f5605445de2dc9122d09adedcb683ca783be7f0496db0b6e9aef9045636100da889055e0cb0ee4a4c398ab1e
-  data.tar.gz: f0dd133ab0aa988a9bac5d9b2954299c5cf47ee86f08482b0199c8108fe953ae6e44c5f781457cda74063a93d1686da9ce76b4e4780ffb16d66dd70790b17815
+  metadata.gz: 01c5c2356f84eaeade94edba7113e700682911558d165b8b60186abbe0cda3d0f453427b8ab6e96f4ab51948e3ec5a109e53e1b51cc15c46c3fd79aad4865768
+  data.tar.gz: 94633b744ef88219f66289d9aae91bbb35b013bbea82c84f0f253abd15d4e5bd7ea5a123c39dffc36911479b1663cee71f786110be0ee15c3c8f56d035032e76

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

@@ -8,7 +8,7 @@ module Stoplight
       attr_reader :data_store
       private :data_store
 
-      # @param data_store [Stoplight::DataStore::Base]
+      # @param data_store [Stoplight::Domain::DataStore]
       def initialize(data_store:)
         @data_store = data_store
       end
@@ -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/helpers.rb

@@ -15,11 +15,16 @@ module Stoplight
       end
 
       private def data_store
-        settings.data_store.tap do |data_store|
-          if data_store.is_a?(Stoplight::DataStore::Memory)
-            raise "Stoplight Admin requires a persistent data store, but the current data store is Memory. " \
-              "Please configure a different data store in your Stoplight configuration."
-          end
+        if settings.data_store.is_a?(Stoplight::DataStore::Memory)
+          raise "Stoplight Admin requires a persistent data store, but the current data store is Memory. " \
+            "Please configure a different data store in your Stoplight configuration."
+        else
+          Stoplight::Wiring::LightBuilder.new(
+            {
+              data_store: settings.data_store,
+              config: Wiring::Light::DefaultConfig
+            }
+          ).__send__(:data_store)
         end
       end
     end

data/lib/stoplight/admin/lights_repository.rb

@@ -4,11 +4,11 @@ module Stoplight
   class Admin
     class LightsRepository
       # @!attribute data_store
-      #   @return [Stoplight::DataStore::Base]
+      #   @return [Stoplight::Domain::DataStore]
       attr_reader :data_store
       private :data_store
 
-      #  @param data_store [Stoplight::DataStore::Base]
+      #  @param data_store [Stoplight::Domain::DataStore]
       def initialize(data_store:)
         @data_store = data_store
       end
@@ -37,37 +37,49 @@ module Stoplight
       #   color
       # @return [void]
       def lock(name, color = nil)
-        light = build_light(name)
+        config = build_config(name)
+        color ||= data_store.get_state_snapshot(config).color
 
-        case color || light.color
+        case color
         when Stoplight::Color::GREEN
-          light.lock(Stoplight::Color::GREEN)
+          data_store.set_state(config, Stoplight::State::LOCKED_GREEN)
         else
-          light.lock(Stoplight::Color::RED)
+          data_store.set_state(config, Stoplight::State::LOCKED_RED)
         end
       end
 
       # @param name [String] unlocks light by its name
       # @return [void]
       def unlock(name)
-        build_light(name).unlock
+        config = build_config(name)
+        data_store.set_state(config, Domain::State::UNLOCKED)
+      end
+
+      # @param name [String] removes light metadata by its name
+      # @return [void]
+      def remove(name)
+        config = build_config(name)
+
+        data_store.delete_light(config)
       end
 
       private def load_light(name)
-        light = build_light(name)
+        config = build_config(name)
+
         # failures, state
-        metadata = data_store.get_metadata(light.config)
+        state_snapshot = data_store.get_state_snapshot(config)
+        metrics = data_store.get_metrics(config)
 
         Light.new(
           name: name,
-          color: light.color,
-          state: metadata.locked_state,
-          failures: [metadata.last_error].compact
+          color: state_snapshot.color,
+          state: state_snapshot.locked_state,
+          failures: [metrics.last_error].compact
         )
       end
 
-      private def build_light(name)
-        Stoplight(name, data_store: data_store)
+      private def build_config(name)
+        Wiring::Light::DefaultConfig.with(name:)
       end
     end
   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,8 @@
 # frozen_string_literal: true
 
+require "cgi/escape"
+require "cgi/util" if RUBY_VERSION < "3.5"
+
 begin
   require "sinatra/base"
   require "sinatra/json"
@@ -63,5 +66,11 @@ module Stoplight
 
       redirect to("/")
     end
+
+    post "/remove" do
+      dependencies.remove_action.call(params)
+
+      redirect to("/")
+    end
   end
 end

data/lib/stoplight/common/deprecations.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Common
+    module Deprecations
+      extend self
+
+      def deprecate(message) = warn("[DEPRECATION] #{message}")
+    end
+  end
+end

data/lib/stoplight/domain/config.rb

@@ -7,7 +7,7 @@ module Stoplight
     # # @!attribute [r] name
     #   @return [String]
     #
-    # @!attribute [r] cool_off_time
+    # @!attribute [r] cool_off_time - cool-off time in seconds
     #   @return [Numeric]
     #
     # @!attribute [r] threshold
@@ -50,6 +50,10 @@ module Stoplight
 
         !skip && track
       end
+
+      def cool_off_time_in_milliseconds
+        cool_off_time * 1_000
+      end
     end
   end
 end

data/lib/stoplight/domain/data_store.rb

@@ -14,11 +14,41 @@ 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::Metadata] The metadata associated with the light.
-      def get_metadata(config)
+      # @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 [void]
+      def clear_metrics(config)
+        raise NotImplementedError
+      end
+
+      def clear_recovery_metrics(config)
         raise NotImplementedError
       end
 
@@ -26,7 +56,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 +73,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 +81,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
@@ -65,6 +95,18 @@ module Stoplight
         raise NotImplementedError
       end
 
+      # Acquires recovery lock for serializing probe execution.
+      #
+      # @param config [Stoplight::Domain::Config]
+      # @return [Stoplight::Domain::LockToken, nil] Lock if acquired, nil if contended
+      def acquire_recovery_lock(config) = raise NotImplementedError
+
+      # Releases previously acquired lock.
+      #
+      # @param lock [Stoplight::Domain::RecoveryLockToken]
+      # @return [void]
+      def release_recovery_lock(lock) = raise NotImplementedError
+
       # Transitions the Stoplight to the specified color.
       #
       # This method performs a color transition operation that works across distributed instances
@@ -88,6 +130,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/configuration_builder_interface.rb

@@ -15,9 +15,22 @@ module Stoplight
         #
         # @param data_store [DataStore::Base]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_data_store(data_store)
-          with(data_store:)
+          deprecate(<<~MSG)
+            Light#with_data_store is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_data_store(data_stare)
+
+            Configure correctly from the start:
+              Stoplight('api-call', data_store:)
+          MSG
+          with_without_warning(data_store:)
         end
 
         # Configures cool off time. Stoplight automatically tries to recover
@@ -29,9 +42,22 @@ module Stoplight
         #
         # @param cool_off_time [Numeric] number of seconds
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_cool_off_time(cool_off_time)
-          with(cool_off_time:)
+          deprecate(<<~MSG)
+            Light#with_cool_off_time is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_cool_off_time(cool_off_time)
+
+            Configure correctly from the start:
+              Stoplight('api-call', cool_off_time:)
+          MSG
+          with_without_warning(cool_off_time:)
         end
 
         # Configures custom threshold. After this number of failures Stoplight
@@ -43,9 +69,22 @@ module Stoplight
         #
         # @param threshold [Numeric]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_threshold(threshold)
-          with(threshold:)
+          deprecate(<<~MSG)
+            Light#with_threshold is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_threshold(threshold)
+
+            Configure correctly from the start:
+              Stoplight('api-call', threshold:)
+          MSG
+          with_without_warning(threshold:)
         end
 
         # Configures custom window size which Stoplight uses to count failures. For example,
@@ -60,9 +99,22 @@ module Stoplight
         #
         # @param window_size [Numeric] number of seconds
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_window_size(window_size)
-          with(window_size:)
+          deprecate(<<~MSG)
+            Light#with_window_size is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_window_size(window_size)
+
+            Configure correctly from the start:
+              Stoplight('api-call', window_size:)
+          MSG
+          with_without_warning(window_size:)
         end
 
         # Configures custom notifier
@@ -75,17 +127,43 @@ module Stoplight
         #
         # @param notifiers [Array<Notifier::Base>]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_notifiers(notifiers)
-          with(notifiers:)
+          deprecate(<<~MSG)
+            Light#with_notifiers is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_notifiers(notifiers)
+
+            Configure correctly from the start:
+              Stoplight('api-call', notifiers:)
+          MSG
+          with_without_warning(notifiers:)
         end
 
         # @param error_notifier [Proc]
         # @return [Stoplight::Light]
         # @api private
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_error_notifier(&error_notifier)
-          with(error_notifier: error_notifier)
+          deprecate(<<~MSG)
+            Light#with_error_notifier is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_error_notifier { |error| warn error }
+
+            Configure correctly from the start:
+              Stoplight('api-call', error_notifier: ->(error) { warn error })
+          MSG
+          with_without_warning(error_notifier: error_notifier)
         end
 
         # Configures a custom list of tracked errors that counts toward the threshold.
@@ -101,9 +179,22 @@ module Stoplight
         #
         # @param tracked_errors [Array<StandardError>]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_tracked_errors(*tracked_errors)
-          with(tracked_errors:)
+          deprecate(<<~MSG)
+            Light#with_tracked_errors is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_tracked_errors(TimeoutError, NetworkError)
+
+            Configure correctly from the start:
+              Stoplight('api-call', tracked_errors: [TimeoutError, NetworkError])
+          MSG
+          with_without_warning(tracked_errors:)
         end
 
         # Configures a custom list of skipped errors that do not count toward the threshold.
@@ -120,9 +211,22 @@ module Stoplight
         #
         # @param skipped_errors [Array<Exception>]
         # @return [Stoplight::Light]
-        # @deprecated consider using +Light#with+ for reconfiguration
+        # @deprecated
         def with_skipped_errors(*skipped_errors)
-          with(skipped_errors:)
+          deprecate(<<~MSG)
+            Light#with_skipped_errors is deprecated and will be removed in v6.0.0.
+
+            Circuit breakers should be configured once at creation, not cloned with
+            modifications.
+
+            Instead of:
+              light = Stoplight('api-call')
+              modified = light.with_skipped_errors(ActiveRecord::RecordNotFound)
+
+            Configure correctly from the start:
+              Stoplight('api-call', skipped_errors: [ActiveRecord::RecordNotFound])
+          MSG
+          with_without_warning(skipped_errors:)
         end
       end
     end