RubyGems - stoplight - Versions diffs - 4.1.1 → 5.0.1 - Mend

stoplight 4.1.1 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (105) hide show

checksums.yaml +4 -4
data/README.md +288 -354
data/lib/stoplight/admin/actions/action.rb +24 -0
data/lib/stoplight/admin/actions/lock.rb +23 -0
data/lib/stoplight/admin/actions/lock_all_green.rb +18 -0
data/lib/stoplight/admin/actions/lock_green.rb +23 -0
data/lib/stoplight/admin/actions/lock_red.rb +23 -0
data/lib/stoplight/admin/actions/stats.rb +27 -0
data/lib/stoplight/admin/actions/unlock.rb +23 -0
data/lib/stoplight/admin/dependencies.rb +50 -0
data/lib/stoplight/admin/helpers.rb +27 -0
data/lib/stoplight/admin/lights_repository/light.rb +155 -0
data/lib/stoplight/admin/lights_repository.rb +74 -0
data/lib/stoplight/admin/lights_stats.rb +77 -0
data/lib/stoplight/admin/views/_card.erb +120 -0
data/lib/stoplight/admin/views/index.erb +36 -0
data/lib/stoplight/admin/views/layout.erb +66 -0
data/lib/stoplight/admin.rb +68 -0
data/lib/stoplight/color.rb +3 -3
data/lib/stoplight/config/config_provider.rb +62 -0
data/lib/stoplight/config/library_default_config.rb +29 -0
data/lib/stoplight/config/user_default_config.rb +83 -0
data/lib/stoplight/data_store/base.rb +59 -33
data/lib/stoplight/data_store/fail_safe.rb +105 -0
data/lib/stoplight/data_store/memory.rb +257 -50
data/lib/stoplight/data_store/redis/get_metadata.lua +38 -0
data/lib/stoplight/data_store/redis/lua.rb +23 -0
data/lib/stoplight/data_store/redis/record_failure.lua +36 -0
data/lib/stoplight/data_store/redis/record_success.lua +35 -0
data/lib/stoplight/data_store/redis/transition_to_green.lua +10 -0
data/lib/stoplight/data_store/redis/transition_to_red.lua +10 -0
data/lib/stoplight/data_store/redis/transition_to_yellow.lua +9 -0
data/lib/stoplight/data_store/redis.rb +345 -106
data/lib/stoplight/default.rb +11 -9
data/lib/stoplight/error.rb +1 -13
data/lib/stoplight/failure.rb +14 -13
data/lib/stoplight/light/config.rb +118 -0
data/lib/stoplight/light/configuration_builder_interface.rb +128 -0
data/lib/stoplight/light/green_run_strategy.rb +53 -0
data/lib/stoplight/light/red_run_strategy.rb +26 -0
data/lib/stoplight/light/run_strategy.rb +30 -0
data/lib/stoplight/light/yellow_run_strategy.rb +78 -0
data/lib/stoplight/light.rb +164 -84
data/lib/stoplight/metadata.rb +71 -0
data/lib/stoplight/notifier/base.rb +14 -7
data/lib/stoplight/notifier/fail_safe.rb +67 -0
data/lib/stoplight/notifier/generic.rb +54 -5
data/lib/stoplight/rspec/generic_notifier.rb +11 -12
data/lib/stoplight/rspec.rb +1 -1
data/lib/stoplight/state.rb +3 -3
data/lib/stoplight/traffic_control/base.rb +35 -0
data/lib/stoplight/traffic_control/consecutive_failures.rb +43 -0
data/lib/stoplight/traffic_recovery/base.rb +51 -0
data/lib/stoplight/traffic_recovery/single_success.rb +35 -0
data/lib/stoplight/version.rb +1 -1
data/lib/stoplight.rb +111 -51
metadata +49 -98
data/lib/stoplight/builder.rb +0 -70
data/lib/stoplight/circuit_breaker.rb +0 -102
data/lib/stoplight/configurable.rb +0 -95
data/lib/stoplight/configuration.rb +0 -126
data/lib/stoplight/light/deprecated.rb +0 -44
data/lib/stoplight/light/lockable.rb +0 -45
data/lib/stoplight/light/runnable.rb +0 -127
data/lib/stoplight/notifier.rb +0 -6
data/spec/spec_helper.rb +0 -22
data/spec/stoplight/builder_spec.rb +0 -165
data/spec/stoplight/circuit_breaker_spec.rb +0 -43
data/spec/stoplight/color_spec.rb +0 -39
data/spec/stoplight/configurable_spec.rb +0 -25
data/spec/stoplight/data_store/base_spec.rb +0 -71
data/spec/stoplight/data_store/memory_spec.rb +0 -22
data/spec/stoplight/data_store/redis_spec.rb +0 -45
data/spec/stoplight/data_store_spec.rb +0 -9
data/spec/stoplight/default_spec.rb +0 -80
data/spec/stoplight/error_spec.rb +0 -39
data/spec/stoplight/failure_spec.rb +0 -108
data/spec/stoplight/light/lockable_spec.rb +0 -93
data/spec/stoplight/light/runnable_spec.rb +0 -38
data/spec/stoplight/light_spec.rb +0 -156
data/spec/stoplight/notifier/base_spec.rb +0 -18
data/spec/stoplight/notifier/generic_spec.rb +0 -50
data/spec/stoplight/notifier/io_spec.rb +0 -41
data/spec/stoplight/notifier/logger_spec.rb +0 -75
data/spec/stoplight/notifier_spec.rb +0 -9
data/spec/stoplight/state_spec.rb +0 -39
data/spec/stoplight/version_spec.rb +0 -9
data/spec/stoplight_spec.rb +0 -32
data/spec/support/configurable.rb +0 -69
data/spec/support/data_store/base/clear_failures.rb +0 -24
data/spec/support/data_store/base/clear_state.rb +0 -20
data/spec/support/data_store/base/get_all.rb +0 -44
data/spec/support/data_store/base/get_failures.rb +0 -30
data/spec/support/data_store/base/get_state.rb +0 -7
data/spec/support/data_store/base/names.rb +0 -29
data/spec/support/data_store/base/record_failures.rb +0 -70
data/spec/support/data_store/base/set_state.rb +0 -15
data/spec/support/data_store/base/with_notification_lock.rb +0 -27
data/spec/support/data_store/base.rb +0 -21
data/spec/support/database_cleaner.rb +0 -26
data/spec/support/exception_helpers.rb +0 -9
data/spec/support/light/runnable/color.rb +0 -79
data/spec/support/light/runnable/run.rb +0 -247
data/spec/support/light/runnable/state.rb +0 -31
data/spec/support/light/runnable.rb +0 -5

