stoplight 5.3.1 → 5.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d9c236d51c7ba9b67ccbc0be19c1836b90b2a1b1f6b9e38cdfcfa28cfd85d5e
-  data.tar.gz: 85f04de041217bfd4ad1d0892d637847db62dba16e3dab8b00b5cb87b0c73725
+  metadata.gz: c930c989a3184cfc4fb254c720a854caf34fb56bbb550df150d65125969240b2
+  data.tar.gz: 3ca98448ca2a378d6101e4b10e4567adb24bc65c2747d77bccf4b9386aeba64c
 SHA512:
-  metadata.gz: 6c5f9dfe0b88fb11ce8e2f830d73101ad39ed5a3c398d08e0ab4afd90c55246a4f62717f1eca4c1e463669ef123d8496e8525fc935b84f323ec7c15469d1db24
-  data.tar.gz: 267bac02ac372e70646820ffee6e6209fe6de8fd26658c2975cd08f079676cb5862e41a5154e1f58d6897f4ede79b5284fad1678310cc458867fcedc5466f874
+  metadata.gz: caf3fbc0b32e823a3877525841ab46948fdedbda6791da8006ded3c194229aad7add1c01df82f60b406606a34481a40535662036b2f21caf1ea953ed58ae3eab
+  data.tar.gz: 0d372655a21b4f2ebf04973a6fa41ae4e24e1bab2851bfef69c6ba866a2e38231cdc2a13f4c3afb7a267f56c7a5e3040d88c4ce0602f6b4392b9216fd57d6f2a

data/README.md

@@ -3,9 +3,8 @@
 [![Version badge][]][version]
 [![Build badge][]][build]
 [![Coverage badge][]][coverage]
-[![Climate badge][]][climate]
 
-Stoplight is traffic control for code. It's an implementation of the circuit breaker pattern in Ruby.
+Stoplight is a traffic control for code. It's an implementation of the circuit breaker pattern in Ruby.
 
 ---
 
@@ -103,7 +102,7 @@ light.color # => "red"
 After one minute, the light transitions to yellow, allowing a test execution:
 
 ```ruby
-# Wait for the cool off time
+# Wait for the cool-off time
 sleep 60
 light.run { 1 / 1 } #=> 1
 ```
@@ -130,7 +129,7 @@ receives `nil`. In both cases, the return value of the fallback becomes the retu
 
 ## Admin Panel
 
-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.
+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.
 
 To add Admin Panel protected by basic authentication to your Rails project, add this configuration to your `config/routes.rb` file.
 
@@ -378,7 +377,12 @@ single successful recovery probe will resume traffic flow.
 
 ### Data Store
 
-Stoplight uses an in-memory data store out of the box:
+Stoplight officially supports three data stores:
+- In-memory data store
+- Redis
+- Valkey
+
+By default, Stoplight uses an in-memory data store:
 
 ```ruby
 require "stoplight"
@@ -386,7 +390,9 @@ Stoplight::Default::DATA_STORE
 # => #<Stoplight::DataStore::Memory:...>
 ```
 
-For production environments, you'll likely want to use a persistent data store. Currently, [Redis] is the supported option:
+#### Redis for Production
+
+For production environments, you'll likely want to use a persistent data store. One of the supported options is [Redis].
 
 ```ruby
 # Configure Redis as the data store
@@ -399,9 +405,32 @@ Stoplight.configure do |config|
 end
 ```
 
-#### Connection Pooling with Redis
+#### Valkey Support
 
-For high-traffic applications or when you want to control a number of opened connections to Redis:
+Stoplight also supports [Valkey], a drop-in replacement for Redis.  
+Just point your Redis client to a Valkey instance and configure Stoplight as usual:
+
+```ruby
+# ...
+# We assume that Valkey is available on 127.0.0.1:6379 address
+valkey = Redis.new(url: "redis://127.0.0.1:6379")
+data_store = Stoplight::DataStore::Redis.new(valkey)
+
+Stoplight.configure do |config|
+  config.data_store = data_store
+  # ...
+end
+```
+
+#### DragonflyDB Support
+
+Although Stoplight does not officially support [DragonflyDB], it can be used with it. For details, you may refer to the official [DragonflyDB documentation].
+
+**NOTE**: Compatibility with [DragonflyDB] is not guaranteed, and results may vary. However, you are welcome to contribute to the project if you find any issues.
+
+#### Connection Pooling
+
+For high-traffic applications or when you want to control the number of open connections to the Data Store:
 
 ```ruby
 require "connection_pool"
@@ -415,7 +444,7 @@ end
 
 ### Notifiers
 
-Stoplight notifies when lights change state. Configure how these notifications are delivered:
+Stoplight notifies when the lights change state. Configure how these notifications are delivered:
 
 ```ruby
 # Log to a specific logger
