stoplight 6.0.0.rc3 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97295cc794acc8de621f091e6cb0cfc7903f2f3bc5c439773c7888cb267bd197
-  data.tar.gz: c154e63a6dcd7094d56173647f022ed800514969db64655aac9dd3aefedd566a
+  metadata.gz: e9e835f7351f236b8965d8179da39eff4eaf768bbf066c94cb35f8ed6f0360f6
+  data.tar.gz: ea64aa21f4874b40843e2f18716da346b4e0a4fbf77f57ca777bafa8e396ae5b
 SHA512:
-  metadata.gz: b6d7af0c9ad656fca39fb69bcc563e22cb955e3ec60e24e0615a7877fa3f09d7fe58152d7cb1a8797190529bab55b92ecfda544a4fddb7dbe1c16539adbe30b3
-  data.tar.gz: 5e222668a15bdd9e7b5b384ec83fb9b94e61e069d34cc509da7855325740e932fb72afcd31f91db5ed74847ce2509f019a8b10db550245741cbb73ab37c484b3
+  metadata.gz: 3bfa3fb97ed1f8f2743930257fefb4eba4f380b9b7eea122af9ca792206b43c27b42fb35292d95ab6c608ad70e3f99f6cf3ca0eb319e2d31c2010943e50a9730
+  data.tar.gz: 330fce49dcde86b0d0a9864143523db53caa20f64105cd40f85fcc4930769e3cd35ddb1f199aefce184b6c08eed69259acf0d697a9c4dc4e8245f482fc4a2474

data/README.md

@@ -80,8 +80,8 @@ After the last failure, the light turns red. The next call will raise a `Stoplig
 executing the block:
 
 ```ruby
-light.run { 1 / 0 } #=> raises Stoplight::Error::RedLight: example-zero
-light.color # => "red"
+light.run { 1 / 0 } #=> raises Stoplight::Error::RedLight: Light `Example` is red - traffic stopped until recovery.
+light.color # => :red
 ```
 
 The `Stoplight::Error::RedLight` provides metadata about the error:
@@ -108,7 +108,7 @@ light.run { 1 / 1 } #=> 1
 If the test probe succeeds, the light turns green again. If it fails, the light turns red again.
 
 ```ruby
-light.color #=> "green"
+light.color #=> :green
 ```
 
 ### Using Fallbacks
@@ -388,7 +388,7 @@ By default, Stoplight uses an in-memory data store:
 
 ```ruby
 require "stoplight"
-Stoplight::Default::DATA_STORE
+Stoplight::Wiring::Default::DATA_STORE
 # => #<Stoplight::DataStore::Memory:...>
 ```
 
@@ -678,8 +678,8 @@ Example: "Ruby 3.3 reaches end-of-life in March 2027, so Stoplight 7.0 will requ
 ## 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. Also check our CONTRIBUTING.md guide for contributors.
+code style with `bundle exec standardrb`. All work happens on `main` - see [CONTRIBUTING.md] for branch naming,
+releases, and the contribution workflow.
 
 ## Credits
 
@@ -700,7 +700,7 @@ Fowler’s [CircuitBreaker][] article.
 [stoplight-sentry]: https://github.com/bolshakov/stoplight-sentry
 [stoplight-honeybadger]: https://github.com/qoqa/stoplight-honeybadger
 [stoplight-statsd]: https://github.com/bolshakov/stoplight-statsd
-[notifier interface documentation]: https://github.com/bolshakov/stoplight/blob/main/lib/stoplight/domain/state_transition_notifier.rb
+[notifier interface documentation]: https://github.com/bolshakov/stoplight/blob/main/sig/stoplight/domain/ports/state_transition_notifier.rbs
 [camdez]: https://github.com/camdez
 [tfausak]: https://github.com/tfausak
 [bolshakov]: https://github.com/bolshakov
@@ -708,7 +708,7 @@ 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
+[CONTRIBUTING.md]: CONTRIBUTING.md
 [Valkey]: https://valkey.io/
 [Ruby Maintenance Branches]: https://www.ruby-lang.org/en/downloads/branches/
 [Redis's support policy]: https://redis.io/about/releases/

data/UPGRADING.md

@@ -8,6 +8,7 @@ Here's what you'll want to tackle during your upgrade, roughly ordered from the
 
 - [ ] Make every `Stoplight("name", ...)` call site for the same name pass identical settings
 - [ ] Move `data_store`, `notifiers`, and `error_notifier` from individual lights to `Stoplight.configure`
+- [ ] Make sure that you run at least Ruby 3.3+, Redis 7.4+ (or Valkey 7.2+)
 - [ ] Replace the `with_*` builder methods with settings passed at creation time
 - [ ] Replace proc and anonymous-class error matchers with named classes or modules
 - [ ] Account for Stoplight state reset after deployment
@@ -16,6 +17,7 @@ Here's what you'll want to tackle during your upgrade, roughly ordered from the
 - [ ] Round any fractional `cool_off_time` up to a whole number of seconds, at least 1
 - [ ] Drop `warn_on_clock_skew` from your Redis data store setup
 - [ ] Compare `light.color` and `light.state` against symbols, not strings, and pass a symbol to `light.lock`
+- [ ] Check anything that parses or matches `Stoplight::Error::RedLight` messages - the message format changed
 - [ ] Test thoroughly in a staging environment
 
 ### Lights Are Registered and Reused
@@ -87,6 +89,13 @@ end
 If you genuinely need more than one data store - separate Redis instances per tenant, for example - use named
 systems, which own their own infrastructure. See [Systems: Namespace Isolation & Configuration][systems] for setup.
 
+### Ruby 3.3 and Redis 7.4 Are the new Minimum
+
+Stoplight 6 requires Ruby 3.3 or newer.
+We also require Redis 7.4 or newer and Valkey 7.2 or newer and no longer tested or supported earlier versions.
+
+See the [maintenance policy] for the versions under test.
+
 ### The Light Builder API Is Gone
 
 `Light#with` and the whole `with_*` family are removed: `with_data_store`, `with_cool_off_time`, `with_threshold`,