data/lib/stoplight/admin/views/index.erb ADDED Viewed

@@ -0,0 +1,36 @@
+<% if lights.empty? %>
+  <section class="bg-white dark:bg-gray-900">
+    <div class="py-8 px-4 mx-auto max-w-screen-xl text-center lg:py-16">
+      <div class="mx-auto mb-6 flex h-16 w-16 items-center justify-center rounded-full bg-blue-50 dark:bg-blue-900/20">
+        <svg class="lucide lucide-unplug-icon lucide-unplug w-8 h-8 text-blue-600 dark:text-blue-400" 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">
+          <path d="m19 5 3-3"/><path d="m2 22 3-3"/><path d="M6.3 20.3a2.4 2.4 0 0 0 3.4 0L12 18l-6-6-2.3 2.3a2.4 2.4 0 0 0 0 3.4Z"/><path d="M7.5 13.5 10 11"/><path d="M10.5 16.5 13 14"/><path d="m12 6 6 6 2.3-2.3a2.4 2.4 0 0 0 0-3.4l-2.6-2.6a2.4 2.4 0 0 0-3.4 0Z"/>
+        </svg>
+      </div>
+      <h2 class="mb-3 text-2xl font-semibold tracking-tight leading-none text-gray-900 md:text-5xl lg:text-6xl dark:text-white">
+        No lights found
+      </h2>
+      <div class="space-y-4">
+        <p class="mb-8 text-lg font-normal text-gray-500 lg:text-xl sm:px-16 lg:px-48 dark:text-gray-400">
+          Ensure that your Stoplight data store is properly configured and that your Stoplight blocks have been run.
+        </p>
+      </div>
+      <div class="flex flex-col space-y-4 sm:flex-row sm:justify-center sm:space-y-0">
+        <a href="javascript:location.reload();" class="inline-flex justify-center items-center py-3 px-5 text-base font-medium text-center text-white rounded-lg bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 dark:focus:ring-blue-900">
+          <svg 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" class="lucide lucide-refresh-ccw-icon lucide-refresh-ccw w-3.5 h-3.5 me-2">
+            <path d="M21 12a9 9 0 0 0-9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/><path d="M3 12a9 9 0 0 0 9 9 9.75 9.75 0 0 0 6.74-2.74L21 16"/><path d="M16 16h5v5"/>
+          </svg>
+          Refresh Lights
+        </a>
+      </div>
+    </div>
+  </section>
+<% else %>
+  <section class="grid gap-4" style="grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));">
+    <% lights.each do |light| %>
+      <%= erb :_card, locals: { light:, color: light.color } %>
+    <% end %>
+  </section>
+<% end %>

