stoplight 5.8.3 → 6.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe8903aa5cfb542051938b5579384312614da2ffbb937b7eb0be6ce75ae71951
-  data.tar.gz: 5866c336e440464a53b0b7266a44494734c86574e80351bf9ec0406ee9c51f10
+  metadata.gz: 0dc15c81e94d811df03fe4acdd4ff76e3633931a1c4df022b7c26480834135e8
+  data.tar.gz: 82b93fba4751312a3ad6ac33602b0b50c40fc6ebd5d72554d66f040ab7efd133
 SHA512:
-  metadata.gz: a27f2a8da1e01f183d13719efae03132ec938edc6bfaa575c916fa34a4b11da0071135e937d9de1763191a2c99ce2bed55092793b2413f482020ae626c46eac6
-  data.tar.gz: f77a6c5e858e4b8427a4bca1b09450ddbbc9b5aa4d11804167151c0efcfc8e7731f50a1c7e9b40952addb77fd08287c8948b98896ca97d45740e2882933665df
+  metadata.gz: 3a97e8dec725453ffd76e95d7d2ab59ef8929b89aa6ac2350a816d3e280aa49f893d3818dc28d6b465e20bf508c9cf10b37265e6968c436836ba9b5bdc374bb8
+  data.tar.gz: 9550e279df8c4ceaa1cc4de1a76a85dcb2fa84cb079e7dbd3716e699479b5cf94fe1d577f99f713840b693b6520d1c19b8f1b2b01fc9325b6db7cf89abdcfed3

data/CHANGELOG.md

@@ -4,4 +4,4 @@ Stoplight uses [Semantic Versioning][].
 The change log is available [on GitHub][].
 
 [semantic versioning]: http://semver.org/spec/v2.0.0.html
-[on github]: https://github.com/orgsync/stoplight/releases
+[on github]: https://github.com/bolshakov/stoplight/releases

data/LICENSE.md

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2015-2016 Cameron Desautels, Taylor Fausak & Justin Steffy
+Copyright (c) 2019-2026 Tëma Bolshakov, George Asfour and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -8,8 +8,8 @@ Stoplight is a traffic control for code. It's an implementation of the circuit b
 
 ---
 
