stoplight 5.3.8 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14702003b76fde01b28e5266b392f5d55b2924c83365a0ab122f11aebf2e4a7
-  data.tar.gz: e9c1b348b2637aa66408de62a2bbbc24b9b73927ca9712a8b4137446e336cd0a
+  metadata.gz: d96e1b5dcce81c642d059b07b2e274b8c7dbd7f246b86ee25ce40567eaba8418
+  data.tar.gz: e6b04f0ff592f89f345ff3f9ec9e26b86463ff0baeb56ef752cbd00b7f8952b8
 SHA512:
-  metadata.gz: 1601dd8a7fae2e9c8f89a52556c8f931d3712d71648300aef0e3dae226c9998b7b1fa35e7fa0ce151d943e961473e012ca382b718bb50b44000f5a43e4d667b8
-  data.tar.gz: 7c4e9696009e01bea1908cd3212d4625cc0ac3e03205d1cd69e4471f9aec4f3add7f101e58b393df210658e6be2c2d42b5d4a2ddedd954f832053505e291f232
+  metadata.gz: 01c5c2356f84eaeade94edba7113e700682911558d165b8b60186abbe0cda3d0f453427b8ab6e96f4ab51948e3ec5a109e53e1b51cc15c46c3fd79aad4865768
+  data.tar.gz: 94633b744ef88219f66289d9aae91bbb35b013bbea82c84f0f253abd15d4e5bd7ea5a123c39dffc36911479b1663cee71f786110be0ee15c3c8f56d035032e76

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
@@ -519,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
 ```
@@ -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/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/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,14 @@
 # frozen_string_literal: true
 
+require "cgi/escape"
+require "cgi/util" if RUBY_VERSION < "3.5"
+
 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 +27,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 +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/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,59 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # A +Stoplight::Light+ configuration object.
+    #
+    # # @!attribute [r] name
+    #   @return [String]
+    #
+    # @!attribute [r] cool_off_time - cool-off time in seconds
+    #   @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
+
+      def cool_off_time_in_milliseconds
+        cool_off_time * 1_000
+      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,56 @@ 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_metrics(config)
+        raise NotImplementedError
+      end
+
+      def clear_recovery_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,30 +71,42 @@ 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)
         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
@@ -71,7 +114,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 +130,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