@@ -276,6 +285,19 @@ light.lock(Stoplight::Color::GREEN)
 Symbols are the idiomatic Ruby choice for a closed set of values. Anything that serializes them - logs, metrics tags,
 the Admin dashboard's JSON - renders the same text as before.
 
+### The `RedLight` Exception Message Changed
+
+The message of `Stoplight::Error::RedLight` used to be the bare light name. It is now a sentence that names the light
+and says what happened, so a log line or an error tracker (e.g., in Sentry) entry is readable on its own:
+
+```
+# 5.x
+Stoplight::Error::RedLight: Payment Service
+
+# 6.0
+Stoplight::Error::RedLight: Light `Payment Service` is red - traffic stopped until recovery.
+```
+
 ### Getting Help
 
 If you run into anything this guide doesn't cover, post to our [Discussions forum]. The configuration errors in 6.0
@@ -582,6 +604,7 @@ Nothing. Stoplight will function as usual.
 [Community-supported notifiers]: https://github.com/bolshakov/stoplight/tree/master#community-supported-notifiers
 [How to implement your own notifier?]: https://github.com/bolshakov/stoplight/blob/master/lib/stoplight/notifier/generic.rb
 [dropped notifiers]: https://github.com/bolshakov/stoplight/tree/v3.0.1/lib/stoplight/notifier
+[maintenance policy]: https://github.com/bolshakov/stoplight#maintenance-policy
 [without passing an empty block]: https://github.com/bolshakov/stoplight-admin/blob/9c9848eb94410e46b20972548f0863db224cb6da/lib/sinatra/stoplight_admin.rb#L30
 [sliding window]: https://github.com/bolshakov/stoplight#custom-window-size
 [systems]: https://github.com/bolshakov/stoplight/blob/master/docs/systems.md

data/lib/stoplight/data_store.rb

@@ -30,6 +30,13 @@ module Stoplight
       # @see Stoplight::Infrastructure::Redis::Key
       def self.key_space = KEY_SPACE
       def key_space = self.class.key_space
+
+      # Lua scripts are loaded into Redis once per server, so every light shares a single script cache.
+      #
+      # @api private
+      def __stoplight__scripting
+        @scripting ||= Infrastructure::Redis::Storage::Scripting.new(redis:)
+      end
     end
 
     class Memory < Base

data/lib/stoplight/error.rb

@@ -18,7 +18,7 @@ module Stoplight
     end
 
     class RedLight < Base
-      EXCEPTION_MESSAGE = 'Stoplight "%{light_name}" is red - traffic stopped until recovery.'
+      EXCEPTION_MESSAGE = "Light `%{light_name}` is red - traffic stopped until recovery."
       private_constant :EXCEPTION_MESSAGE
 
       # @!attribute light_name

data/lib/stoplight/infrastructure/redis/storage/scripting.rb