data/lib/stoplight/admin/views/layout.erb ADDED Viewed

@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <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">
+        document.addEventListener("turbo:load", () => {
+            window.initFlowbite()
+        })
+    </script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flowbite@3.1.2/dist/flowbite.min.css" />
+  </head>
+  <body>
+    <div class="antialiased bg-gray-50 dark:bg-gray-900">
+      <nav class="bg-white border-gray-200 dark:bg-gray-900">
+        <div class="max-w-screen-xl flex flex-wrap items-center justify-between mx-auto p-4">
+          <a href="<%= url('/') %>" class="flex items-center space-x-3 rtl:space-x-reverse">
+            🚦
+            <span class="self-center text-2xl font-semibold whitespace-nowrap dark:text-white">Stoplight Admin</span>
+          </a>
+          <button data-collapse-toggle="navbar-default" type="button" class="inline-flex items-center p-2 w-10 h-10 justify-center text-sm text-gray-500 rounded-lg md:hidden hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-gray-200 dark:text-gray-400 dark:hover:bg-gray-700 dark:focus:ring-gray-600" aria-controls="navbar-default" aria-expanded="false">
+            <span class="sr-only">Open main menu</span>
+            <svg class="w-5 h-5" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 17 14">
+              <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M1 1h15M1 7h15M1 13h15"/>
+            </svg>
+          </button>
+          <div class="hidden w-full md:block md:w-auto" id="navbar-default">
+            <ul class="font-medium flex flex-col p-4 md:p-0 mt-4 border border-gray-100 rounded-lg bg-gray-50 md:flex-row md:space-x-8 rtl:space-x-reverse md:mt-0 md:border-0 md:bg-white dark:bg-gray-800 md:dark:bg-gray-900 dark:border-gray-700">
+              <% if count_red + count_yellow > 0 %>
+                <li>
+                  <a href="<%= url('/green_all') %>" data-turbo-method="post" class="inline-flex items-center text-gray-900 bg-white border border-gray-300 focus:outline-none hover:bg-gray-100 focus:ring-4 focus:ring-gray-100 font-medium rounded-lg text-sm px-5 py-2.5 me-2 mb-2 dark:bg-gray-800 dark:text-white dark:border-gray-600 dark:hover:bg-gray-700 dark:hover:border-gray-600 dark:focus:ring-gray-700">
+                    <svg class="flex w-4 h-4 me-1.5 text-green-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">
+                      <circle cx="12" cy="16" r="1"/>
+                      <rect x="3" y="10" width="18" height="12" rx="2"/>
+                      <path d="M7 10V7a5 5 0 0 1 10 0v3"/>
+                    </svg>
+                    Lock All Green
+                  </a>
+                </li>
+              <% end %>
+            </ul>
+          </div>
+        </div>
+      </nav>
+      <main class="p-4 md:ml-64 h-auto">
+        <%= yield %>
+      </main>
+      <footer class="bg-white rounded-lg shadow-sm dark:bg-gray-900 m-4">
+        <div class="w-full max-w-screen-xl mx-auto p-4 md:py-8">
+          <p class="block text-sm text-gray-500 sm:text-center dark:text-gray-400 mb-2">All of the Lights -- cop lights, flashlights, spotlights, strobe lights...</p>
+          <p class="block text-sm text-gray-500 sm:text-center dark:text-gray-400">💡 🔦 🚨 🚥 💫</p>
+        </div>
+      </footer>
+    </div>
+    <script src="https://cdn.jsdelivr.net/npm/flowbite@3.1.2/dist/flowbite.min.js"></script>
+  </body>
+</html>

