stoplight 6.0.0.rc2 → 6.0.0.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dc15c81e94d811df03fe4acdd4ff76e3633931a1c4df022b7c26480834135e8
-  data.tar.gz: 82b93fba4751312a3ad6ac33602b0b50c40fc6ebd5d72554d66f040ab7efd133
+  metadata.gz: ade3c17bdafebab88e87b0f967dcf71a3fef99bb486c10a328e5110c4a4f456a
+  data.tar.gz: 2dff3cb5d7731a337c8d558c73d7a3091b7bf1bafb060ae7d8bd74d570f2b4c2
 SHA512:
-  metadata.gz: 3a97e8dec725453ffd76e95d7d2ab59ef8929b89aa6ac2350a816d3e280aa49f893d3818dc28d6b465e20bf508c9cf10b37265e6968c436836ba9b5bdc374bb8
-  data.tar.gz: 9550e279df8c4ceaa1cc4de1a76a85dcb2fa84cb079e7dbd3716e699479b5cf94fe1d577f99f713840b693b6520d1c19b8f1b2b01fc9325b6db7cf89abdcfed3
+  metadata.gz: bd236321933ab75c09c468c3a12fddefe3002ce16cbfc7c6a28580d56fb3b6cace531792e9e5c0cae393158f5ba0ce6d62ec1425363bf4ba83abd8b6d4cb04ee
+  data.tar.gz: ce3c272066f30882c34921144dbe48773fd6ed4812d6933ea96842a0848830c4e9e5b1f23b46d7d93556c87d56cb6b7345553c06135ab54f2111f21a52aac759

data/README.md

@@ -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
 
@@ -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
@@ -15,6 +16,7 @@ Here's what you'll want to tackle during your upgrade, roughly ordered from the
 - [ ] Round any fractional `window_size` up to a whole number of seconds
 - [ ] 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`
 - [ ] Test thoroughly in a staging environment
 
 ### Lights Are Registered and Reused
@@ -86,6 +88,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`,
@@ -250,6 +259,31 @@ Stoplight::DataStore::Redis.new(redis)
 All time-dependent decisions are now made from Redis's own clock, so every instance reads the same time no matter
 what its host believes. With the coordination problem solved at the source, there is no skew left to warn about.
 
+### Colors and Lock States Are Symbols
+
+`light.color` now returns `:green`, `:yellow`, or `:red` instead of `"green"`, `"yellow"`, or `"red"`, and
+`light.state` returns `:unlocked`, `:locked_green`, or `:locked_red`. The constants under `Stoplight::Color` and
+`Stoplight::State` hold the same symbols, and every telemetry event carries them too: `from_color` and `to_color` on
+each transition, `from_state` and `to_state` on `LockChanged`.
+
+`light.lock` only recognises the symbols, so `light.lock("red")` now raises `Stoplight::Error::IncorrectColor`.
+
+Code that compares against the constants keeps working. Code that compares against, or passes, string literals needs
+updating:
+
+```ruby
+# Old way that won't work anymore
+alert! if light.color == "red"
+light.lock("green")
+
+# New way
+alert! if light.color == Stoplight::Color::RED
+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.
+
 ### Getting Help
 
 If you run into anything this guide doesn't cover, post to our [Discussions forum]. The configuration errors in 6.0
@@ -556,6 +590,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/admin/helpers.rb

@@ -9,6 +9,10 @@ module Stoplight
         Color::RED
       ].freeze
 
+      def red?(light) = light.color == Color::RED
+
+      def yellow?(light) = light.color == Color::YELLOW
+
       def dependencies
         Dependencies.new(system: current_system)
       end

data/lib/stoplight/admin/views/_card.erb

@@ -28,15 +28,15 @@
       </p>
       <span class="flex items-center text-sm font-medium text-gray-500 dark:text-gray-400 truncate me-3">
         <span class="flex w-2.5 h-2.5 bg-<%= color %>-600 rounded-full me-1.5 shrink-0"></span>
-        <% if light.color == "red" %>
+        <% if red?(light) %>
           Open
-        <% elsif light.color == "yellow" %>
+        <% elsif yellow?(light) %>
           Half-Open
         <% else %>
           Closed
         <% end %>
 
-        <% if light.color == "yellow" %>
+        <% if yellow?(light) %>
           (Recovering)
         <% elsif light.locked? %>
           (Locked)

data/lib/stoplight/admin.rb

@@ -142,14 +142,14 @@ module Stoplight
 
     patch "/systems/:system_id/lights/:light_id/lock" do
       light_id = T.must(params[:light_id])
-      color = T.must(params[:color])
+      color = T.must(params[:color]).to_sym
       dependencies.lock_action.call(light_id:, color:)
 
       redirect system_url(current_system_id, "/lights")
     end
 
     patch "/systems/:system_id/lights/lock" do
-      color = T.must(params[:color])
+      color = T.must(params[:color]).to_sym
       dependencies.lock_all_action.call(color:)
 
       redirect system_url(current_system_id, "/lights")

data/lib/stoplight/color.rb

@@ -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/domain/state_snapshot.rb

@@ -23,7 +23,7 @@ module Stoplight
       # @!attribute time
       #   The time when the snapshot was taken
 
-      # @return [String] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
+      # @return [Symbol] one of +Color::GREEN+, +Color::RED+, or +Color::YELLOW+
       def color
         if locked_state == State::LOCKED_GREEN
           Color::GREEN

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 || Stoplight::State::UNLOCKED,
+              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/state.rb

@@ -2,8 +2,8 @@
 
 module Stoplight
   module State
-    UNLOCKED = "unlocked"
-    LOCKED_GREEN = "locked_green"
-    LOCKED_RED = "locked_red"
+    UNLOCKED = :unlocked
+    LOCKED_GREEN = :locked_green
+    LOCKED_RED = :locked_red
   end
 end

data/lib/stoplight/version.rb

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

data/lib/stoplight/wiring/system.rb

@@ -46,6 +46,9 @@ module Stoplight
       REGISTRATION_FRAME_LIMIT = 5
       private_constant :REGISTRATION_FRAME_LIMIT
 
+      Registration = Data.define(:light, :digest, :backtrace, :without_settings)
+      private_constant :Registration
+
       attr_reader :name
       # @api private
       attr_reader :config
@@ -113,6 +116,16 @@ module Stoplight
         traffic_control: T.undefined,
         traffic_recovery: T.undefined
       )
+        without_settings = cool_off_time.is_a?(Undefined) && threshold.is_a?(Undefined) &&
+          recovery_threshold.is_a?(Undefined) && window_size.is_a?(Undefined) &&
+          tracked_errors.is_a?(Undefined) && skipped_errors.is_a?(Undefined) &&
+          traffic_control.is_a?(Undefined) && traffic_recovery.is_a?(Undefined)
+
+        if without_settings
+          registration = @lights[name]
+          return registration.light if registration&.without_settings
+        end
+
         light_dsl = LightConfigurationDsl.new(
           name:,
           cool_off_time:,
@@ -126,8 +139,8 @@ module Stoplight
         )
         config_digest = light_dsl.digest
 
-        light, existing_digest, existing_backtrace = @lights[name] || begin
-          registered_at = ExternalCaller.backtrace.first(REGISTRATION_FRAME_LIMIT)
+        registration = @lights[name] || begin
+          backtrace = ExternalCaller.backtrace.first(REGISTRATION_FRAME_LIMIT)
           config = light_dsl.configure!(@config)
           @lights.compute_if_absent(name) do
             built = LightFactory.new(
@@ -137,12 +150,12 @@ module Stoplight
               telemetry: @telemetry
             ).build
             @registry.register(config)
-            [built, config_digest, registered_at]
+            Registration.new(light: built, digest: config_digest, backtrace:, without_settings:)
           end
         end
 
-        if config_digest != existing_digest
-          original_site = existing_backtrace.map { |frame| "  #{frame}" }.join("\n")
+        if config_digest != registration.digest
+          original_site = registration.backtrace.map { |frame| "  #{frame}" }.join("\n")
 
           raise Stoplight::Error::ConfigurationError, <<~MSG, ExternalCaller.backtrace
             Light `#{name}` already registered with different configuration.