@@ -540,9 +569,45 @@ stoplight = Stoplight("test-#{rand}")
 
 ## Maintenance Policy
 
-Stoplight supports the latest three minor versions of Ruby, which currently are: `3.2.x`, `3.3.x`, and `3.4.x`. Changing
-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`)
+We focus on supporting current, secure versions rather than maintaining extensive backwards compatibility. We follow 
+semantic versioning and give reasonable notice before dropping support.
+
+### Stoplight Version Support
+
+We only actively support the latest major version of Stoplight.
+
+* ✅ Bug fixes and new features go to the current major version only (e.g., if you're on 4.x, upgrade to 5.x for fixes)
+* ✅ Upgrade guidance is provided in release notes for major version changes
+* ✅ We won't break compatibility in patch/minor releases
+* ✅ We may accept community-contributed security patches for the previous major version
+* ❌ We don't backport fixes to old Stoplight major versions
+* ❌ We don't add new features to old Stoplight major versions
+
+### What We Support
+
+**Ruby**: Major versions that receive security updates (see [Ruby Maintenance Branches]):
+
+* Currently: Ruby 3.2.x, 3.3.x and 3.4.x
+* We test against these versions in CI
+
+**Data Stores**: Current supported versions from upstream (versions that receive security updates):
+
+* Redis: 8.0.x, 7.4.x, 7.2.x, 6.2.x (following [Redis's support policy])
+* Valkey: 8.0.x, 7.2.x (following [Valkey's support policy])
+* We test against the latest version of each major release
+
+For dependencies:
+* ✅ We test all supported dependency combinations in CI
+* ✅ We investigate bug reports on supported dependency versions
+* ❌ We don't test unsupported dependency versions (e.g., Ruby 3.1, Redis 5.x)
+* ❌ We don't fix bugs specific to unsupported dependencies
+
+### When We Drop Support
+
+* Ruby: When Ruby core team ends security support, we drop it in our next major release
+* Data Stores: When Redis/Valkey ends maintenance, we drop it in our next major release
+
+Example: "Ruby 3.2 reaches end-of-life in March 2026, so Stoplight 6.0 will require Ruby 3.3+"
 
 ## Development
 
@@ -563,14 +628,12 @@ Fowler’s [CircuitBreaker][] article.
 [build]: https://github.com/bolshakov/stoplight/actions?query=branch%3Amaster
 [Coverage badge]: https://img.shields.io/coveralls/bolshakov/stoplight/master.svg?label=coverage
 [coverage]: https://coveralls.io/r/bolshakov/stoplight
-[Climate badge]: https://api.codeclimate.com/v1/badges/3451c2d281ffa345441a/maintainability
-[climate]: https://codeclimate.com/github/bolshakov/stoplight
 [stoplight-admin]: https://github.com/bolshakov/stoplight-admin
 [Semantic Versioning]: http://semver.org/spec/v2.0.0.html
 [the change log]: CHANGELOG.md
 [stoplight-sentry]: https://github.com/bolshakov/stoplight-sentry
 [stoplight-honeybadger]: https://github.com/qoqa/stoplight-honeybadger
-[notifier interface documentation]: https://github.com/bolshakov/stoplight/blob/master/lib/stoplight/notifier/generic.rb
+[notifier interface documentation]: https://github.com/bolshakov/stoplight/blob/main/lib/stoplight/notifier/generic.rb
 [camdez]: https://github.com/camdez
 [tfausak]: https://github.com/tfausak
 [bolshakov]: https://github.com/bolshakov
@@ -579,3 +642,9 @@ Fowler’s [CircuitBreaker][] article.
 [CircuitBreaker]: http://martinfowler.com/bliki/CircuitBreaker.html
 [Redis]: https://redis.io/
 [Git Flow wiki page]: https://github.com/bolshakov/stoplight/wiki/Git-Flow
+[Valkey]: https://valkey.io/
+[Ruby Maintenance Branches]: https://www.ruby-lang.org/en/downloads/branches/
+[Redis's support policy]: https://redis.io/about/releases/
+[Valkey's support policy]: https://valkey.io/topics/releases/
+[DragonflyDB]: https://www.dragonflydb.io/
+[DragonflyDB documentation]: https://www.dragonflydb.io/docs/managing-dragonfly/scripting#script-flags

data/lib/stoplight/data_store/fail_safe.rb

@@ -48,13 +48,13 @@ module Stoplight
       end
 
       def get_metadata(config)
-        with_fallback(Metadata.new, config) do
+        with_fallback(EmptyMetadata, config) do
           data_store.get_metadata(config)
         end
       end
 
       def record_failure(config, failure)
-        with_fallback(nil, config) do
+        with_fallback(EmptyMetadata, config) do
           data_store.record_failure(config, failure)
         end
       end
@@ -66,13 +66,13 @@ module Stoplight
       end
 
       def record_recovery_probe_success(config, **args)
-        with_fallback(nil, config) do
+        with_fallback(EmptyMetadata, config) do
           data_store.record_recovery_probe_success(config, **args)
         end
       end
 
       def record_recovery_probe_failure(config, failure)
-        with_fallback(nil, config) do
+        with_fallback(EmptyMetadata, config) do
           data_store.record_recovery_probe_failure(config, failure)
         end
       end

data/lib/stoplight/data_store/redis/get_metadata.lua

@@ -11,7 +11,7 @@ local metadata_key = KEYS[1]
 -- we need to limit the start time of the window to the time of the last recovery.
 local recovered_at = redis.call('HGET', metadata_key, "recovered_at")
 if recovered_at then
-  window_start_ts = math.max(window_start_ts, recovered_at)
+  window_start_ts = math.max(window_start_ts, tonumber(recovered_at))
 end
 
 local function count_events(start_idx, bucket_count, start_ts)

data/lib/stoplight/empty_metadata.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Stoplight
+  EmptyMetadata = Metadata.new
+end

data/lib/stoplight/light/yellow_run_strategy.rb

@@ -51,24 +51,26 @@ module Stoplight
         recovery_result = config.traffic_recovery.determine_color(config, metadata)
 
         case recovery_result
-        when Color::GREEN
+        when TrafficRecovery::GREEN
           if data_store.transition_to_color(config, Color::GREEN)
             config.notifiers.each do |notifier|
               notifier.notify(config, Color::YELLOW, Color::GREEN, nil)
             end
           end
-        when Color::YELLOW
+        when TrafficRecovery::YELLOW
           if data_store.transition_to_color(config, Color::YELLOW)
             config.notifiers.each do |notifier|
               notifier.notify(config, Color::GREEN, Color::YELLOW, nil)
             end
           end
-        when Color::RED
+        when TrafficRecovery::RED
           if data_store.transition_to_color(config, Color::RED)
             config.notifiers.each do |notifier|
               notifier.notify(config, Color::YELLOW, Color::RED, nil)
             end
           end
+        when TrafficRecovery::PASS
+          # No state change, do nothing
         else
           raise "recovery strategy returned an expected color: #{recovery_result}"
         end

data/lib/stoplight/metadata.rb

@@ -19,10 +19,10 @@ module Stoplight
     :recovered_at
   ) do
     def initialize(
-      successes: nil,
-      errors: nil,
-      recovery_probe_successes: nil,
-      recovery_probe_errors: nil,
+      successes: 0,
+      errors: 0,
+      recovery_probe_successes: 0,
+      recovery_probe_errors: 0,
       last_error_at: nil,
       last_success_at: nil,
       consecutive_errors: 0,
@@ -35,14 +35,14 @@ module Stoplight
       recovered_at: nil
     )
       super(
-        recovery_probe_successes:,
-        recovery_probe_errors:,
-        successes:,
-        errors:,
+        recovery_probe_successes: recovery_probe_successes.to_i,
+        recovery_probe_errors: recovery_probe_errors.to_i,
+        successes: successes.to_i,
+        errors: errors.to_i,
         last_error_at: (Time.at(Integer(last_error_at)) if last_error_at),
         last_success_at: (Time.at(Integer(last_success_at)) if last_success_at),
-        consecutive_errors: Integer(consecutive_errors),
-        consecutive_successes: Integer(consecutive_successes),
+        consecutive_errors: consecutive_errors.to_i,
+        consecutive_successes: consecutive_successes.to_i,
         last_error:,
         breached_at: (Time.at(Integer(breached_at)) if breached_at),
         locked_state: locked_state || State::UNLOCKED,
@@ -52,6 +52,16 @@ module Stoplight
       )
     end
 
+    # Creates a new Metadata instance with updated attributes. This method overrides
+    # the default +with+ method provided by +Data.define+ to ensure constructor
+    # logic is applied.
+    #
+    # @param kwargs [Hash{Symbol => Object}]
+    # @return [Metadata]
+    def with(**kwargs)
+      self.class.new(**to_h.merge(kwargs))
+    end
+
     # @param at [Time] (Time.now) the moment of time when the color is determined
     # @return [String] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
     def color(at: Time.now)
@@ -72,7 +82,7 @@ module Stoplight
     #
     # @return [Float]
     def error_rate
-      if successes.nil? || errors.nil? || (successes + errors).zero?
+      if (successes + errors).zero?
         0.0
       else
         errors.fdiv(successes + errors)

data/lib/stoplight/traffic_recovery/base.rb

@@ -49,10 +49,7 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config]
       # @param metadata [Stoplight::Metadata]
-      # @return [String] One of the Stoplight::Color constants:
-      #   - Stoplight::Color::RED: Recovery failed, block all traffic
-      #   - Stoplight::Color::YELLOW: Continue recovery process
-      #   - Stoplight::Color::GREEN: Recovery successful, return to normal traffic flow
+      # @return [TrafficRecovery::Decision]
       def determine_color(config, metadata)
         raise NotImplementedError
       end

data/lib/stoplight/traffic_recovery/consecutive_successes.rb

@@ -49,16 +49,18 @@ module Stoplight
       #
       # @param config [Stoplight::Light::Config]
       # @param metadata [Stoplight::Metadata]
-      # @return [String]
+      # @return [TrafficRecovery::Decision]
       def determine_color(config, metadata)
+        return TrafficRecovery::PASS if metadata.color != Color::YELLOW
+
         recovery_started_at = metadata.recovery_started_at || metadata.recovery_scheduled_after
 
         if metadata.last_error_at && metadata.last_error_at >= recovery_started_at
-          Color::RED
+          TrafficRecovery::RED
         elsif [metadata.consecutive_successes, metadata.recovery_probe_successes].min >= config.recovery_threshold
-          Color::GREEN
+          TrafficRecovery::GREEN
         else
-          Color::YELLOW
+          TrafficRecovery::YELLOW
         end
       end
     end

data/lib/stoplight/traffic_recovery.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module TrafficRecovery
+    Decision = Data.define(:decision)
+    GREEN = Decision.new("green")
+    YELLOW = Decision.new("yellow")
+    RED = Decision.new("red")
+    PASS = Decision.new("pass")
+  end
+end

data/lib/stoplight/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 5.3.1
+  version: 5.3.5
 platform: ruby
 authors:
 - Cameron Desautels
@@ -76,6 +76,7 @@ files:
 - lib/stoplight/data_store/redis/transition_to_red.lua
 - lib/stoplight/data_store/redis/transition_to_yellow.lua
 - lib/stoplight/default.rb
+- lib/stoplight/empty_metadata.rb
 - lib/stoplight/error.rb
 - lib/stoplight/failure.rb
 - lib/stoplight/light.rb
@@ -97,6 +98,7 @@ files:
 - lib/stoplight/traffic_control/base.rb
 - lib/stoplight/traffic_control/consecutive_errors.rb
 - lib/stoplight/traffic_control/error_rate.rb
+- lib/stoplight/traffic_recovery.rb
 - lib/stoplight/traffic_recovery/base.rb
 - lib/stoplight/traffic_recovery/consecutive_successes.rb
 - lib/stoplight/version.rb