data/lib/stoplight/admin.rb ADDED Viewed

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+begin
+  require "sinatra"
+  require "sinatra/contrib"
+  require "sinatra/base"
+  require "sinatra/json"
+rescue LoadError
+  raise <<~WARN
+    "sinatra" and "sinatra-contrib" gems are unavailable and necessery for running Stoplight Admin panel
+    Please add them to your Gemfile and run `bundle install`:
+      gem "sinatra", required: false
+      gem "sinatra-contrib", require: false
+  WARN
+end
+module Stoplight
+  class Admin < Sinatra::Base
+    COLORS = [
+      GREEN = Stoplight::Color::GREEN,
+      YELLOW = Stoplight::Color::YELLOW,
+      RED = Stoplight::Color::RED
+    ].freeze
+    private_constant :COLORS
+    helpers Helpers
+    set :protection, except: %i[json_csrf]
+    set :data_store, proc { Stoplight.config_provider.data_store }
+    set :views, File.join(__dir__, "admin", "views")
+    get "/" do
+      lights, stats = dependencies.stats_action.call
+      erb :index, locals: stats.merge(lights: lights)
+    end
+    get "/stats" do
+      lights, stats = dependencies.stats_action.call
+      json({stats: stats, lights: lights.map(&:as_json)})
+    end
+    post "/unlock" do
+      dependencies.unlock_action.call(params)
+      redirect to("/")
+    end
+    post "/green" do
+      dependencies.green_action.call(params)
+      redirect to("/")
+    end
+    post "/red" do
+      dependencies.red_action.call(params)
+      redirect to("/")
+    end
+    post "/green_all" do
+      dependencies.green_all_action.call
+      redirect to("/")
+    end
+  end
+end

data/lib/stoplight/color.rb CHANGED Viewed

@@ -2,8 +2,8 @@
 module Stoplight
   module Color
-    GREEN = 'green'
-    YELLOW = 'yellow'
-    RED = 'red'
+    GREEN = "green"
+    YELLOW = "yellow"
+    RED = "red"
   end
 end

