stoplight 5.4.0 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2629a7cdd83dce508860ffe0c7fe3da4cad02eab605e0cb1b4f1e4c0f7db509d
-  data.tar.gz: 50f13d3625ab327dd07815fd3da1a9384a0cf0f1d75af2db853b098c3b90ba2e
+  metadata.gz: 297bbf636a9d6fa8e47b2241a3bfe0ccf357954044dc9cd02b79735012d92148
+  data.tar.gz: 7e539fac482dbde352b0e971b20d29968758c85017c2f917859d5130ef8ed7a1
 SHA512:
-  metadata.gz: 9aa893f78f602c6d71f82f15deb41d6aa0bb4bc0ca37bf3756003699e2b158e1d3a857ee0f1fdd6cebcbb35fb787e5f515a36f89dd5560c000297302cd0e7e18
-  data.tar.gz: 772938b653645a1ad3c8ca5e9e5958871c1b8802da6ce947d38fd9d5390fa9e336d8838941571569aed102cd0656c58389224b417bcf059f4569295c42894d6d
+  metadata.gz: 53277c7ec692204dc99c96dbf4d8e224d47424b6f5605445de2dc9122d09adedcb683ca783be7f0496db0b6e9aef9045636100da889055e0cb0ee4a4c398ab1e
+  data.tar.gz: f0dd133ab0aa988a9bac5d9b2954299c5cf47ee86f08482b0199c8108fe953ae6e44c5f781457cda74063a93d1686da9ce76b4e4780ffb16d66dd70790b17815

data/README.md

@@ -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/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

