stoplight 5.4.0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2629a7cdd83dce508860ffe0c7fe3da4cad02eab605e0cb1b4f1e4c0f7db509d
-  data.tar.gz: 50f13d3625ab327dd07815fd3da1a9384a0cf0f1d75af2db853b098c3b90ba2e
+  metadata.gz: f540f78d771a711da32d2e50cc150c4072cf805e4ef7e52e0b5ea07dd2435fea
+  data.tar.gz: 2b859ca65577026db5e1e5af4bc2900e178edc0e230b1cfc75728ffcadc9efc8
 SHA512:
-  metadata.gz: 9aa893f78f602c6d71f82f15deb41d6aa0bb4bc0ca37bf3756003699e2b158e1d3a857ee0f1fdd6cebcbb35fb787e5f515a36f89dd5560c000297302cd0e7e18
-  data.tar.gz: 772938b653645a1ad3c8ca5e9e5958871c1b8802da6ce947d38fd9d5390fa9e336d8838941571569aed102cd0656c58389224b417bcf059f4569295c42894d6d
+  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
 ```
@@ -628,7 +628,7 @@ Example: "Ruby 3.2 reaches end-of-life in March 2026, so Stoplight 6.0 will requ
 
 After checking out the repo, run `bundle install` to install dependencies. Run tests with `bundle exec rspec` and check 
 code style with `bundle exec standardrb`. We follow a git flow branching strategy - see our [Git Flow wiki page] for 
-details on branch naming, releases, and contribution workflow.
+details on branch naming, releases, and contribution workflow. Also check our CONTRIBUTING.md guide for contributors.
 
 ## Credits
 

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/views/layout.erb

@@ -6,8 +6,8 @@
 
     <title>Stoplight Admin</title>
 
-    <script type="module" src="https://cdn.jsdelivr.net/npm/@hotwired/turbo@latest/dist/turbo.es2017-esm.min.js"></script>
-    <script type="module">
+    <script nonce="<%= nonce %>" type="module" src="https://cdn.jsdelivr.net/npm/@hotwired/turbo@latest/dist/turbo.es2017-esm.min.js"></script>
+    <script nonce="<%= nonce %>" type="module">
         document.addEventListener("turbo:load", () => {
             window.initFlowbite()
         })
@@ -63,6 +63,6 @@
       </footer>
     </div>
 
-    <script src="https://cdn.jsdelivr.net/npm/flowbite@3.1.2/dist/flowbite.min.js"></script>
+    <script nonce="<%= nonce %>" src="https://cdn.jsdelivr.net/npm/flowbite@3.1.2/dist/flowbite.min.js"></script>
   </body>
 </html>

data/lib/stoplight/admin.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require "cgi" # Ruby 3.2 needs this
+
 begin
   require "sinatra/base"
-  require "sinatra/contrib"
   require "sinatra/json"
 rescue LoadError
   raise <<~WARN
-    "sinatra" and "sinatra-contrib" gems are unavailable and necessery for running Stoplight Admin panel
+    "sinatra" and "sinatra-contrib" gems are unavailable and necessary for running Stoplight Admin panel
     Please add them to your Gemfile and run `bundle install`:
       gem "sinatra", required: false
       gem "sinatra-contrib", require: false
@@ -25,13 +26,14 @@ module Stoplight
     helpers Helpers
 
     set :protection, except: %i[json_csrf]
-    set :data_store, proc { Stoplight.default_config.data_store }
+    set :data_store, proc { Stoplight.__stoplight__default_configuration.data_store }
     set :views, File.join(__dir__, "admin", "views")
+    set :nonce, proc { |request| }
 
     get "/" do
       lights, stats = dependencies.stats_action.call
 
-      erb :index, locals: stats.merge(lights: lights)
+      erb :index, locals: stats.merge(lights: lights, nonce: settings.nonce(request))
     end
 
     get "/stats" do
@@ -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/color.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Color
+      GREEN = "green"
+      YELLOW = "yellow"
+      RED = "red"
+    end
+  end
+end

data/lib/stoplight/{config → domain}/compatibility_result.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Stoplight
-  module Config
+  module Domain
     # The +CompatibilityResult+ class represents the result of a compatibility check
     # for a strategy. It provides methods to determine if the strategy is compatible
     # and to retrieve error messages when it is not.

data/lib/stoplight/domain/config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # A +Stoplight::Light+ configuration object.
+    #
+    # # @!attribute [r] name
+    #   @return [String]
+    #
+    # @!attribute [r] cool_off_time
+    #   @return [Numeric]
+    #
+    # @!attribute [r] threshold
+    #   @return [Numeric]
+    #
+    # @!attribute [r] window_size
+    #   @return [Numeric]
+    #
+    # @!attribute [r] tracked_errors
+    #   @return [Array<StandardError>]
+    #
+    # @!attribute [r] skipped_errors
+    #  @return [Array<Exception>]
+    #
+    # @api private
+    Config = Data.define(
+      :name,
+      :cool_off_time,
+      :threshold,
+      :recovery_threshold,
+      :window_size,
+      :tracked_errors,
+      :skipped_errors
+    ) do
+      class << self
+        # Creates a new NULL configuration object.
+        # @return [Stoplight::Domain::Config]
+        def empty
+          new(**members.map { |key| [key, nil] }.to_h)
+        end
+      end
+
+      # Checks if the given error should be tracked
+      #
+      # @param error [#==] The error to check, e.g. an Exception, Class or Proc
+      # @return [Boolean]
+      def track_error?(error)
+        skip = skipped_errors.any? { |klass| klass === error }
+        track = tracked_errors.any? { |klass| klass === error }
+
+        !skip && track
+      end
+    end
+  end
+end

data/lib/stoplight/{data_store/base.rb → domain/data_store.rb}

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 module Stoplight
-  module DataStore
+  module Domain
     # @abstract
-    class Base
+    # :nocov:
+    class DataStore
       METRICS_RETENTION_TIME = 60 * 60 * 24 # 1 day
 
       # Retrieves the names of all lights stored in the data store.
@@ -13,26 +14,52 @@ module Stoplight
         raise NotImplementedError
       end
 
-      # Retrieves metadata for a specific light configuration.
+      # Retrieves metrics for a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config] The light configuration.
-      # @return [Stoplight::Metadata] The metadata associated with the light.
-      def get_metadata(config)
+      # @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 [void]
+      def clear_windowed_metrics(config)
         raise NotImplementedError
       end
 
       # Records a failure for a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config]
-      # @param failure [Failure] The failure to record.
-      # @return [Stoplight::Metadata] The metadata associated with the light.
-      def record_failure(config, failure)
+      # @param config [Stoplight::Domain::Config]
+      # @param exception [Exception]
+      # @return [void]
+      def record_failure(config, exception)
         raise NotImplementedError
       end
 
       # Records a success for a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config]
+      # @param config [Stoplight::Domain::Config]
       # @return [void]
       def record_success(config)
         raise NotImplementedError
@@ -40,24 +67,24 @@ module Stoplight
 
       # Records a failed recovery probe for a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config]
+      # @param config [Stoplight::Domain::Config]
       # @param failure [Failure]
-      # @return [Stoplight::Metadata]
+      # @return [void]
       def record_recovery_probe_failure(config, failure)
         raise NotImplementedError
       end
 
       # Records a successful recovery probe for a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config]
-      # @return [Stoplight::Metadata]
+      # @param config [Stoplight::Domain::Config]
+      # @return [void]
       def record_recovery_probe_success(config)
         raise NotImplementedError
       end
 
       # Sets the state of a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config]
+      # @param config [Stoplight::Domain::Config]
       # @param state [String] The new state to set.
       # @return [String] The state that was set.
       def set_state(config, state)
@@ -71,7 +98,7 @@ module Stoplight
       # is considered the "first" to perform the transition (and therefore responsible for
       # triggering notifications).
       #
-      # @param config [Stoplight::Light::Config]
+      # @param config [Stoplight::Domain::Config]
       # @param color [String] The target color/state to transition to.
       #   Should be one of Stoplight::Color::GREEN, Stoplight::Color::YELLOW, or Stoplight::Color::RED.
       #
@@ -87,6 +114,17 @@ 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
 end

data/lib/stoplight/domain/error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Error
+      Base = Class.new(StandardError)
+      ConfigurationError = Class.new(Base)
+      IncorrectColor = Class.new(Base)
+
+      class RedLight < Base
+        # @!attribute light_name
+        #   @return [String] The light's name
+        attr_reader :light_name
+
+        # @!attribute cool_off_time
+        #   @return [Numeric] Cool-off period in seconds
+        attr_reader :cool_off_time
+
+        # @!attribute retry_after
+        #   @return [Time] Absolute Time after which a recovery attempt can occur
+        attr_reader :retry_after
+
+        # Initializes a new RedLight error.
+        #
+        # @param light_name [String] The light's name
+        #
+        # @option cool_off_time [Numeric] Cool-off period in seconds
+        #
+        # @option retry_after [Time] Absolute Time after which a recovery attempt can occur
+        #
+        # @return [Stoplight::Error::RedLight]
+        def initialize(light_name, cool_off_time:, retry_after:)
+          @light_name = light_name
+          @cool_off_time = cool_off_time
+          @retry_after = retry_after
+
+          super(light_name)
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/failure.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Stoplight
+  module Domain
+    # @api private
+    class Failure
+      # @return [String]
+      attr_reader :error_class
+      # @return [String]
+      attr_reader :error_message
+      # @return [Time]
+      attr_reader :time
+
+      # @param error [Exception]
+      # @return (see #initialize)
+      def self.from_error(error, time: Time.now)
+        new(error.class.name, error.message, time)
+      end
+
+      # @param error_class [String]
+      # @param error_message [String]
+      # @param time [Time]
+      def initialize(error_class, error_message, time)
+        @error_class = error_class
+        @error_message = error_message
+        @time = time
+      end
+
+      alias_method :occurred_at, :time
+
+      # @param other [Failure]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) &&
+          error_class == other.error_class &&
+          error_message == other.error_message &&
+          time == other.time
+      end
+    end
+  end
+end

data/lib/stoplight/domain/light/configuration_builder_interface.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Stoplight
+  module Domain
+    class Light
+      # Implements light configuration behavior
+      module ConfigurationBuilderInterface
+        # Configures data store to be used with this circuit breaker
+        #
+        # @example
+        #   Stoplight('example')
+        #     .with_data_store(Stoplight::DataStore::Memory.new)
+        #
+        # @param data_store [DataStore::Base]
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_data_store(data_store)
+          with(data_store:)
+        end
+
+        # Configures cool off time. Stoplight automatically tries to recover
+        # from the red state after the cool off time.
+        #
+        # @example
+        #   Stoplight('example')
+        #     .cool_off_time(60)
+        #
+        # @param cool_off_time [Numeric] number of seconds
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_cool_off_time(cool_off_time)
+          with(cool_off_time:)
+        end
+
+        # Configures custom threshold. After this number of failures Stoplight
+        # switches to the red state:
+        #
+        # @example
+        #   Stoplight('example')
+        #     .with_threshold(5)
+        #
+        # @param threshold [Numeric]
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_threshold(threshold)
+          with(threshold:)
+        end
+
+        # Configures custom window size which Stoplight uses to count failures. For example,
+        #
+        # @example
+        #   Stoplight('example')
+        #     .with_threshold(5)
+        #     .with_window_size(60)
+        #
+        # The above example will turn to red light only when 5 errors happen
+        # within 60 seconds period.
+        #
+        # @param window_size [Numeric] number of seconds
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_window_size(window_size)
+          with(window_size:)
+        end
+
+        # Configures custom notifier
+        #
+        # @example
+        #   io = StringIO.new
+        #   notifier = Stoplight::Notifier::IO.new(io)
+        #   Stoplight('example')
+        #     .with_notifiers([notifier])
+        #
+        # @param notifiers [Array<Notifier::Base>]
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_notifiers(notifiers)
+          with(notifiers:)
+        end
+
+        # @param error_notifier [Proc]
+        # @return [Stoplight::Light]
+        # @api private
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_error_notifier(&error_notifier)
+          with(error_notifier: error_notifier)
+        end
+
+        # Configures a custom list of tracked errors that counts toward the threshold.
+        #
+        # @example
+        #   light = Stoplight('example')
+        #     .with_tracked_errors(TimeoutError, NetworkError)
+        #   light.run { call_external_service }
+        #
+        # In the example above, the +TimeoutError+ and +NetworkError+ exceptions
+        # will be counted towards the threshold for moving the circuit breaker into the red state.
+        # If not configured, the default tracked error is +StandardError+.
+        #
+        # @param tracked_errors [Array<StandardError>]
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_tracked_errors(*tracked_errors)
+          with(tracked_errors:)
+        end
+
+        # Configures a custom list of skipped errors that do not count toward the threshold.
+        # Typically, such errors does not represent a real failure and handled somewhere else
+        # in the code.
+        #
+        # @example
+        #   light = Stoplight('example')
+        #    .with_skipped_errors(ActiveRecord::RecordNotFound)
+        #   light.run { User.find(123) }
+        #
+        # In the example above, the +ActiveRecord::RecordNotFound+ doesn't
+        # move the circuit breaker into the red state.
+        #
+        # @param skipped_errors [Array<Exception>]
+        # @return [Stoplight::Light]
+        # @deprecated consider using +Light#with+ for reconfiguration
+        def with_skipped_errors(*skipped_errors)
+          with(skipped_errors:)
+        end
+      end
+    end
+  end
+end