stoplight 5.0.2 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33957e89681161b7eee07f1ea96544341f0be3b988a53609829450f13a5840e9
-  data.tar.gz: cdad58020fe3e1e85b2705cc6d0b1fc733b994717860c911dfab0c9a375b074d
+  metadata.gz: 2fba85e77b2b2c6569592f463080da2bca787dc65f12da00bf566b4bb7e56912
+  data.tar.gz: 4aaac27c0747de8a550575ecd8a93cc2391f3a73c008c543ee049db6f7fd01b7
 SHA512:
-  metadata.gz: e97d13c334f95e586dd561ad3ba3c2a5e7c3f37ef830efca794e1bde280f8f22ebbf3baa02efc61f0978dde42d9d6551aafdef6d1d35f8d2589d7d18c46b84ca
-  data.tar.gz: e0841a8040fc194c1b271f0dad0550200ea1bc73982545d7143e77c5e4eb867d6b4f9d94d1f5e292833ce1cd3091a6839bfc66b6a62d78ea73468735c6f09ead
+  metadata.gz: acc5305b5da510feacb9584a60a6043eb4c7c7280bbf6f3d6c77db968a445aa45fcfaaaf41027684ff9dc7f4ebf615b1f27e0d53315eda932126b6c47b5ca514
+  data.tar.gz: 1ce0b8d4fea66779d6688c52a871ac10568184f796fc3d51a08c9d6fb45e2402b59da077cbcdd049b1dcdc9e2e748ebdde9ebd327b28aa810190b6bf8d17049c

data/README.md

@@ -128,18 +128,23 @@ receives `nil`. In both cases, the return value of the fallback becomes the retu
 
 Stoplight goes 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.
 
-To add Admin Panel to your Rails project, add this configuration to your `config/routes.rb` file.
+To add Admin Panel protected by basic authentication to your Rails project, add this configuration to your `config/routes.rb` file.
 
 ```ruby
 Rails.application.routes.draw do
   # ...
 
+  Stoplight::Admin.use(Rack::Auth::Basic) do |username, password|
+    username == ENV["STOPLIGHT_ADMIN_USERNAME"] && password == ENV["STOPLIGHT_ADMIN_PASSWORD"]
+  end
   mount Stoplight::Admin => '/stoplights'
 
   # ...
 end
 ```
 
+Then set up `STOPLIGHT_ADMIN_USERNAME` and `STOPLIGHT_ADMIN_PASSWORD` env variables to access your Admin panel.
+
 **IMPORTANT:** Stoplight Admin Panel requires you to have `sinatra` and `sinatra-contrib` gems installed. You can either add them to your Gemfile:
 
 ```ruby
@@ -158,13 +163,13 @@ gem install sinatra-contrib
 It is possible to run the Admin Panel separately from your application using the `stoplight-admin:<release-version>` docker image.
 
 ```shell
-docker run --net=host stoplight-admin:v5
+docker run --net=host bolshakov/stoplight-admin
 ```
 
 **IMPORTANT:** Standalone Admin Panel should use the same Redis your application uses. To achieve this, set the `REDIS_URL` ENV variable via `-e REDIS_URL=<url-to-your-redis-servier>.` E.g.:
 
 ```shell
-docker run -e REDIS_URL=redis://localhost:6378  --net=host stoplight-admin:v5
+docker run -e REDIS_URL=redis://localhost:6378  --net=host bolshakov/stoplight-admin
 ```
 
 
@@ -384,6 +389,12 @@ Stoplight.configure do |config|
 end
 ```
 
+You can generate initializer with Redis, Admin Panel route and add needed gems to your Gemfile:
+
+```sh
+rails generate stoplight:install --with-admin-panel
+```
+
 ## Testing
 
 Tips for working with Stoplight in test environments:
@@ -416,6 +427,12 @@ Stoplight supports the latest three minor versions of Ruby, which currently are:
 the minimum supported Ruby version is not considered a breaking change. We support the current stable Redis 
 version (`7.4.x`) and the latest release of the previous major version (`6.2.x`)
 