@@ -21,6 +21,7 @@ module Stoplight
             @shas = Hash.new do |hash, script_name|
               hash[script_name] = Digest::SHA1.hexdigest(resolve_source(script_name))
             end
+            @invoked = Set.new
           end
 
           def call(script_name, keys: [], args: [])
@@ -33,18 +34,23 @@ module Stoplight
             rescue ::Redis::CommandError => error
               if error.message.include?("NOSCRIPT") && !retried
                 retried = true
-                reload_script(script_name)
+                if @invoked.include?(script_name) # skip warning for the first script invocation on app boot
+                  warn "Stoplight is unable to find the script '#{script_name}' from Redis's script cache. " \
+                         "Reloading and retrying..."
+                end
+                load_script(script_name)
                 retry
               else
                 raise error
               end
+            ensure
+              @invoked << script_name
             end
           end
 
           private
 
-          def reload_script(script_name)
-            warn "Stoplight is unable to find the script '#{script_name}' in Redis's script cache. Reloading and retrying..."
+          def load_script(script_name)
             @redis.then { |client| client.script(:load, resolve_source(script_name)) }
           end
 

data/lib/stoplight/infrastructure/redis/storage/state/state_snapshot.lua

@@ -0,0 +1,9 @@
+-- @include now
+
+local meta_key = KEYS[1]
+
+local state = redis.call('HMGET', meta_key, 'breached_at', 'locked_state', 'recovery_scheduled_after', 'recovery_started_at')
+local current_time = now()
+state[5] = current_time
+
+return state

data/lib/stoplight/infrastructure/redis/storage/state/transition_to_red.lua

@@ -1,8 +1,9 @@
 -- @include now
 
 local meta_key = KEYS[1]
-local recovery_scheduled_after_ts = tonumber(ARGV[1])
+local cool_off_time = tonumber(ARGV[1])
 local current_ts = now() / 1000
+local recovery_scheduled_after_ts = current_ts + cool_off_time
 
 --  1 if the field is a new field in the hash and the value was set
 local became_red = redis.call('HSETNX', meta_key, 'breached_at', current_ts)

data/lib/stoplight/infrastructure/redis/storage/state.rb

@@ -57,16 +57,19 @@ module Stoplight
           end
 
           def state_snapshot
-            breached_at_raw, locked_state, recovery_scheduled_after_raw, recovery_started_at_raw = redis.with do |client|
-              client.hmget(state_key, :breached_at, :locked_state, :recovery_scheduled_after, :recovery_started_at)
-            end
+            breached_at_raw, locked_state, recovery_scheduled_after_raw, recovery_started_at_raw, now_ms =
+              scripting.call(
+                "state/state_snapshot",
+                args: [],
+                keys: [state_key]
+              )
 
             Domain::StateSnapshot.new(
               breached_at: breached_at_raw && clock.at(breached_at_raw.to_f),
               locked_state: locked_state&.to_sym || Stoplight::State::UNLOCKED,
               recovery_scheduled_after: recovery_scheduled_after_raw && clock.at(recovery_scheduled_after_raw.to_f),
               recovery_started_at: recovery_started_at_raw && clock.at(recovery_started_at_raw.to_f),
-              time: clock.current_time
+              time: clock.at(now_ms.fdiv(1000))
             )
           end
 
@@ -123,12 +126,9 @@ module Stoplight
           # Transitions to RED state and ensures only one notification
           #
           def transition_to_red
-            current_ts = clock.current_time.to_f
-            recovery_scheduled_after_ts = current_ts + cool_off_time
-
             became_red = scripting.call(
               "state/transition_to_red",
-              args: [recovery_scheduled_after_ts],
+              args: [cool_off_time],
               keys: [state_key]
             )
 

data/lib/stoplight/infrastructure/redis/storage/window_metrics/_evict.lua

@@ -18,6 +18,8 @@ local function evict_buckets(metrics_key, ts_index_key, window_start)
     return
   end
 