@@ -154,12 +167,12 @@ module Stoplight
           MSG
         end
 
-        light
+        registration.light
       end
 
       # @raise [Stoplight::Error::UnregisteredLightError] if no light was registered under +name+
       def light(name)
-        @lights[name]&.first || raise(Stoplight::Error::UnregisteredLightError, <<~MSG)
+        @lights[name]&.light || raise(Stoplight::Error::UnregisteredLightError, <<~MSG)
           Light `#{name}` was never registered on system `#{@name}`.
           Call `.register(#{name.inspect}, ...)` at boot before using it.
         MSG

data/sig/stoplight/admin/actions/action.rbs

@@ -3,7 +3,7 @@ module Stoplight
   class Admin
     module Actions
       class Action
-        def halt: (Integer status) -> void
+        def halt: (Integer status) -> bot
       end
     end
   end

data/sig/stoplight/admin/helpers.rbs

@@ -3,6 +3,9 @@ module Stoplight
     module Helpers : Sinatra::Base
       COLORS: Array[Domain::color]
 
+      def red?: (LightView) -> bool
+      def yellow?: (LightView) -> bool
+
       def dependencies: -> Dependencies
       def system_url: (String system_id, String path) -> String
       def asset_path: (String) -> String

data/sig/stoplight/domain/types.rbs

@@ -5,15 +5,15 @@ module Stoplight
     type duration_ms = Float
 
     # Light Colors
-    type green = "green"
-    type yellow = "yellow"
-    type red = "red"
+    type green = :green
+    type yellow = :yellow
+    type red = :red
     type color = green | yellow | red
 
     # Light States
-    type unlocked = "unlocked"
-    type locked_green = "locked_green"
-    type locked_red = "locked_red"
+    type unlocked = :unlocked
+    type locked_green = :locked_green
+    type locked_red = :locked_red
     type state = unlocked | locked_green | locked_red
 
     type recovery_decision = :green | :yellow | :red

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

data/sig/stoplight/wiring/system.rbs

@@ -6,7 +6,28 @@ module Stoplight
       @name: String
       REGISTRATION_FRAME_LIMIT: Integer
 
-      @lights: Concurrent::Map[String, [Domain::Light, Integer, Array[String]]]
+      class Registration < Data
+        attr_reader light: Domain::Light
+        attr_reader digest: Integer
+        attr_reader backtrace: Array[String]
+        attr_reader without_settings: bool
+
+        def self.new: (
+            light: Domain::Light,
+            digest: Integer,
+            backtrace: Array[String],
+            without_settings: bool,
+          ) -> instance
+
+        def initialize: (
+            light: Domain::Light,
+            digest: Integer,
+            backtrace: Array[String],
+            without_settings: bool,
+          ) -> void
+      end
+
+      @lights: Concurrent::Map[String, Registration]
       @failover_system: _System?
       @registry: Domain::_Registry
       @telemetry: Domain::Telemetry::Bus

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 6.0.0.rc2
+  version: 6.0.0.rc5
 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