+## Development
+
+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.
+
 ## Credits
 
 Stoplight was originally created by [camdez][] and [tfausak][]. It is currently maintained by [bolshakov][] and
@@ -444,3 +461,4 @@ Fowler’s [CircuitBreaker][] article.
 [complete list of contributors]: https://github.com/bolshakov/stoplight/graphs/contributors
 [CircuitBreaker]: http://martinfowler.com/bliki/CircuitBreaker.html
 [Redis]: https://redis.io/
+[Git Flow wiki page]: https://github.com/bolshakov/stoplight/wiki/Git-Flow

data/lib/generators/stoplight/install/USAGE

@@ -0,0 +1,16 @@
+Description:
+  Generates stoplight initializer to setup Stoplight Redis configuration
+    and optionally sets up Admin panel
+  
+Examples:
+  rails generate stoplight:install
+
+    This will generate "config/initializers/stoplight.rb" initializer with basic config
+    Then you should adjust Redis config there.
+
+  rails generate stoplight:install --with-admin-panel
+
+    This generated all needed requirements to set up Stoplight Admin Panel:
+    * It generates initializer "config/initializers/stoplight.rb" with Redis configuration
+    * It injects your "config/routes.rb" with route with basic authentication to Stoplight Admin panel
+    * It injects your Gemfile with needed dependencies ('redis', 'sinatra' and 'sinatra-contrib')

data/lib/generators/stoplight/install/install_generator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+begin
+  require "rails/generators"
+rescue LoadError
+  raise <<~WARN
+    Currently generators are only available for Rails applications
+  WARN
+end
+
+module Stoplight
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base # :nodoc:
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :with_admin_panel, type: :boolean, optional: true,
+        desc: "Define whether to set up admin panel"
+
+      ROUTES_PATH = "config/routes.rb"
+      STOPLIGHT_CONFIG_TEMPLATE = "stoplight.rb.erb"
+      INITIALIZERS_PATH = "config/initializers"
+      AFTER_INSTALL_NOTIFICATION = <<~TEXT
+        \nThank you for using stoplight!
+        Now to finish configuration:
+        * Run `bundle` from the project root to install new gems
+        * Go to 'config/initializers/stoplight.rb' to set up connection to Redis.\n
+      TEXT
+
+      STOPLIGHT_ADMIN_ROUTE = <<-RUBY
+  mount Stoplight::Admin => '/stoplights'
+      RUBY
+
+      STOPLIGHT_AUTH = <<-RUBY
+  Stoplight::Admin.use(Rack::Auth::Basic) do |username, password|
+    username == ENV["STOPLIGHT_ADMIN_USERNAME"] && password == ENV["STOPLIGHT_ADMIN_PASSWORD"]
+  end
+      RUBY
+
+      def generate_redis_gem
+        if options[:with_admin_panel]
+          conf = "\ngem 'redis'"
+          inject_into_file "Gemfile", conf
+        end
+      end
+
+      def generate_sinatra_deps
+        if options[:with_admin_panel]
+          conf = <<~RUBY
+            gem 'sinatra', require: false
+            gem 'sinatra-contrib', require: false
+          RUBY
+
+          inject_into_file "Gemfile", "\n#{conf}"
+        end
+      end
+
+      def generate_initializer
+        initializer_template = STOPLIGHT_CONFIG_TEMPLATE
+        copy_file initializer_template, "#{INITIALIZERS_PATH}/stoplight.rb"
+      end
+
+      def generate_admin_panel
+        if options[:with_admin_panel]
+          route_config = "#{STOPLIGHT_AUTH}#{STOPLIGHT_ADMIN_ROUTE}\n"
+
+          inject_into_file ROUTES_PATH, route_config, after: ".application.routes.draw do\n"
+        end
+      end
+
+      def redis_configuration_notification
+        print AFTER_INSTALL_NOTIFICATION
+      end
+    end
+  end
+end

