stoplight 3.0.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbfed26c7b63f56e88cd970d5db820022a89d689570cd4e98168b7226d718791
-  data.tar.gz: 9206b2c2a66e78d39f37e7932fc95faaf850a2cc54d024eab2a2d90dc14396b4
+  metadata.gz: '0194283983ed6568bca930b6640a7d397dd06e779d921e8bd169cb6a8e743448'
+  data.tar.gz: 9b68b81b05c15cbed7885d8f10a042c0e0ecacafacb0fe6e621e3c124007d74e
 SHA512:
-  metadata.gz: 34d477b3b8e0c6e9b34a0a1ea7e0e6fab4950601d914407063a113f019b9e4a7420b4b291f76702e326b41f3b7cd780adb55f9c2df28bd659c9be7d384af35b4
-  data.tar.gz: ab49c8f6cac59358b78807fa82e88e8ee3cec5c668dad2f6cc0ca8183507dc64373f611c23b83dce4d2d5958f176d6c447e796a9137e87a165b0cabd12b7dc7c
+  metadata.gz: 64c7f5d19bb00b46f9908d938a120c475f1fd60e481e58400c49360dae260bd6c83690e61f34362a20dea0b3b955f4f9b9d76030b8ccbb7c788fd7a531ad395b
+  data.tar.gz: e48e470e7f72d811852df5576b132a11f6f69dedf711cf371c9cfbc4dc1a4600f217b147ba53c9313a8863a06aaef88e279d3cd5f7e8ff51bd69c731123b1093

data/README.md

@@ -9,6 +9,8 @@ Stoplight is traffic control for code. It's an implementation of the circuit
 breaker pattern in Ruby.
 
 ---