-:warning:️ You're currently browsing the documentation for Stoplight 5.x. If you're looking for
-the documentation of the previous version 4.x, you can find it [here](https://github.com/bolshakov/stoplight/tree/v4.1.1).
+:warning:️ You're currently browsing the documentation for Stoplight 6. If you're looking for
+the documentation of the previous version 5.x, you can find it [here](https://github.com/bolshakov/stoplight/tree/v5.8.3).
 
 Stoplight helps your application gracefully handle failures in external dependencies
 (like flaky databases, unreliable APIs, or spotty web services). By wrapping these unreliable
@@ -38,22 +38,7 @@ Stoplight uses [Semantic Versioning][]. Check out [the change log][] for a detai
 
 Stoplight operates like a traffic light with three states:
 
-```mermaid
-stateDiagram
-    Green --> Red: Errors reach threshold
-    Red --> Yellow: After cool_off_time
-    Yellow --> Green: Successful recovery
-    Yellow --> Red: Failed recovery
-    Green --> Green: Success
-    
-    classDef greenState fill:#28a745,stroke:#1e7e34,stroke-width:2px,color:#fff
-    classDef redState fill:#dc3545,stroke:#c82333,stroke-width:2px,color:#fff
-    classDef yellowState fill:#ffc107,stroke:#e0a800,stroke-width:2px,color:#000
-    
-    class Green greenState
-    class Red redState
-    class Yellow yellowState
-```
+![Stoplight state diagram][]
 
 - **Green**: Normal operation. Code runs as expected. (Circuit closed)
 - **Red**: Failure state. Fast-fails without running the code. (Circuit open)
@@ -142,53 +127,51 @@ receives `nil`. In both cases, the return value of the fallback becomes the retu
 
 ## Admin Panel
 
-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.
+Stoplight comes with a built-in Admin Panel for observing and controlling all lights across your application. It 
+displays each light's current state, recent failures, and provides controls to lock/unlock lights manually.
 
 ![Admin Panel Screenshot](assets/admin.png)
 
-To add Admin Panel protected by basic authentication to your Rails project, add this configuration to your `config/routes.rb` file.
+### Basic Setup
+
+Add the Admin Panel to your Rails application with authentication:
 
 ```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.
+Then set environment variables:
+```bash
+export STOPLIGHT_ADMIN_USERNAME=admin
+export STOPLIGHT_ADMIN_PASSWORD=secret
+```
 
-**IMPORTANT:** Stoplight Admin Panel requires you to have `sinatra` and `sinatra-contrib` gems installed. You can either add them to your Gemfile:
+**IMPORTANT:** Stoplight Admin Panel requires `sinatra` and `sinatra-contrib` gems:
 
 ```ruby
 gem "sinatra", require: false
 gem "sinatra-contrib", require: false
 ```
 
-Or install it manually:
-```ruby
-gem install sinatra
-gem install sinatra-contrib
-```
+### Standalone Docker Setup
 
-### Standalone Admin Panel Setup
-
-It is possible to run the Admin Panel separately from your application using the `stoplight-admin:<release-version>` docker image.
+Run the Admin Panel as a separate service:
 
 ```shell
-docker run --net=host bolshakov/stoplight-admin
+docker run \
+  -e REDIS_URL=redis://localhost:6379 \
+  -e STOPLIGHT_ADMIN_USERNAME=admin \
+  -e STOPLIGHT_ADMIN_PASSWORD=secret \
+  -p 4567:4567 \
+  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 bolshakov/stoplight-admin
-```
+For complete setup and multi-system configuration details, see the [Admin Panel guide](docs/admin.md).
 
 ## Configuration
 
@@ -226,36 +209,16 @@ light = Stoplight("Payment Service")
 You can also provide settings during creation:
 
 ```ruby
-data_store = Stoplight::DataStore::Redis.new(Redis.new)
-
 light = Stoplight("Payment Service",
   window_size: 300,                       # Only count errors in the last five minutes
   threshold: 5,                           # 5 errors before turning red
   cool_off_time: 60,                      # Wait 60 seconds before attempting recovery
   recovery_threshold: 1,                  # 1 successful attempt to turn green again
-  data_store: data_store,                 # Use Redis for persistence
   tracked_errors: [TimeoutError],         # Only count TimeoutError
   skipped_errors: [ValidationError]       # Ignore ValidationError
 )
 ```
 
-### Modifying Stoplights
-
-You can create specialized versions of existing stoplights:
-
-```ruby
-# Base configuration for API calls
-base_api = Stoplight("Service API")
-
-# Create specialized version for the users endpoint
-users_api = base_api.with(
-  tracked_errors: [TimeoutError]          # Only track timeouts
-)
-```
-
-The `#with` method creates a new stoplight instance without modifying the original, making it ideal for creating
-specialized stoplights from a common configuration.
-
 ## Error Handling
 
 By default, Stoplight tracks all `StandardError` exceptions.
@@ -277,8 +240,41 @@ light = Stoplight("Example API", tracked_errors: [NetworkError, Timeout::Error])
 
 When both methods are used, `skipped_errors` takes precedence over `tracked_errors`.
 
+Either list can be replaced for a single call without changing the light's configuration:
+
+```ruby
+light.run(tracked_errors: [Timeout::Error]) { fetch_data }
+light.run(skipped_errors: [ValidationError]) { process_data }
+```
+
+Any list omitted from `run` keeps its configured value. The provided list is replaced only for that call, and
+`skipped_errors` still takes precedence over `tracked_errors`.
+
 ## Advanced Configuration
 
+### Registering Lights
+
+Calling `Stoplight("name", ...)` at every call site works well for a handful of lights. As an app
+grows, repeating the same settings everywhere makes them easy to drift out of sync, and there's no
+single place listing what lights exist.
+
+Register a light once and look it up by name wherever you need it, instead of repeating the same
+settings at every call site.
+
+```ruby
+# config/initializers/stoplight.rb
+Stoplight.register("Payment Service", threshold: 5, cool_off_time: 60)
+```
+
+```ruby
+# anywhere else in your app
+Stoplight.light("Payment Service").run { payment_gateway.process(order) }
+```
+
+`Stoplight("name", ...)` still works as shown above -- registration is an addition, not a replacement.
+`Stoplight.light` is also approximately 10 times faster, since it's a plain lookup rather than re-validating 
+the configuration on every call.
+
 ### Traffic Control Strategies
 
 You've seen how Stoplight transitions from green to red when errors reach the threshold. But **how exactly does it 
@@ -340,18 +336,9 @@ light = Stoplight(
 
 Monitors error rate over a 5-minute sliding window. The stoplight turns red when error rate exceeds 50%.
 
-```ruby
-light = Stoplight(
-  "Payment API", 
-  traffic_control: {
-    error_rate: { min_requests: 20 },
-  }, 
-  window_size: 300, 
-  threshold: 0.5,
-)
-```
-
-Only evaluates error rate after at least 20 requests within the window. Default `min_requests` is 10.
+Error rate evaluation starts only after 100 requests within the window — enough samples
+for a statistically reliable estimate. If your service handles fewer than 100 requests
+per window, the breaker will never trip on error rate; use `traffic_control: :consecutive_errors` instead.
 
 
 #### When to use:
@@ -488,6 +475,24 @@ By default, Stoplight logs state transitions to STDERR.
 Pull requests to update this section are welcome. If you want to implement your own notifier, refer to
 the [notifier interface documentation] for detailed instructions. Pull requests to update this section are welcome.
 
+### Telemetry
+
+Notifiers only fire on state transitions. For everything else a light does - every run, trip, recovery probe, and
+manual lock - subscribe to the telemetry bus:
+
+```ruby
+Stoplight.telemetry.subscribe(Stoplight::Telemetry::TrafficBreached) do |envelope|
+  logger.warn("#{envelope.light_name} tripped: #{envelope.payload.failure&.exception&.message}")
+end
+```
+
+The [stoplight-statsd] gem is built on this bus. It forwards every event to Statsd, so a dashboard of your circuit
+breakers is a `bundle add` away:
+
+![Stoplight metrics in Grafana](assets/grafana.png)
+
+See the [Telemetry guide](docs/telemetry.md) for the full event list and the envelope format.
+
 ### Error Notifiers
 
 Stoplight is built for resilience. If the Redis data store fails, Stoplight automatically falls back to the in-memory
@@ -522,6 +527,52 @@ light.lock(Stoplight::Color::GREEN)
 light.unlock
 ```
 
+### Multiple Independent Systems
+
+By default, all lights share the same global configuration and data store. For larger applications with multiple 
+services or tenants, you can create **named systems** -- completely isolated instances with their own configuration, 
+notifiers, and data store:
+
+```ruby
+# Create independent systems with separate data stores
+Payments = Stoplight.register_system("Payments", threshold: 3, cool_off_time: 30)
+Analytics = Stoplight.register_system("Analytics", threshold: 5, cool_off_time: 60)
+
+# Register lights in each system
+Payments.register("stripe", cool_off_time: 30)
+Analytics.register("amplitude")
+
+# Use them — one system's state does not affect another
+Payments.light("stripe").run { charge_card }
+Analytics.light("amplitude").run { track_event }
+```
+
+Use cases for multiple systems:
+
+* **Multi-tenancy**: Each tenant gets its own isolated system and data store
+* **Service boundaries**: Separate failure domains with independent SLOs (e.g., payments vs. analytics)
+* **Independent data stores**: One service uses Redis for persistence, another uses in-memory
+
+For complete details on system configuration, boot-time registration patterns, and isolation guarantees, see 
+the [Systems guide](docs/systems.md).
+
+### Admin
+
+Admin Panel can work in an read-only which could be useful for observability. To enabled read-only mode:
+
+```ruby
+Stoplight::Admin.configure do |config|
+  config.read_only = true
+end
+```
+
+Read-only mode could be turned on for a pre-built docker image by passing `STOPLIGHT_ADMIN_READ_ONLY` environment 
+variable:
+
+```sh
+docker run -e REDIS_URL=redis://localhost:6378  -e STOPLIGHT_ADMIN_READ_ONLY=true --net=host bolshakov/stoplight-admin
+```
+
 ## Rails Integration
 
 Wrap controller actions with minimal effort:
@@ -602,13 +653,13 @@ We only actively support the latest major version of Stoplight.
 
 **Ruby**: Major versions that receive security updates (see [Ruby Maintenance Branches]):
 
-* Currently: Ruby 3.2.x, 3.3.x and 3.4.x
+* Currently: Ruby 3.3.x, 3.4.x and 4.0.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])
+* Redis: 8.6.x, 8.4.x, 7.4.x (following [Redis's support policy])
+* Valkey: 9.1.x, 9.0.x, 8.1.x, 8.0.x, 7.2.x (following [Valkey's support policy])
 * We test against the latest version of each major release
 
 For dependencies:
@@ -622,7 +673,7 @@ For dependencies:
 * 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+"
+Example: "Ruby 3.3 reaches end-of-life in March 2027, so Stoplight 7.0 will require Ruby 3.4+"
 
 ## Development
 
@@ -639,15 +690,16 @@ Fowler’s [CircuitBreaker][] article.
 [Stoplight]: https://github.com/bolshakov/stoplight
 [Version badge]: https://img.shields.io/gem/v/stoplight.svg?label=version
 [version]: https://rubygems.org/gems/stoplight
-[Build badge]: https://github.com/bolshakov/stoplight/workflows/Specs/badge.svg
-[build]: https://github.com/bolshakov/stoplight/actions?query=branch%3Amaster
-[Coverage badge]: https://img.shields.io/coveralls/bolshakov/stoplight/master.svg?label=coverage
+[Build badge]: https://github.com/bolshakov/stoplight/actions/workflows/ci.yml/badge.svg?branch=main
+[build]: https://github.com/bolshakov/stoplight/actions?query=branch%3Amain
+[Coverage badge]: https://img.shields.io/coveralls/bolshakov/stoplight/main.svg?label=coverage
 [coverage]: https://coveralls.io/r/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
+[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
 [camdez]: https://github.com/camdez
 [tfausak]: https://github.com/tfausak
@@ -663,3 +715,4 @@ Fowler’s [CircuitBreaker][] article.
 [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
+[Stoplight state diagram]: assets/state-diagram.svg

data/UPGRADING.md

@@ -1,3 +1,261 @@
+## Stoplight 6.0
+
+Stoplight 6.0 is built around a single idea: a light is a named thing your application declares once, not an object
+you rebuild at every call site. Most of the changes below follow from that. The first two need some thought, the rest
+are mechanical.
+
+Here's what you'll want to tackle during your upgrade, roughly ordered from the most involved to the most trivial:
+
+- [ ] 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`
+- [ ] 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
+- [ ] Re-check `error_rate` lights - `min_requests` is gone and the fixed minimum sample is now 100 requests
+- [ ] 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
+- [ ] Test thoroughly in a staging environment
+
+### Lights Are Registered and Reused
+
+In 5.x, each `Stoplight("Payment Service", threshold: 5)` call built a brand-new light. Nothing tied the call sites
+together, so two places could configure the same name differently and both would run - which settings a process ended
+up with depended on which file it executed.
+
+In 6.0, `Stoplight()` registers the light on first call and returns that same cached instance afterwards. If a later
+call passes settings that differ from the registration, Stoplight raises `Stoplight::Error::ConfigurationError`. The
+message names where the light was first registered, and the error's backtrace points at the conflicting call:
+
+```
+Light `Payment Service` already registered with different configuration.
+
+Originally registered at:
+  app/services/payment_service.rb:14:in 'charge'
+
+Lights must have consistent configuration across all call sites.
+```
+
+Your existing code keeps working as long as each name is configured consistently, so for many applications this
+upgrade is a no-op until a stray call site raises. The more durable fix is to register lights once at boot and look
+them up by name:
+
+```ruby
+# config/initializers/stoplight.rb
+Stoplight.register("Payment Service", threshold: 5, cool_off_time: 60)
+```
+
+```ruby
+# anywhere else in your app
+Stoplight.light("Payment Service").run { payment_gateway.charge(order) }
+```
+
+`Stoplight()` still works everywhere it used to - it just expects the same settings each time. `Stoplight.light` is
+the alternative: it takes a name and nothing else, so there's no settings list to keep in sync, and it raises
+`Stoplight::Error::UnregisteredLightError` if that name was never registered.
+
+Lights built from dynamic names (`Stoplight("api-#{endpoint}")`) still work - caching is per name, so each distinct
+name registers once.
+
+### Infrastructure Configuration Moved Out of Individual Lights
+
+`Stoplight()` and `Stoplight.light()` no longer accept `data_store`, `notifiers`, or `error_notifier`. Passing them
+now raises `ArgumentError: unknown keyword`.
+
+These options aren't per-circuit behavior - they describe where your application keeps state and how it reports
+problems. When each light could carry its own, the same light name could end up backed by different stores in
+different processes, so instances never saw each other's failures. It also left no single place listing which lights
+exist and where their state lives, which the Admin dashboard's registry needs.
+
+```ruby
+# Old way that won't work anymore
+light = Stoplight("Payment Service", data_store: Stoplight::DataStore::Redis.new(redis))
+```
+
+Configure infrastructure once, at boot:
+
+```ruby
+# New way
+Stoplight.configure do |config|
+  config.data_store = Stoplight::DataStore::Redis.new(redis)
+  config.notifiers = [Stoplight::Notifier::Logger.new(Rails.logger)]
+  config.error_notifier = ->(error) { Bugsnag.notify(error) }
+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.
+
+### The Light Builder API Is Gone
+
+`Light#with` and the whole `with_*` family are removed: `with_data_store`, `with_cool_off_time`, `with_threshold`,
+`with_window_size`, `with_notifiers`, `with_error_notifier`, `with_tracked_errors`, and `with_skipped_errors`. They
+were marked deprecated in 5.0 and have printed a warning naming this release since 5.7, so most codebases should
+already be clean.
+
+Cloning a light produced a second light sharing the first one's name but not its settings - exactly the configuration
+drift the registration model now rejects.
+
+```ruby
+# Old way
+light = Stoplight("Payment Service").with_threshold(10).with_cool_off_time(30)
+
+# New way
+light = Stoplight("Payment Service", threshold: 10, cool_off_time: 30)
+```
+
+If you were cloning in order to vary error handling per call, you don't need a second light for that anymore -
+`#run` takes per-call overrides:
+
+```ruby
+light.run(skipped_errors: [ActiveRecord::RecordNotFound]) { find_customer }
+```
+
+### Error Matchers Must Be Named Classes or Modules
+
+`tracked_errors` and `skipped_errors` accept named `Class` or `Module` constants only - `StandardError`, your own
+error classes, or a custom class or module overriding `===`. Procs, anonymous classes (`Class.new(StandardError)`),
+and instances raise `ArgumentError`. In 5.x anything responding to `===` was accepted.
+
+Both the registry and the consistency check need a matcher's *name*. The registry writes each light's configuration
+to Redis so the Admin dashboard can list lights it never loaded, and a matcher is stored there as its class name - a
+proc has no name to write. Comparing call sites has the same problem from the other direction: two files that each
+build their own `->(error) { ... }` produce two different objects, so identical-looking configuration would be
+reported as a conflict. A constant is the same matcher everywhere it's mentioned.
+
+```ruby
+# Old way that won't work anymore
+light = Stoplight("Payment Service", skipped_errors: [->(error) { error.is_a?(Timeout::Error) }])
+
+# New way
+light = Stoplight("Payment Service", skipped_errors: [Timeout::Error])
+```
+
+For matching that genuinely needs logic, give it a name and let it override `===`:
+
+```ruby
+module TransientHTTPError
+  def self.===(error) = error.is_a?(Net::HTTPError) && error.response.code.start_with?("5")
+end
+
+light = Stoplight("Payment Service", tracked_errors: [TransientHTTPError])
+```
+
+The restriction applies to registration only. The same two lists can be passed to `#run` as a per-call override, and
+those are never registered, serialized, or compared against another call site - so anything responding to `===` still
+works there, procs included:
+
+```ruby
+light.run(skipped_errors: ->(error) { error.message.include?("rate limit") }) { charge_card }
+```
+
+### Redis Data Gets a Fresh Start Again
+
+Like 5.0 before it, 6.0 moves to a new Redis key schema. Keys are now namespaced `stoplight:v6:...` instead of
+`stoplight:v5:...`, and the storage behind them was decomposed into focused stores for state, metrics, and recovery
+locks.
+
+The reason is the same one that motivated the split: a single monolithic key structure made every read pull data no
+caller needed, and it left no room for the per-light configuration the registry and dashboard now persist. Migrating
+the old format would have meant a rewrite of live data for a value that decays within minutes anyway.
+
+Nothing to change in your code. After deploying, every circuit breaker starts green with no history. For most
+applications that's a non-event, since circuit breakers are meant to react to current conditions - but if you're
+deploying while a dependency is already failing, expect the first failures after the deploy to be passed through
+before the light trips again.
+
+Your old `stoplight:v5:*` keys are ignored from the moment you deploy, and they carry TTLs, so they expire on their
+own. There's no cleanup to do.
+
+### Error Rate No Longer Takes `min_requests`
+
+The `error_rate` traffic control strategy dropped its `min_requests` option. The minimum sample size is now fixed at
+100 requests internally, up from a default of 10.
+
+This changes behavior even if you never passed the option: an `error_rate` light now needs 100 requests in its window
+before it can trip at all.
+
+An error rate is only a useful signal when it's measured over enough requests. Across 10 requests - the old default -
+a single failure moves the rate by 10 percentage points, so the light reacted to normal variation as readily as to a
+real problem. At 100 requests each individual request moves the measurement by one point, which is stable enough to
+act on. Since the value that makes the strategy trustworthy is the one nobody should tune down, it stopped being a
+knob.
+
+The practical consequence is that `error_rate` is a strategy for lights that see real traffic. If a light won't see
+100 requests within its `window_size`, use `:consecutive_errors` instead.
+
+```ruby
+# Old way that won't work anymore
+light = Stoplight("Payment Service", traffic_control: {error_rate: {min_requests: 10}}, threshold: 0.5)
+
+# New way
+light = Stoplight("Payment Service", traffic_control: :error_rate, threshold: 0.5, window_size: 300)
+```
+
+The hash form of `traffic_control` is gone entirely, so passing it raises `Stoplight::Error::ConfigurationError`.
+`Stoplight::Domain::TrafficControl::ErrorRate.new` takes no arguments.
+
+### `window_size` Must Be a Whole Number of Seconds
+
+`window_size` now accepts only an `Integer` of at least 1. A `Float`, or anything below one second, raises
+`Stoplight::Error::ConfigurationError` when the value is applied - at `Stoplight()`, `Stoplight.register_system`, or
+`Stoplight.configure`. `nil` still means "no window".
+
+```ruby
+# Old way that won't work anymore
+light = Stoplight("Payment Service", window_size: 59.5, traffic_control: :error_rate, threshold: 0.5)
+
+# New way
+light = Stoplight("Payment Service", window_size: 60, traffic_control: :error_rate, threshold: 0.5)
+```
+
+Metrics are counted in per-second buckets, so a second is the smallest span the window can actually measure. A
+fractional value was never honoured as written - both stores truncated it to whole buckets, so `window_size: 59.5`
+measured 59 seconds on Redis and 59 or 60 in memory depending on when you asked, and anything under a second evicted
+the current bucket on most calls, so failures rarely accumulated enough to trip the light. None of that has changed -
+the window is measured exactly as it always was. What changes is that the mismatch is no longer hidden: instead of
+quietly measuring a different span than you asked for, Stoplight escalates it as an error the moment the light is
+configured.
+
+### `cool_off_time` Must Be a Whole Number of Seconds
+
+`cool_off_time` now accepts only an `Integer` of at least 1. A `Float`, or anything below one second, raises
+`Stoplight::Error::ConfigurationError` when the value is applied - at `Stoplight()`, `Stoplight.register_system`, or
+`Stoplight.configure`.
+
+```ruby
+# Old way that won't work anymore
+light = Stoplight("Payment Service", cool_off_time: 1.5)
+
+# New way
+light = Stoplight("Payment Service", cool_off_time: 2)
+```
+
+Below a second the light turns yellow again before the failing dependency could plausibly have recovered, so it
+probes on nearly every call instead of breaking the circuit. Above that, a fraction of a second is marginal against
+the window the light measures failures over, so whole seconds are the only granularity worth expressing.
+
+### Clock Skew Detection Is Gone
+
+`Stoplight::DataStore::Redis.new` no longer accepts `warn_on_clock_skew:`. Passing it raises `ArgumentError`.
+
+```ruby
+# Old way that won't work anymore
+Stoplight::DataStore::Redis.new(redis, warn_on_clock_skew: false)
+
+# New way
+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.
+
+### Getting Help
+
+If you run into anything this guide doesn't cover, post to our [Discussions forum]. The configuration errors in 6.0
+try hard to tell you exactly which two call sites disagree and what to do about it, so start by reading the message
+in full - it usually names the file and line you need.
+
 ## Stoplight 5.0 
 
 Stoplight 5.0 introduces several breaking changes, so you'll need to set aside some time to update your code. The good 
@@ -7,12 +265,12 @@ more powerful setup.
 Here's what you'll want to tackle during your upgrade. Don't worry if this looks like a lot - most of these are simple 
 find-and-replace operations:
 
-- [] Update global configuration to use the new block syntax
-- [] Replace any remaining `Stoplight() {}` calls with `Stoplight().run {}`
-- [] Convert error handlers to tracked/skipped error lists
-- [] Move fallbacks from configuration to `#run` method calls
-- [] Account for Stoplight state reset after deployment
-- [] Test thoroughly in a staging environment
+- [ ] Update global configuration to use the new block syntax
+- [ ] Replace any remaining `Stoplight() {}` calls with `Stoplight().run {}`
+- [ ] Convert error handlers to tracked/skipped error lists
+- [ ] Move fallbacks from configuration to `#run` method calls
+- [ ] Account for Stoplight state reset after deployment
+- [ ] Test thoroughly in a staging environment
 
 ### Global Configuration Redesign
 
@@ -300,4 +558,5 @@ Nothing. Stoplight will function as usual.
 [dropped notifiers]: https://github.com/bolshakov/stoplight/tree/v3.0.1/lib/stoplight/notifier
 [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
 [Discussions forum]: https://github.com/bolshakov/stoplight/discussions/categories/q-a

data/lib/stoplight/admin/actions/action.rb

@@ -5,18 +5,10 @@ module Stoplight
     module Actions
       # @abstract
       class Action
-        # @!attribute lights_repository
-        #   @return [Stoplight::Admin::LightsRepository]
-        attr_reader :lights_repository
-        private :lights_repository
-
-        # @return lights_repository [Stoplight::Admin::LightsRepository]
-        def initialize(lights_repository:)
-          @lights_repository = lights_repository
-        end
-
-        def call(params)
-          raise NotImplementedError
+        # Unwinds to Sinatra's route dispatch via `throw :halt`, skipping the rest of the
+        # action and the route block, and using +status+ as the response status.
+        def halt(status)
+          throw :halt, status
         end
       end
     end