data/lib/generators/stoplight/install/templates/stoplight.rb.erb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "redis"
+
+# Set up your project-specific Redis setup here
+# One of the simplest configurations would be configuring Redis via url
+# Example:
+#   redis = Redis.new(url: ENV["REDIS_URL"])
+# REDIS_URL usually looks like this
+#   "redis://<username>:<password>@<server ip address>:<port>/<redis db>"
+# Example:
+#   "redis://admin:p4ssw0rd@10.0.1.1:6380/15"
+redis = Redis.new
+data_store = Stoplight::DataStore::Redis.new(redis)
+
+Stoplight.configure do |config|
+  config.data_store = data_store
+end

data/lib/stoplight/admin.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 begin
-  require "sinatra"
-  require "sinatra/contrib"
   require "sinatra/base"
+  require "sinatra/contrib"
   require "sinatra/json"
 rescue LoadError
   raise <<~WARN

data/lib/stoplight/config/config_provider.rb

@@ -10,6 +10,8 @@ module Stoplight
     # 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.
+    # After merging settings, the configuration transformations are applied such as wrapping data stores and notifiers
+    # with fail-safe mechanism, type conversion, etc. Each transformation must be idempotent.
     #
     # @api private
     class ConfigProvider
@@ -38,13 +40,28 @@ module Stoplight
       #   @see +Stoplight()+
       # @return [Stoplight::Light::Config] The configuration for the specified light.
       # @raise [Error::ConfigurationError]
-      def provide(light_name, **settings_overrides)
+      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)
+        Light::Config.new(**transform_settings(settings))
+      end
+
+      # Creates a configuration from a given +Stoplight::Light::Config+ object extending it
+      # with additional settings overrides.
+      #
+      # @param config [Stoplight::Light::Config] The configuration object to extend.
+      # @param settings_overrides [Hash] The settings to override.
+      # @return [Stoplight::Light::Config] The new extended configuration object.
+      def from_prototype(config, settings_overrides)
+        config.to_h.then do |settings|
+          current_name = settings.delete(:name)
+          name = settings_overrides.delete(:name) || current_name
+
+          provide(name, **settings.merge(settings_overrides))
+        end
       end
 
       def inspect
@@ -57,6 +74,38 @@ module Stoplight
           "data_store=#{default_settings[:data_store].class.name}" \
         ">"
       end
+
+      private
+
+      def transform_settings(settings)
+        settings.merge(
+          data_store: build_data_store(settings.fetch(:data_store)),
+          notifiers: build_notifiers(settings.fetch(:notifiers)),
+          tracked_errors: build_tracked_errors(settings.fetch(:tracked_errors)),
+          skipped_errors: build_skipped_errors(settings.fetch(:skipped_errors)),
+          cool_off_time: build_cool_off_time(settings.fetch(:cool_off_time))
+        )
+      end
+
+      def build_data_store(data_store)
+        DataStore::FailSafe.wrap(data_store)
+      end
+
+      def build_notifiers(notifiers)
+        notifiers.map { |notifier| Notifier::FailSafe.wrap(notifier) }
+      end
+
+      def build_tracked_errors(tracked_error)
+        Array(tracked_error)
+      end
+
+      def build_skipped_errors(skipped_errors)
+        Array(skipped_errors)
+      end
+
+      def build_cool_off_time(cool_off_time)
+        cool_off_time.to_i
+      end
     end
   end
 end

data/lib/stoplight/config/user_default_config.rb

@@ -20,9 +20,9 @@ module Stoplight
       #   @return [Proc, nil] The default error notifier (callable object).
       attr_writer :error_notifier
 
-      # @!attribute [r] notifiers
+      # @!attribute [rw] notifiers
       #   @return [Array<Stoplight::Notifier::Base>] The default list of notifiers.
-      attr_reader :notifiers
+      attr_accessor :notifiers
 
       # @!attribute [w] threshold
       #   @return [Integer, nil] The default failure threshold to trip the circuit breaker.
@@ -40,24 +40,16 @@ module Stoplight
       #   @return [Array<Class>, nil] The default list of errors to skip.
       attr_writer :skipped_errors
 
+      # @!attribute [w] data_store
+      #   @return [Stoplight::DataStore::Base] The default data store instance.
+      attr_writer :data_store
+
       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.
@@ -67,7 +59,7 @@ module Stoplight
           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