data/lib/stoplight/domain/light.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Stoplight
+  module Domain
+    #
+    # @api private use +Stoplight()+ method instead
+    class Light
+      extend Forwardable
+      include ConfigurationBuilderInterface
+
+      # @!attribute [r] config
+      #   @return [Stoplight::Domain::Config]
+      #   @api private
+      attr_reader :config
+
+      # @!attribute [r] name
+      #   The name of the light.
+      #   @return [String]
+      def_delegator :config, :name
+
+      # @!attribute [r] green_run_strategy
+      #   @return [Stoplight::Domain::Strategies::GreenRunStrategy]
+      protected attr_reader :green_run_strategy
+
+      # @!attribute [r] yellow_run_strategy
+      #   @return [Stoplight::Domain::Strategies::YellowRunStrategy]
+      protected attr_reader :yellow_run_strategy
+
+      # @!attribute [r] red_run_strategy
+      #   @return [Stoplight::Domain::Strategies::RedRunStrategy]
+      protected attr_reader :red_run_strategy
+
+      # @!attribute [r] data_store
+      #   @return [Stoplight::Light::Base]
+      protected attr_reader :data_store
+
+      # @!attribute [r] factory
+      #   @return [Stoplight::Domain::LightFactory]
+      protected attr_reader :factory
+
+      # @param config [Stoplight::Domain::Config]
+      def initialize(config, green_run_strategy:, yellow_run_strategy:, red_run_strategy:, data_store:, factory:)
+        @config = config
+        @data_store = data_store
+        @green_run_strategy = green_run_strategy
+        @yellow_run_strategy = yellow_run_strategy
+        @red_run_strategy = red_run_strategy
+        @factory = factory
+      end
+
+      # Returns the current state of the light:
+      #  * +Stoplight::State::LOCKED_GREEN+ -- light is locked green and allows all traffic
+      #  * +Stoplight::State::LOCKED_RED+ -- light is locked red and blocks all traffic
+      #  * +Stoplight::State::UNLOCKED+ -- light is not locked and follow the configured rules
+      #
+      # @return [String]
+      def state
+        metadata.locked_state
+      end
+
+      # Returns current color:
+      #   * +Stoplight::Color::GREEN+ -- circuit breaker is closed
+      #   * +Stoplight::Color::RED+ -- circuit breaker is open
+      #   * +Stoplight::Color::YELLOW+ -- circuit breaker is half-open
+      #
+      # @example
+      #   light = Stoplight('example')
+      #   light.color #=> Color::GREEN
+      #
+      # @return [String] returns current light color
+      def color
+        metadata.color
+      end
+
+      # Runs the given block of code with this circuit breaker
+      #
+      # @example
+      #   light = Stoplight('example')
+      #   light.run { 2/0 }
+      #
+      # @example Running with fallback
+      #   light = Stoplight('example')
+      #   light.run(->(error) { 0 }) { 1 / 0 } #=> 0
+      #
+      # @param fallback [Proc, nil] (nil) fallback code to run if the circuit breaker is open
+      # @raise [Stoplight::Error::RedLight]
+      # @return [any]
+      # @raise [Stoplight::Error::RedLight]
+      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)
+        end
+      end
+
+      # Locks light in either +State::LOCKED_RED+ or +State::LOCKED_GREEN+
+      #
+      # @example
+      #   light = Stoplight('example-locked')
+      #   light.lock(Stoplight::Color::RED)
+      #
+      # @param color [String] should be either +Color::RED+ or +Color::GREEN+
+      # @return [Stoplight::Light] returns locked light (circuit breaker)
+      def lock(color)
+        state = case color
+        when Color::RED then State::LOCKED_RED
+        when Color::GREEN then State::LOCKED_GREEN
+        else raise Error::IncorrectColor
+        end
+
+        data_store.set_state(config, state)
+
+        self
+      end
+
+      # Unlocks light and sets its state to State::UNLOCKED
+      #
+      # @example
+      #   light = Stoplight('example-locked')
+      #   light.lock(Stoplight::Color::RED)
+      #   light.unlock
+      #
+      # @return [Stoplight::Light] returns unlocked light (circuit breaker)
+      def unlock
+        data_store.set_state(config, State::UNLOCKED)
+
+        self
+      end
+
+      # Two lights considered equal if they have the same configuration.
+      #
+      # @param other [any]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) && config == other.config && data_store == other.data_store &&
+          green_run_strategy == other.green_run_strategy && yellow_run_strategy == other.yellow_run_strategy &&
+          red_run_strategy == other.red_run_strategy && factory == other.factory
+      end
+
+      # Reconfigures the light with updated settings and returns a new instance.
+      #
+      # This method allows you to modify the configuration of a +Stoplight::Light+ object
+      # by providing a hash of settings. The original light remains unchanged, and a new
+      # light instance with the updated configuration is returned.
+      #
+      # @param settings [Hash] A hash of configuration options to update.
+      # @option settings [String] :name The name of the light.
+      # @option settings [Numeric] :cool_off_time The cool-off time in seconds before the light attempts recovery.
+      # @option settings [Numeric] :threshold The failure threshold to trigger the red state.
+      # @option settings [Numeric] :window_size The time window in seconds for counting failures.
+      # @option settings [Stoplight::DataStore::Base] :data_store The data store to use for persisting light state.
+      # @option settings [Array<Stoplight::Domain::AbstractStateTransitionNotifier>] :notifiers A list of notifiers to handle light events.
+      # @option settings [Proc] :error_notifier A custom error notifier to handle exceptions.
+      # @option settings [Array<StandardError>] :tracked_errors A list of errors to track for failure counting.
+      # @option settings [Array<StandardError>] :skipped_errors A list of errors to skip from failure counting.
+      # @return [Stoplight::Light] A new `Stoplight::Light` instance with the updated configuration.
+      #
+      # @example Reconfiguring a light with custom settings
+      #   light = Stoplight('payment-api')
+      #
+      #   # Create a light for invoices with a higher threshold
+      #   invoices_light = light.with(tracked_errors: [TimeoutError], threshold: 10)
+      #
+      #   # Create a light for payments with a lower threshold
+      #   payment_light = light.with(threshold: 5)
+      #
+      #   # Run the lights with their respective configurations
+      #   invoices_light.run(->(error) { [] }) { call_invoices_api }
+      #   payment_light.run(->(error) { nil }) { call_payment_api }
+      # @see +Stoplight()+
+      def with(**settings)
+        factory.build_with(**settings)
+      end
+
+      private
+
+      def state_strategy_factory(color)
+        case color
+        when Color::GREEN
+          green_run_strategy
+        when Color::YELLOW
+          yellow_run_strategy
+        else
+          red_run_strategy
+        end
+      end
+
+      # @return [Stoplight::Domain::Metadata]
+      def metadata
+        data_store.get_metadata(config)
+      end
+    end
+  end
+end