stoplight 5.3.8 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14702003b76fde01b28e5266b392f5d55b2924c83365a0ab122f11aebf2e4a7
-  data.tar.gz: e9c1b348b2637aa66408de62a2bbbc24b9b73927ca9712a8b4137446e336cd0a
+  metadata.gz: 297bbf636a9d6fa8e47b2241a3bfe0ccf357954044dc9cd02b79735012d92148
+  data.tar.gz: 7e539fac482dbde352b0e971b20d29968758c85017c2f917859d5130ef8ed7a1
 SHA512:
-  metadata.gz: 1601dd8a7fae2e9c8f89a52556c8f931d3712d71648300aef0e3dae226c9998b7b1fa35e7fa0ce151d943e961473e012ca382b718bb50b44000f5a43e4d667b8
-  data.tar.gz: 7c4e9696009e01bea1908cd3212d4625cc0ac3e03205d1cd69e4471f9aec4f3add7f101e58b393df210658e6be2c2d42b5d4a2ddedd954f832053505e291f232
+  metadata.gz: 53277c7ec692204dc99c96dbf4d8e224d47424b6f5605445de2dc9122d09adedcb683ca783be7f0496db0b6e9aef9045636100da889055e0cb0ee4a4c398ab1e
+  data.tar.gz: f0dd133ab0aa988a9bac5d9b2954299c5cf47ee86f08482b0199c8108fe953ae6e44c5f781457cda74063a93d1686da9ce76b4e4780ffb16d66dd70790b17815

data/README.md

@@ -99,6 +99,19 @@ light.run { 1 / 0 } #=> raises Stoplight::Error::RedLight: example-zero
 light.color # => "red"
 ```
 
+The `Stoplight::Error::RedLight` provides metadata about the error:
+
+```ruby
+def run_request
+  light = Stoplight("Example", cool_off_time: 10)
+  light.run { 1 / 0 }  #=> raises Stoplight::Error::RedLight
+rescue Stoplight::Error::RedLight => error
+  puts error.light_name #=> "Example"
+  puts error.cool_off_time #=> 10
+  puts error.retry_after   #=> Absolute Time after which a recovery attempt can occur (e.g., "2025-10-21 15:39:50.672414 +0600")
+end
+```
+
 After one minute, the light transitions to yellow, allowing a test execution:
 
 ```ruby
@@ -131,6 +144,8 @@ receives `nil`. In both cases, the return value of the fallback becomes the retu
 
 Stoplight comes with a built-in Admin Panel that can track all active Lights and manually lock them in the desired state (`Green` or `Red`). Locking lights in certain states might be helpful in scenarios like E2E testing.
 
+![Admin Panel Screenshot](assets/admin.png)
+
 To add Admin Panel protected by basic authentication to your Rails project, add this configuration to your `config/routes.rb` file.
 
 ```ruby
@@ -613,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/generators/stoplight/install/templates/stoplight.rb.erb

@@ -12,7 +12,9 @@ require "redis"
 #   "redis://admin:p4ssw0rd@10.0.1.1:6380/15"
 redis = Redis.new
 data_store = Stoplight::DataStore::Redis.new(redis)
+error_notifier = Rails.error.method(:report)
 
 Stoplight.configure do |config|
   config.data_store = data_store
+  config.error_notifier = error_notifier
 end

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

@@ -2,11 +2,10 @@
 
 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 +24,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

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.
@@ -15,24 +16,24 @@ module Stoplight
 
       # Retrieves metadata for a specific light configuration.
       #
-      # @param config [Stoplight::Light::Config] The light configuration.
-      # @return [Stoplight::Metadata] The metadata associated with the light.
+      # @param config [Stoplight::Domain::Config] The light configuration.
+      # @return [Stoplight::Domain::Metadata] The metadata associated with the light.
       def get_metadata(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 [Stoplight::Domain::Metadata] The metadata associated with the light.
+      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 +41,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 [Stoplight::Domain::Metadata]
       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 [Stoplight::Domain::Metadata]
       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 +72,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.
       #
@@ -88,5 +89,6 @@ module Stoplight
         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,42 @@
+# 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
+
+      # @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