+          notifiers: @notifiers,
           threshold: @threshold,
           window_size: @window_size,
           tracked_errors: @tracked_errors,

data/lib/stoplight/data_store/fail_safe.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Stoplight
   module DataStore
     # A wrapper around a data store that provides fail-safe mechanisms using a

data/lib/stoplight/default.rb

@@ -14,9 +14,7 @@ module Stoplight
       words.join(" ")
     end
 
-    NOTIFIERS = [
-      Notifier::FailSafe.wrap(Notifier::IO.new($stderr))
-    ].freeze
+    NOTIFIERS = [Notifier::IO.new($stderr)].freeze
 
     THRESHOLD = 3
 

data/lib/stoplight/light/config.rb

@@ -3,85 +3,56 @@
 module Stoplight
   class Light
     # A +Stoplight::Light+ configuration object.
+    #
+    # # @!attribute [r] name
+    #   @return [String]
+    #
+    # @!attribute [r] cool_off_time
+    #   @return [Numeric]
+    #
+    # @!attribute [r] data_store
+    #   @return [Stoplight::DataStore::Base]
+    #
+    # @!attribute [r] error_notifier
+    #   @return [StandardError => void]
+    #
+    # @!attribute [r] notifiers
+    #   @return [Array<Stoplight::Notifier::Base>]
+    #
+    # @!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>]
+    #
+    # @!attribute [r] traffic_control
+    #  @return [Stoplight::TrafficControl::Base]
+    #
+    # @!attribute [r] traffic_recovery
+    #   @return [Stoplight::TrafficRecovery::Base]
     # @api private
-    class Config
-      # @!attribute [r] name
-      #   @return [String]
-      attr_reader :name
-
-      # @!attribute [r] cool_off_time
-      #   @return [Numeric]
-      attr_reader :cool_off_time
-
-      # @!attribute [r] data_store
-      #   @return [Stoplight::DataStore::Base]
-      attr_reader :data_store
-
-      # @!attribute [r] error_notifier
-      #   @return [StandardError => void]
-      attr_reader :error_notifier
-
-      # @!attribute [r] notifiers
-      #   @return [Array<Stoplight::Notifier::Base>]
-      attr_reader :notifiers
-
-      # @!attribute [r] threshold
-      #   @return [Numeric]
-      attr_reader :threshold
-
-      # @!attribute [r] window_size
-      #   @return [Numeric]
-      attr_reader :window_size
-
-      # @!attribute [r] tracked_errors
-      #   @return [Array<StandardError>]
-      attr_reader :tracked_errors
-
-      # @!attribute [r] skipped_errors
-      #  @return [Array<Exception>]
-      attr_reader :skipped_errors
-
-      # @!attribute [r] traffic_control
-      #  @return [Stoplight::TrafficControl::Base]
-      attr_reader :traffic_control
-
-      # @!attribute [r] traffic_recovery
-      #   @return [Stoplight::TrafficRecovery::Base]
-      attr_reader :traffic_recovery
-
-      # @param name [String]
-      # @param cool_off_time [Numeric]
-      # @param data_store [Stoplight::DataStore::Base]
-      # @param error_notifier [Proc]
-      # @param notifiers [Array<Stoplight::Notifier::Base>]
-      # @param threshold [Numeric]
-      # @param window_size [Numeric]
-      # @param tracked_errors [Array<StandardError>]
-      # @param skipped_errors [Array<Exception>]
-      # @param traffic_control [Stoplight::TrafficControl::Base]
-      # @param traffic_recovery [Stoplight::TrafficRecovery::Base]
-      def initialize(name:, cool_off_time:, data_store:, error_notifier:, notifiers:, threshold:, window_size:,
-        tracked_errors:, skipped_errors:, traffic_control:, traffic_recovery:)
-        @name = name
-        @cool_off_time = cool_off_time.to_i
-        @data_store = DataStore::FailSafe.wrap(data_store)
-        @error_notifier = error_notifier
-        @notifiers = notifiers.map { |notifier| Notifier::FailSafe.wrap(notifier) }
-        @threshold = threshold
-        @window_size = window_size
-        @tracked_errors = Array(tracked_errors)
-        @skipped_errors = Array(skipped_errors)
-        @traffic_control = traffic_control
-        @traffic_recovery = traffic_recovery
-      end
-
-      # @param other [any]
-      # @return [Boolean]
-      def ==(other)
-        other.is_a?(self.class) && to_h == other.to_h
-      end
-
-      # @param error [Exception]
+    Config = Data.define(
+      :name,
+      :cool_off_time,
+      :data_store,
+      :error_notifier,
+      :notifiers,
+      :threshold,
+      :window_size,
+      :tracked_errors,
+      :skipped_errors,
+      :traffic_control,
+      :traffic_recovery
+    ) do
+      # 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 }
@@ -89,30 +60,6 @@ module Stoplight
 
         !skip && track
       end