+:warning: You're browsing the documentation of the not realized version. You can find the documentation 
+for the most recent version 3.0.1 [here](https://github.com/bolshakov/stoplight/tree/v3.0.1).
 
 Does your code use unreliable systems, like a flaky database or a spotty web
 service? Wrap calls to those up in stoplights to prevent them from affecting
@@ -17,97 +19,88 @@ the rest of your application.
 Check out [stoplight-admin][] for controlling your stoplights.
 
 - [Installation](#installation)
-- [Basic usage](#basic-usage)
-  - [Custom errors](#custom-errors)
-  - [Custom fallback](#custom-fallback)
-  - [Custom threshold](#custom-threshold)
-  - [Custom cool off time](#custom-cool-off-time)
+- [Basic Usage](#basic-usage)
+  - [Custom Errors](#custom-errors)
+  - [Custom Fallback](#custom-fallback)
+  - [Custom Threshold](#custom-threshold)
+  - [Custom Window Size](#custom-window-size)
+  - [Custom Cool Off Time](#custom-cool-off-time)
   - [Rails](#rails)
 - [Setup](#setup)
-  - [Data store](#data-store)
+  - [Data Store](#data-store)
     - [Redis](#redis)
   - [Notifiers](#notifiers)
-    - [Bugsnag](#bugsnag)
-    - [Honeybadger](#honeybadger)
+    - [IO](#io)
     - [Logger](#logger)
-    - [Pagerduty](#pagerduty)
-    - [Rollbar](#rollbar)
-    - [Sentry](#sentry)
-    - [Slack](#slack)
+    - [Community-supported Notifiers](#community-supported-notifiers)
+    - [How to Implement Your Own Notifier?](#how-to-implement-your-own-notifier)
   - [Rails](#rails-1)
-- [Advanced usage](#advanced-usage)
+- [Advanced Usage](#advanced-usage)
   - [Locking](#locking)
   - [Testing](#testing)
+- [Maintenance Policy][#maintenance-policy]
 - [Credits](#credits)
 
 ## Installation
 
 Add it to your Gemfile:
 
-``` rb
+```ruby
 gem 'stoplight'
 ```
 
 Or install it manually:
 
-``` sh
+```sh
 $ gem install stoplight
 ```
 
 Stoplight uses [Semantic Versioning][]. Check out [the change log][] for a
 detailed list of changes.
 
-Stoplight works with all supported versions of Ruby (2.1 through 2.3).
-
-## Basic usage
+## Basic Usage
 
 To get started, create a stoplight:
 
-``` rb
-light = Stoplight('example-pi') { 22.0 / 7 }
-# => #<Stoplight::Light:...>
+```ruby
+light = Stoplight('example-pi')
 ```
 
-Then you can run it and it will return the result of calling the block. This is
-the green state. (The green state corresponds to the closed state for circuit
-  breakers.)
+Then you can run it with a block of code and it will return the result of calling the block. This is
+the green state. (The green state corresponds to the closed state for circuit breakers.)
 
-``` rb
-light.run
+```ruby
+light.run { 22.0 / 7 }
 # => 3.142857142857143
 light.color
 # => "green"
 ```
 
 If everything goes well, you shouldn't even be able to tell that you're using a
-stoplight. That's not very interesting though, so let's create a failing
-stoplight:
+stoplight. That's not very interesting though, so let's make stoplight fail.
 
-``` rb
-light = Stoplight('example-zero') { 1 / 0 }
-# => #<Stoplight::Light:...>
-```
-
-Now when you run it, the error will be recorded and passed through. After
+When you run it, the error will be recorded and passed through. After
 running it a few times, the stoplight will stop trying and fail fast. This is
 the red state. (The red state corresponds to the open state for circuit
-  breakers.)
+breakers.)
 
-``` rb
-light.run
+```ruby
+light = Stoplight('example-zero')
+# => #<Stoplight::CircuitBreaker:...>
+light.run { 1 / 0 }
 # ZeroDivisionError: divided by 0
-light.run
+light.run { 1 / 0 }
 # ZeroDivisionError: divided by 0
-light.run
+light.run { 1 / 0 }
 # Switching example-zero from green to red because ZeroDivisionError divided by 0
 # ZeroDivisionError: divided by 0
-light.run
+light.run { 1 / 0 }
 # Stoplight::Error::RedLight: example-zero
 light.color
 # => "red"
 ```
 
-When the stoplight changes from green to red, it will notify every configured
+When the Stoplight changes from green to red, it will notify every configured
 notifier. See [the notifiers section][] to learn more about notifiers.
 
 The stoplight will move into the yellow state after being in the red state for
@@ -117,7 +110,7 @@ check out [the cool off time section][] When stoplights are yellow, they will
 try to run their code. If it fails, they'll switch back to red. If it succeeds,
 they'll switch to green.
 
-### Custom errors
+### Custom Errors
 
 Some errors shouldn't cause your stoplight to move into the red state. Usually
 these are handled elsewhere in your stack and don't represent real failures. A
@@ -140,89 +133,126 @@ provide a custom block that will be called with the error and a handler
     never ignore the error. That means a `NoMemoryError` could change the color
     of your stoplights.
 
-``` rb
-light = Stoplight('example-not-found') { User.find(123) }
+```ruby
+light = Stoplight('example-not-found')
   .with_error_handler do |error, handle|
-    raise error if error.is_a?(ActiveRecord::RecordNotFound)
-    handle.call(error)
+    if error.is_a?(ActiveRecord::RecordNotFound)
+      raise error
+    else      
+      handle.call(error)
+    end
   end
-# => #<Stoplight::Light:...>
-light.run
+# => #<Stoplight::CircuitBreaker:...>
+light.run { User.find(123) }
 # ActiveRecord::RecordNotFound: Couldn't find User with ID=123
-light.run
+light.run { User.find(123) }
 # ActiveRecord::RecordNotFound: Couldn't find User with ID=123
-light.run
+light.run { User.find(123) }
 # ActiveRecord::RecordNotFound: Couldn't find User with ID=123
 light.color
 # => "green"
 ```
 
-### Custom fallback
+### Custom Fallback
 
 By default, stoplights will re-raise errors when they're green. When they're
 red, they'll raise a `Stoplight::Error::RedLight` error. You can provide a
 fallback that will be called in both of these cases. It will be passed the
 error if the light was green.
 
-``` rb
-light = Stoplight('example-fallback') { 1 / 0 }
+```ruby
+light = Stoplight('example-fallback')
   .with_fallback { |e| p e; 'default' }
-# => #<Stoplight::Light:..>
-light.run
+# => #<Stoplight::CircuitBreaker:..>
+light.run { 1 / 0 }
 # #<ZeroDivisionError: divided by 0>
 # => "default"
-light.run
+light.run { 1 / 0 }
 # #<ZeroDivisionError: divided by 0>
 # => "default"
-light.run
+light.run { 1 / 0 }
 # Switching example-fallback from green to red because ZeroDivisionError divided by 0
 # #<ZeroDivisionError: divided by 0>
 # => "default"
-light.run
+light.run { 1 / 0 }
 # nil
 # => "default"
 ```
 
-### Custom threshold
+### Custom Threshold
 
 Some bits of code might be allowed to fail more or less frequently than others.
 You can configure this by setting a custom threshold.
 
-``` rb
-light = Stoplight('example-threshold') { fail }
+```ruby
+light = Stoplight('example-threshold')
   .with_threshold(1)
-# => #<Stoplight::Light:...>
-light.run
+# => #<Stoplight::CircuitBreaker:...>
+light.run { fail }
 # Switching example-threshold from green to red because RuntimeError
 # RuntimeError:
-light.run
+light.run { fail }
 # Stoplight::Error::RedLight: example-threshold
 ```
 
 The default threshold is `3`.
 
-### Custom cool off time
+### Custom Window Size
+
+By default, all recorded failures, regardless of the time these happen, will count to reach
+the threshold (hence turning the light to red). If needed, a window size can be set,
+meaning you can control how many errors per period of time will count to reach the red
+state.
+
+By default, every recorded failure contributes to reaching the threshold, regardless of when it occurs, 
+causing the stoplight to turn red. By configuring a custom window size, you control how errors are 
+counted within a specified time frame. Here's how it works:
+
+Let's say you set the window size to 2 seconds:
+
+ ```ruby
+window_size_in_seconds = 2
+
+light = Stoplight('example-threshold')
+  .with_window_size(window_size_in_seconds)
+  .with_threshold(1) #=> #<Stoplight::CircuitBreaker:...>
+
+light.run { 1 / 0 } #=> #<ZeroDivisionError: divided by 0>
+sleep(3)
+light.run { 1 / 0 }
+ ```
+
+Without the window size configuration, the second `light.run { 1 / 0 }` call will result in a
+`Stoplight::Error::RedLight` exception being raised, as the stoplight transitions to the red state 
+after the first call. With a sliding window of 2 seconds, only the errors that occur within the latest
+2 seconds are considered. The first error causes the stoplight to turn red, but after 3 seconds 
+(when the second error occurs), the window has shifted, and the stoplight switches to green state 
+causing the error to raise again. This provides a way to focus on the most recent errors.
+
+The default window size is infinity, so all failures counts.
+
+### Custom Cool Off Time
 
 Stoplights will automatically attempt to recover after a certain amount of
 time. A light in the red state for longer than the cool off period will
 transition to the yellow state. This cool off time is customizable.
 
-``` rb
-light = Stoplight('example-cool-off') { fail }
+```ruby
+light = Stoplight('example-cool-off')
   .with_cool_off_time(1)
-# => #<Stoplight::Light:...>
-light.run
+# => #<Stoplight::CircuitBreaker:...>
+light.run { fail }
 # RuntimeError:
-light.run
+light.run { fail }
 # RuntimeError:
-light.run
+light.run { fail }
 # Switching example-cool-off from green to red because RuntimeError
 # RuntimeError:
 sleep(1)
 # => 1
 light.color
 # => "yellow"
-light.run
+light.run { fail }
 # RuntimeError:
 ```
 
@@ -236,19 +266,19 @@ effectively replaces the red state with yellow.
 Stoplight was designed to wrap Rails actions with minimal effort. Here's an
 example configuration:
 
-``` rb
+```ruby
 class ApplicationController < ActionController::Base
   around_action :stoplight
 
   private
 
   def stoplight(&block)
-    Stoplight("#{params[:controller]}##{params[:action]}", &block)
+    Stoplight("#{params[:controller]}##{params[:action]}")
       .with_fallback do |error|
         Rails.logger.error(error)
         render(nothing: true, status: :service_unavailable)
       end
-      .run
+      .run(&block)
   end
 end
 ```
@@ -259,10 +289,10 @@ end
 
 Stoplight uses an in-memory data store out of the box.
 
-``` rb
+```ruby
 require 'stoplight'
 # => true
-Stoplight::Light.default_data_store
+Stoplight.default_data_store
 # => #<Stoplight::DataStore::Memory:...>
 ```
 
@@ -271,17 +301,16 @@ the only supported persistent data store is Redis.
 
 #### Redis
 
-Make sure you have [the Redis gem][] (`~> 3.2`) installed before configuring
-Stoplight.
+Make sure you have [the Redis gem][] installed before configuring Stoplight.
 
-``` rb
+```ruby
 require 'redis'
 # => true
 redis = Redis.new
 # => #<Redis client ...>
 data_store = Stoplight::DataStore::Redis.new(redis)
 # => #<Stoplight::DataStore::Redis:...>
-Stoplight::Light.default_data_store = data_store
+Stoplight.default_data_store = data_store
 # => #<Stoplight::DataStore::Redis:...>
 ```
 
@@ -290,38 +319,26 @@ Stoplight::Light.default_data_store = data_store
 Stoplight sends notifications to standard error by default.
 
 ``` rb
-Stoplight::Light.default_notifiers
+Stoplight.default_notifiers
 # => [#<Stoplight::Notifier::IO:...>]
 ```
 
 If you want to send notifications elsewhere, you'll have to set them up.
 
-#### Bugsnag
-
-Make sure you have [the Bugsnag gem][] (`~> 4.0`) installed before configuring
-Stoplight.
-
-``` rb
-require 'bugsnag'
-# => true
-notifier = Stoplight::Notifier::Bugsnag.new(Bugsnag)
-# => #<Stoplight::Notifier::Bugsnag:...>
-Stoplight::Light.default_notifiers += [notifier]
-# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Bugsnag:...>]
-```
+#### IO
 
-#### Honeybadger
+Stoplight can notify not only into STDOUT, but into any IO object. You can configure 
+the `Stoplight::Notifier::IO` notifier for that.
 
-Make sure you have [the Honeybadger gem][] (`~> 2.5`) installed before
-configuring Stoplight.
+```ruby
+require 'stringio'
 
-``` rb
-require 'honeybadger'
-# => true
-notifier = Stoplight::Notifier::Honeybadger.new('api key')
-# => #<Stoplight::Notifier::Honeybadger:...>
-Stoplight::Light.default_notifiers += [notifier]
-# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Honeybadger:...>]
+io = StringIO.new
+# => #<StringIO:...>
+notifier = Stoplight::Notifier::IO.new(io)
+# => #<Stoplight::Notifier::IO:...>
+Stoplight.default_notifiers += [notifier]
+# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::IO:...>]
 ```
 
 #### Logger
@@ -329,77 +346,48 @@ Stoplight::Light.default_notifiers += [notifier]
 Stoplight can be configured to use [the Logger class][] from the standard
 library.
 
-``` rb
+```ruby
 require 'logger'
 # => true
 logger = Logger.new(STDERR)
 # => #<Logger:...>
 notifier = Stoplight::Notifier::Logger.new(logger)
 # => #<Stoplight::Notifier::Logger:...>
-Stoplight::Light.default_notifiers += [notifier]
+Stoplight.default_notifiers += [notifier]
 # => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Logger:...>]
 ```
 
-#### Pagerduty
-
-Make sure you have [the Pagerduty gem][] (`~> 2.1`) installed before configuring
-Stoplight.
-
-``` rb
-require 'pagerduty'
-# => true
-pagerduty = Pagerduty.new('http://www.example.com/webhook-url')
-# => #<Pagerduty:...>
-notifier = Stoplight::Notifier::Pagerduty.new(pagerduty)
-# => #<Stoplight::Notifier::Pagerduty:...>
-Stoplight::Light.default_notifiers += [notifier]
-# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Pagerduty:...>]
-```
+#### Community-supported Notifiers
 
-#### Rollbar
+* [stoplight-sentry]
 
-Make sure you have [the Rollbar gem][] (`~> 2.0`) installed before configuring
-Stoplight.
+You you want to implement your own notifier, the following section contains all the required information.
 
-``` rb
-require 'rollbar'
-# => true
-notifier = Stoplight::Notifier::Rollbar.new(Rollbar)
-# => #<Stoplight::Notifier::Rollbar:...>
-Stoplight::Light.default_notifiers += [notifier]
-# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Rollbar:...>]
-```
+Pull requests to update this section are welcome.
 
-#### Sentry
+#### How to implement your own notifier?
 
-Make sure you have [the Sentry gem][] (`~> 1.2`) installed before configuring
-Stoplight.
+A notifier has to implement the `Stoplight::Notifier::Base` interface:
 
-``` rb
-require 'sentry-raven'
-# => true
-configuration = Raven::Configuration.new
-# => #<Raven::Configuration:...>
-notifier = Stoplight::Notifier::Raven.new(configuration)
-# => #<Stoplight::Notifier::Raven:...>
-Stoplight::Light.default_notifiers += [notifier]
-# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Raven:...>]
+```ruby
+def notify(light, from_color, to_color, error)
+  raise NotImplementedError
+end
 ```
 
-#### Slack
+For convenience, you can use the `Stoplight::Notifier::Generic` module. It takes care of
+the message formatting, and you have to implement only the `put` method, which takes message sting as an argument:
 
-Make sure you have [the Slack gem][] (`~> 1.3`) installed before configuring
-Stoplight.
-
-``` rb
-require 'slack-notifier'
-# => true
-slack = Slack::Notifier.new('http://www.example.com/webhook-url')
-# => #<Slack::Notifier:...>
-notifier = Stoplight::Notifier::Slack.new(slack)
-# => #<Stoplight::Notifier::Slack:...>
-Stoplight::Light.default_notifiers += [notifier]
-# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::Slack:...>]
+```ruby 
+class IO < Stoplight::Notifier::Base
+  include Generic
+   
+  private
+    
+  def put(message)
+    @object.puts(message)
+  end
+end
 ```
 
 ### Rails
@@ -409,11 +397,11 @@ in-memory data store, you don't need to do anything special. If you want to use
 a persistent data store, you'll need to configure it. Create an initializer for
 Stoplight:
 
-``` rb
+```ruby
 # config/initializers/stoplight.rb
 require 'stoplight'
-Stoplight::Light.default_data_store = Stoplight::DataStore::Redis.new(...)
-Stoplight::Light.default_notifiers += [Stoplight::Notifier::Logger.new(Rails.logger)]
+Stoplight.default_data_store = Stoplight::DataStore::Redis.new(...)
+Stoplight.default_notifiers += [Stoplight::Notifier::Logger.new(Rails.logger)]
 ```
 
 ## Advanced usage
@@ -421,17 +409,17 @@ Stoplight::Light.default_notifiers += [Stoplight::Notifier::Logger.new(Rails.log
 ### Locking
 
 Although stoplights can operate on their own, occasionally you may want to
-override the default behavior. You can lock a light in either the green or red
-state using `set_state`.
+override the default behavior. You can lock a light using `#lock(color)` method.
+Color should be either `Stoplight::Color::GREEN` or ``Stoplight::Color::RED``.
 
-``` rb
-light = Stoplight('example-locked') { true }
-# => #<Stoplight::Light:..>
-light.run
+```ruby
+light = Stoplight('example-locked')
+# => #<Stoplight::CircuitBreaker:..>
+light.run { true }
 # => true
-light.data_store.set_state(light, Stoplight::State::LOCKED_RED)
-# => "locked_red"
-light.run
+light.lock(Stoplight::Color::RED)
+# => #<Stoplight::CircuitBreaker:..>
+light.run { true } 
 # Stoplight::Error::RedLight: example-locked
 ```
 
@@ -440,10 +428,11 @@ have configured a custom data store and that data store fails, Stoplight will
 switch over to using a blank in-memory data store. That means you will lose the
 locked state of any stoplights.
 
-You can go back to using the default behavior by unlocking the stoplight.
+You can go back to using the default behavior by unlocking the stoplight using `#unlock`.
 
-``` rb
-light.data_store.set_state(light, Stoplight::State::UNLOCKED)
+```ruby
+light.unlock
+# => #<Stoplight::CircuitBreaker:..>
 ```
 
 ### Testing
@@ -453,28 +442,34 @@ However there are a few things you can do to make them behave better. If your
 stoplights are spewing messages into your test output, you can silence them
 with a couple configuration changes.
 
-``` rb
-Stoplight::Light.default_error_notifier = -> _ {}
-Stoplight::Light.default_notifiers = []
+```ruby
+Stoplight.default_error_notifier = -> _ {}
+Stoplight.default_notifiers = []
 ```
 
 If your tests mysteriously fail because stoplights are the wrong color, you can
 try resetting the data store before each test case. For example, this would
 give each test case a fresh data store with RSpec.
 
-``` rb
+```ruby
 before(:each) do
-  Stoplight::Light.default_data_store = Stoplight::DataStore::Memory.new
+  Stoplight.default_data_store = Stoplight::DataStore::Memory.new
 end
 ```
 
 Sometimes you may want to test stoplights directly. You can avoid resetting the
 data store by giving each stoplight a unique name.
 
-``` rb
-stoplight = Stoplight("test-#{rand}") { ... }
+```ruby
+stoplight = Stoplight("test-#{rand}")
 ```
 
+## Maintenance Policy
+
+Stoplight supports the latest three minor versions of Ruby, which currently are: `3.0.x`, `3.1.x`, and `3.2.x`. Changing
+the minimum supported Ruby version is not considered a breaking change.
+We support the current stable Redis version (`7.2`) and the latest release of the previous major version (`6.2.9`)
+
 ## Credits
 
 Stoplight is brought to you by [@camdez][] and [@tfausak][] from [@OrgSync][]. [@bolshakov][] is the current 
@@ -512,3 +507,4 @@ Stoplight is licensed under [the MIT License][].
 [complete list of contributors]: https://github.com/bolshakov/stoplight/graphs/contributors
 [CircuitBreaker]: http://martinfowler.com/bliki/CircuitBreaker.html
 [the MIT license]: LICENSE.md
+[stoplight-sentry]: https://github.com/bolshakov/stoplight-sentry