+  local failures, successes = 0, 0
+
   for from = 1, #buckets, EVICT_BATCH_SIZE do
     local to = math.min(from + EVICT_BATCH_SIZE - 1, #buckets)
 
@@ -29,16 +31,15 @@ local function evict_buckets(metrics_key, ts_index_key, window_start)
 
     local values = redis.call('HMGET', metrics_key, unpack(fields))
 
-    local failures, successes = 0, 0
     for i = 1, #values, 2 do
       failures = failures + (tonumber(values[i]) or 0)
       successes = successes + (tonumber(values[i + 1]) or 0)
     end
 
-    redis.call('HINCRBY', metrics_key, 'total_failures', -failures)
-    redis.call('HINCRBY', metrics_key, 'total_successes', -successes)
     redis.call('HDEL', metrics_key, unpack(fields))
   end
 
+  redis.call('HINCRBY', metrics_key, 'total_failures', -failures)
+  redis.call('HINCRBY', metrics_key, 'total_successes', -successes)
   redis.call('ZREMRANGEBYSCORE', ts_index_key, '-inf', window_start)
 end

data/lib/stoplight/version.rb

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

data/lib/stoplight/wiring/light_factory.rb

@@ -72,7 +72,16 @@ module Stoplight
       attr_reader :system_name
 
       def recovery_lock_store = storage_set.recovery_lock_store
-      def storage_scripting = Infrastructure::Redis::Storage::Scripting.new(redis:)
+
+      def storage_scripting
+        case data_store_config
+        when DataStore::Redis
+          data_store_config.__stoplight__scripting
+        else
+          raise T.absurd(data_store_config)
+        end
+      end
+
       def failover_system = T.must(@failover_system)
 
       def key_space

data/lib/stoplight.rb

@@ -3,7 +3,6 @@
 require "concurrent/map"
 require "zeitwerk"
 
-# steep:ignore:start
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect("io" => "IO")
 loader.do_not_eager_load(
@@ -14,7 +13,6 @@ loader.do_not_eager_load(
 loader.ignore("#{__dir__}/generators")
 loader.ignore("#{__dir__}/stoplight/rspec.rb", "#{__dir__}/stoplight/rspec")
 loader.setup
-# steep:ignore:end
 
 module Stoplight # rubocop:disable Style/Documentation
   T = Types

data/sig/stoplight/data_store/redis.rbs

@@ -7,9 +7,12 @@ module Stoplight
       KEY_SPACE: Infrastructure::Redis::Key
 
       attr_reader redis: Infrastructure::redis
+      @scripting: Infrastructure::Redis::Storage::Scripting?
 
       def initialize: (Infrastructure::redis) -> void
 
+      def __stoplight__scripting: -> Infrastructure::Redis::Storage::Scripting
+
       def self.key_space: -> Infrastructure::Redis::Key
       def key_space: -> Infrastructure::Redis::Key
     end

data/sig/stoplight/infrastructure/redis/storage/scripting.rbs

@@ -11,6 +11,7 @@ module Stoplight
 
           @scripts_path: Array[String]
           @shas: Hash[String, String]
+          @invoked: Set[String]
           @redis: redis
 
           def initialize: (
@@ -24,7 +25,7 @@ module Stoplight
               ?args: Array[_ToS]
             ) -> untyped
 
-          private def reload_script: (String script_name) -> void
+          private def load_script: (String script_name) -> void
 
           private def resolve_source: (String script_name) -> String
         end

data/sig/stoplight/infrastructure/redis/storage/state.rbs

@@ -9,7 +9,7 @@ module Stoplight
           attr_reader scripting: Scripting
           attr_reader key_space: Key
           attr_reader clock: Domain::_Clock
-          attr_reader cool_off_time: Domain::timestamp
+          attr_reader cool_off_time: Domain::duration_seconds
           attr_reader state_key: String
 
           def initialize: (
@@ -17,7 +17,7 @@ module Stoplight
             redis: redis,
             scripting: Scripting,
             key_space: Key,
-            cool_off_time: Domain::timestamp
+            cool_off_time: Domain::duration_seconds
           ) -> void
 
           def transition_to_green: -> bool

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 6.0.0.rc3
+  version: 6.0.0
 platform: ruby
 authors:
 - Tëma Bolshakov
@@ -145,6 +145,7 @@ files:
 - lib/stoplight/infrastructure/redis/storage/registry.rb
 - lib/stoplight/infrastructure/redis/storage/scripting.rb
 - lib/stoplight/infrastructure/redis/storage/state.rb
+- lib/stoplight/infrastructure/redis/storage/state/state_snapshot.lua
 - lib/stoplight/infrastructure/redis/storage/state/transition_to_green.lua
 - lib/stoplight/infrastructure/redis/storage/state/transition_to_red.lua
 - lib/stoplight/infrastructure/redis/storage/state/transition_to_yellow.lua
@@ -344,7 +345,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Traffic control for code.
 test_files: []