-
-      # Updates the configuration with new settings and returns a new instance.
-      #
-      # @return [Stoplight::Light::Config]
-      def with(**settings)
-        self.class.new(**to_h.merge(settings))
-      end
-
-      # @return [Hash]
-      def to_h
-        {
-          cool_off_time:,
-          data_store:,
-          error_notifier:,
-          name:,
-          notifiers:,
-          threshold:,
-          window_size:,
-          tracked_errors:,
-          skipped_errors:,
-          traffic_control:,
-          traffic_recovery:
-        }
-      end
     end
   end
 end

data/lib/stoplight/light.rb

@@ -150,7 +150,9 @@ module Stoplight
     #   payment_light.run(->(error) { nil }) { call_payment_api }
     # @see +Stoplight()+
     def with(**settings)
-      reconfigure(config.with(**settings))
+      reconfigure(
+        Stoplight.config_provider.from_prototype(config, settings)
+      )
     end
 
     private

data/lib/stoplight/traffic_control/base.rb

@@ -30,6 +30,12 @@ module Stoplight
       def stop_traffic?(config, metadata)
         raise NotImplementedError
       end
+
+      # @param other [any]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class)
+      end
     end
   end
 end

data/lib/stoplight/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stoplight
-  VERSION = Gem::Version.new("5.0.2")
+  VERSION = Gem::Version.new("5.1.0")
 end

data/lib/stoplight.rb

@@ -9,6 +9,7 @@ loader.do_not_eager_load(
   "#{__dir__}/stoplight/admin",
   "#{__dir__}/stoplight/admin.rb"
 )
+loader.ignore("#{__dir__}/generators")
 loader.ignore("#{__dir__}/stoplight/rspec.rb", "#{__dir__}/stoplight/rspec")
 loader.setup
 
@@ -26,7 +27,7 @@ module Stoplight # rubocop:disable Style/Documentation
     # It raises an error if called more than once.
     #
     # @yield [config] Provides a configuration object to the block.
-    # @yieldparam config [Stoplight::Config::ProgrammaticConfig] The configuration object.
+    # @yieldparam config [Stoplight::Config::UserDefaultConfig] The configuration object.
     # @raise [Stoplight::Error::ConfigurationError] If the library is already configured.
     # @return [void]
     #
@@ -118,6 +119,6 @@ end
 #   light = Stoplight("Payment API", skipped_errors: [ActiveRecord::RecordNotFound])
 #
 def Stoplight(name, **settings) # rubocop:disable Naming/MethodName
-  config = Stoplight.config_provider.provide(name, **settings)
+  config = Stoplight.config_provider.provide(name, settings)
   Stoplight::Light.new(config)
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 5.0.2
+  version: 5.1.0
 platform: ruby
 authors:
 - Cameron Desautels
 - Taylor Fausak
 - Justin Steffy
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-22 00:00:00.000000000 Z
+date: 2025-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -37,6 +38,9 @@ files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
+- lib/generators/stoplight/install/USAGE
+- lib/generators/stoplight/install/install_generator.rb
+- lib/generators/stoplight/install/templates/stoplight.rb.erb
 - lib/stoplight.rb
 - lib/stoplight/admin.rb
 - lib/stoplight/admin/actions/action.rb
@@ -98,6 +102,7 @@ homepage: https://github.com/bolshakov/stoplight
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -112,7 +117,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Traffic control for code.
 test_files: []