data/lib/stoplight/config/config_provider.rb ADDED Viewed

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+module Stoplight
+  module Config
+    # Provides configuration for a Stoplight light by its name.
+    #
+    # It combines settings from three sources in the following order of precedence:
+    # 1. **Settings Overrides**: Explicit settings passed as arguments to +#provide+ method.
+    # 2. **User-level Default Settings**: Settings defined using the +Stoplight.configure+ method.
+    # 4. **Library-Level Default Settings**: Default settings defined in the +Stoplight::Config::UserDefaultConfig+ module.
+    #
+    # The settings are merged in this order, with higher-precedence settings overriding lower-precedence ones.
+    #
+    # @api private
+    class ConfigProvider
+      # @!attribute [r] default_settings
+      #   @return [Hash]
+      private attr_reader :default_settings
+      # @param user_default_config [Stoplight::Config::UserDefaultConfig]
+      # @param library_default_config [Stoplight::Config::LibraryDefaultConfig]
+      # @raise [Error::ConfigurationError] if both user_default_config and legacy_config are not empty
+      def initialize(user_default_config:, library_default_config:)
+        @default_settings = library_default_config.to_h.merge(
+          user_default_config.to_h
+        )
+      end
+      # @return [Stoplight::DataStore::Base]
+      def data_store
+        default_settings.fetch(:data_store)
+      end
+      # Returns a configuration for a specific light with the given name and settings overrides.
+      #
+      # @param light_name [Symbol, String] The name of the light.
+      # @param settings_overrides [Hash] The settings to override.
+      #   @see +Stoplight()+
+      # @return [Stoplight::Light::Config] The configuration for the specified light.
+      # @raise [Error::ConfigurationError]
+      def provide(light_name, **settings_overrides)
+        raise Error::ConfigurationError, <<~ERROR if settings_overrides.has_key?(:name)
+          The +name+ setting cannot be overridden in the configuration.
+        ERROR
+        settings = default_settings.merge(settings_overrides, {name: light_name})
+        Light::Config.new(**settings)
+      end
+      def inspect
+        "#<#{self.class.name} " \
+          "cool_off_time=#{default_settings[:cool_off_time]}, " \
+          "threshold=#{default_settings[:threshold]}, " \
+          "window_size=#{default_settings[:window_size]}, " \
+          "tracked_errors=#{default_settings[:tracked_errors].join(",")}, " \
+          "skipped_errors=#{default_settings[:skipped_errors].join(",")}, " \
+          "data_store=#{default_settings[:data_store].class.name}" \
+        ">"
+      end
+    end
+  end
+end

data/lib/stoplight/config/library_default_config.rb ADDED Viewed

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+module Stoplight
+  module Config
+    # Provides default settings for the Stoplight library.
+    # @api private
+    class LibraryDefaultConfig
+      DEFAULT_SETTINGS = {
+        cool_off_time: Stoplight::Default::COOL_OFF_TIME,
+        data_store: Stoplight::Default::DATA_STORE,
+        error_notifier: Stoplight::Default::ERROR_NOTIFIER,
+        notifiers: Stoplight::Default::NOTIFIERS,
+        threshold: Stoplight::Default::THRESHOLD,
+        window_size: Stoplight::Default::WINDOW_SIZE,
+        tracked_errors: Stoplight::Default::TRACKED_ERRORS,
+        skipped_errors: Stoplight::Default::SKIPPED_ERRORS,
+        traffic_control: Stoplight::Default::TRAFFIC_CONTROL,
+        traffic_recovery: Stoplight::Default::TRAFFIC_RECOVERY
+      }.freeze
+      private_constant :DEFAULT_SETTINGS
+      # Returns library default settings.
+      # @return [Hash]
+      def to_h
+        DEFAULT_SETTINGS
+      end
+    end
+  end
+end

data/lib/stoplight/config/user_default_config.rb ADDED Viewed

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+require "forwardable"
+module Stoplight
+  module Config
+    # Represents user-defined default configuration for Stoplight.
+    #
+    # This class allows users to define default settings for various Stoplight
+    # parameters, such as cool-off time, data store, error notifier, and more.
+    # TODO: add evaluation/recovery strategy support
+    class UserDefaultConfig
+      extend Forwardable
+      # @!attribute [w] cool_off_time
+      #   @return [Integer, nil] The default cool-off time in seconds.
+      attr_writer :cool_off_time
+      # @!attribute [w] error_notifier
+      #   @return [Proc, nil] The default error notifier (callable object).
+      attr_writer :error_notifier
+      # @!attribute [r] notifiers
+      #   @return [Array<Stoplight::Notifier::Base>] The default list of notifiers.
+      attr_reader :notifiers
+      # @!attribute [w] threshold
+      #   @return [Integer, nil] The default failure threshold to trip the circuit breaker.
+      attr_writer :threshold
+      # @!attribute [w] window_size
+      #   @return [Integer, nil] The default size of the rolling window for failure tracking.
+      attr_writer :window_size
+      # @!attribute [w] tracked_errors
+      #   @return [Array<Class>, nil] The default list of errors to track.
+      attr_writer :tracked_errors
+      # @!attribute [w] skipped_errors
+      #   @return [Array<Class>, nil] The default list of errors to skip.
+      attr_writer :skipped_errors
+      def initialize
+        # This allows users appending notifiers to the default list,
+        # while still allowing them to override the default list.
+        @notifiers = Default::NOTIFIERS
+      end
+      # @param value [Stoplight::DataStore::Base]
+      # @return [Stoplight::DataStore::Base] The default data store instance.
+      def data_store=(value)
+        @data_store = DataStore::FailSafe.wrap(value)
+      end
+      # @param value [Array<Stoplight::Notifier::Base>]
+      # @return [Array<Stoplight::Notifier::FailSafe>]
+      def notifiers=(value)
+        @notifiers = value.map { |notifier| Notifier::FailSafe.wrap(notifier) }
+      end
+      # Converts the user-defined configuration to a hash.
+      #
+      # @return [Hash] A hash representation of the configuration, excluding nil values.
+      # @api private
+      def to_h
+        {
+          cool_off_time: @cool_off_time,
+          data_store: @data_store,
+          error_notifier: @error_notifier,
+          notifiers: (@notifiers == Default::NOTIFIERS) ? nil : @notifiers, # This is to avoid conflicts with legacy config
+          threshold: @threshold,
+          window_size: @window_size,
+          tracked_errors: @tracked_errors,
+          skipped_errors: @skipped_errors
+        }.compact
+      end
+      # @return [Boolean] True if the configuration hash is not empty, false otherwise.
+      # @api private
+      def_delegator :to_h, :any?
+    end
+  end
+end

data/lib/stoplight/data_store/base.rb CHANGED Viewed

@@ -4,61 +4,87 @@ module Stoplight
   module DataStore
     # @abstract
     class Base
-      # @return [Array<String>]
-      def names
-        raise NotImplementedError
-      end
+      METRICS_RETENTION_TIME = 60 * 60 * 24 # 1 day
-      # @param _light [Light]
-      # @return [Array(Array<Failure>, String)]
-      def get_all(_light)
+      # Retrieves the names of all lights stored in the data store.
+      #
+      # @return [Array<String>] An array of light names.
+      def names
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @return [Array<Failure>]
-      def get_failures(_light)
+      # Retrieves metadata 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)
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @param _failure [Failure]
-      # @return [Fixnum]
-      def record_failure(_light, _failure)
+      # 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)
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @return [Array<Failure>]
-      def clear_failures(_light)
+      # Records a success for a specific light configuration.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @return [void]
+      def record_success(config)
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @return [String]
-      def get_state(_light)
+      # Records a failed recovery probe for a specific light configuration.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @param failure [Failure]
+      # @return [Stoplight::Metadata]
+      def record_recovery_probe_failure(config, failure)
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @param _state [String]
-      # @return [String]
-      def set_state(_light, _state)
+      # Records a successful recovery probe for a specific light configuration.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @return [Stoplight::Metadata]
+      def record_recovery_probe_success(config)
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @return [String]
-      def clear_state(_light)
+      # Sets the state of a specific light configuration.
+      #
+      # @param config [Stoplight::Light::Config]
+      # @param state [String] The new state to set.
+      # @return [String] The state that was set.
+      def set_state(config, state)
         raise NotImplementedError
       end
-      # @param _light [Light]
-      # @param _from_color [String]
-      # @param _to_color [String]
-      # @yield _block
-      # @return [Void]
-      def with_notification_lock(_light, _from_color, _to_color, &_block)
+      # Transitions the Stoplight to the specified color.
+      #
+      # This method performs a color transition operation that works across distributed instances
+      # of the light. It ensures that in a multi-instance environment, only one instance
+      # is considered the "first" to perform the transition (and therefore responsible for
+      # triggering notifications).
+      #
+      # @param config [Stoplight::Light::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.
+      #
+      # @return [Boolean] Returns +true+ if this instance was the first to perform this specific transition
+      #   (and should therefore trigger notifications). Returns +false+ if another instance already
+      #   initiated this transition.
+      #
+      # @note In distributed environments with multiple instances, race conditions can occur when instances
+      #   attempt conflicting transitions simultaneously (e.g., one instance tries to transition from
+      #   YELLOW to GREEN while another tries YELLOW to RED). The implementation handles this, but
+      #   be aware that the last operation may determine the final color of the light.
+      #
+      def transition_to_color(config, color)
         raise NotImplementedError
       end
     end

data/lib/stoplight/data_store/fail_safe.rb ADDED Viewed

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+module Stoplight
+  module DataStore
+    # A wrapper around a data store that provides fail-safe mechanisms using a
+    # circuit breaker. It ensures that operations on the data store can gracefully
+    # handle failures by falling back to default values when necessary.
+    #
+    # @api private
+    class FailSafe < Base
+      # @!attribute [r] data_store
+      #   @return [Stoplight::DataStore::Base] The underlying data store being wrapped.
+      protected attr_reader :data_store
+      # @!attribute [r] circuit_breaker
+      #   @return [Stoplight] The circuit breaker used to handle failures.
+      private attr_reader :circuit_breaker
+      class << self
+        # Wraps a data store with fail-safe mechanisms.
+        #
+        # @param data_store [Stoplight::DataStore::Base] The data store to wrap.
+        # @return [Stoplight::DataStore::Base, FailSafe] The original data store if it is already
+        #   a +Memory+ or +FailSafe+ instance, otherwise a new +FailSafe+ instance.
+        def wrap(data_store)
+          case data_store
+          when Memory, FailSafe
+            data_store
+          else
+            new(data_store)
+          end
+        end
+      end
+      # @param data_store [Stoplight::DataStore::Base]
+      def initialize(data_store)
+        @data_store = data_store
+        @circuit_breaker = Stoplight("stoplight:data_store:fail_safe:#{data_store.class.name}", data_store: Default::DATA_STORE)
+      end
+      def names
+        with_fallback([]) do
+          data_store.names
+        end
+      end
+      def get_metadata(config)
+        with_fallback(Metadata.new, config) do
+          data_store.get_metadata(config)
+        end
+      end
+      def record_failure(config, failure)
+        with_fallback(nil, config) do
+          data_store.record_failure(config, failure)
+        end
+      end
+      def record_success(config, **args)
+        with_fallback(nil, config) do
+          data_store.record_success(config, **args)
+        end
+      end
+      def record_recovery_probe_success(config, **args)
+        with_fallback(nil, config) do
+          data_store.record_recovery_probe_success(config, **args)
+        end
+      end
+      def record_recovery_probe_failure(config, failure)
+        with_fallback(nil, config) do
+          data_store.record_recovery_probe_failure(config, failure)
+        end
+      end
+      def set_state(config, state)
+        with_fallback(State::UNLOCKED, config) do
+          data_store.set_state(config, state)
+        end
+      end
+      def transition_to_color(config, color)
+        with_fallback(false, config) do
+          data_store.transition_to_color(config, color)
+        end
+      end
+      def ==(other)
+        other.is_a?(self.class) && other.data_store == data_store
+      end
+      # @param default [Object, nil]
+      # @param config [Stoplight::Light::Config]
+      private def with_fallback(default = nil, config = nil, &code)
+        fallback = proc do |error|
+          config.error_notifier.call(error) if config && error
+          default
+        end
+        circuit_breaker.run(fallback, &code)
+      end
+    end
+  end
+end