stoplight 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 314c63808a80e427881c2d09152f74e68f4ffd37
-  data.tar.gz: 67ab9ca03f20512f5b119b95eec17494d7fdf726
+  metadata.gz: ad268d747b85be7b3a0d773d9aeec70b1b22c25a
+  data.tar.gz: 56c5c8f88361a3c9d705212d9725251017097ddb
 SHA512:
-  metadata.gz: 5a758d0cd6beeb2b0c034f424ec4b4b2fc1fe72f11a7eb598fe195e408437ec6ba3dd95aa9b29554d5a9e8a0727fabbfdc46aade4a7c1674cf457467459032c5
-  data.tar.gz: 50eb0565526a389406422fdca3b93a9ce4923bd7ab7e50aa558b976ca09ed56ee976c9bcc3fc4b0f72c6a28290964e4a676d1c6dbb741ae45fed26b9f30619ab
+  metadata.gz: 043418c2e767031b2a229ad2e22d378c52101d342cdec3bb600bec88c5c46238c345eadb558d779ccedb8f60122b81b5cddf969dfb7dbf475e7bfe3e0cb7b3c2
+  data.tar.gz: 8a9952d663eb04f03e05736f3541ac09b69e69776c80265116d43a7c4c4e2e8d699691598ef8ae35d1c0018b5bc7880f73614894d79e194987961e857c2f7016

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+This project uses [Semantic Versioning][1].
+
+- Data stores and notifiers can be configured on a per-stoplight basis. This
+  allows stoplights to use stoplights internally.
+- Stoplights use stoplights internally to wrap calls to data stores and
+  notifiers. This means they gracefully handle either going down.
+- Data stores only store failures and states. Also failures are stored in a ring
+  buffer. This drastically reduces the amount of data stored.
+- Stoplights will use the fallback (if it's given) when they fail while they're
+  green. This means they won't re-raise exceptions if you provide a fallback.
+- Stoplights pass the error to their notifiers when transitioning from green to
+  red.
+
 ## v0.4.1 (2014-10-03)
 
 - Fixed a bug that caused green to red notifications to sometimes not be sent.
@@ -62,3 +75,5 @@
 ## v0.1.0 (2014-08-12)
 
 - Initial release.
+
+[1]: http://semver.org/spec/v2.0.0.html

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Cameron Desautels & Taylor Fausak
+Copyright (c) 2014 Cameron Desautels, Taylor Fausak & Justin Steffy
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.md

@@ -33,7 +33,7 @@ Check out [stoplight-admin][12] for controlling your stoplights.
 Add it to your Gemfile:
 
 ``` rb
-gem 'stoplight', '~> 0.4.1'
+gem 'stoplight', '~> 0.5.0'
 ```
 
 Or install it manually:
@@ -42,8 +42,6 @@ Or install it manually:
 $ gem install stoplight
 ```
 
-This project uses [Semantic Versioning][13].
-
 ## Setup
 
 ### Data store
@@ -53,22 +51,22 @@ Stoplight uses an in-memory data store out of the box.
 ``` irb
 >> require 'stoplight'
 => true
->> Stoplight.data_store
+>> Stoplight::Light.default_data_store
 => #<Stoplight::DataStore::Memory:...>
 ```
 
 If you want to use a persistent data store, you'll have to set it up. Currently
 the only supported persistent data store is Redis. Make sure you have [the Redis
-gem][14] installed before configuring Stoplight.
+gem][13] installed before configuring Stoplight.
 
 ``` irb
 >> require 'redis'
 => true
->> redis = Redis.new(url: 'redis://127.0.0.1:6379/0')
-=> #<Redis:...>
+>> redis = Redis.new
+=> #<Redis client ...>
 >> data_store = Stoplight::DataStore::Redis.new(redis)
 => #<Stoplight::DataStore::Redis:...>
->> Stoplight.data_store = data_store
+>> Stoplight::Light.default_data_store = data_store
 => #<Stoplight::DataStore::Redis:...>
 ```
 
@@ -77,22 +75,22 @@ gem][14] installed before configuring Stoplight.
 Stoplight sends notifications to standard error by default.
 
 ``` irb
->> Stoplight.notifiers
+>> Stoplight::Light.default_notifiers
 => [#<Stoplight::Notifier::IO:...>]
 ```
 
 If you want to send notifications elsewhere, you'll have to set them up.
 Currently the only other supported notifier is HipChat. Make sure you have [the
-HipChat gem][15] installed before configuring Stoplight.
+HipChat gem][14] installed before configuring Stoplight.
 
 ``` irb
 >> require 'hipchat'
 => true
->> hipchat = HipChat::Client.new('token')
+>> hip_chat = HipChat::Client.new('token')
 => #<HipChat::Client:...>
->> notifier = Stoplight::Notifier::HipChat.new(hipchat, 'room')
+>> notifier = Stoplight::Notifier::HipChat.new(hip_chat, 'room')
 => #<Stoplight::Notifier::HipChat:...>
->> Stoplight.notifiers << notifier
+>> Stoplight::Light.default_notifiers += [notifier]
 => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::HipChat:...>]
 ```
 
@@ -106,8 +104,8 @@ Stoplight:
 ``` rb
 # config/initializers/stoplight.rb
 require 'stoplight'
-Stoplight.data_store = Stoplight::DataStore::Redis.new(...)
-Stoplight.notifiers << Stoplight::Notifier::HipChat.new(...)
+Stoplight::Light.default_data_store = Stoplight::DataStore::Redis.new(...)
+Stoplight::Light.default_notifiers += [Stoplight::Notifier::HipChat.new(...)]
 ```
 
 ## Basic usage
@@ -125,8 +123,8 @@ the green state.
 ``` irb
 >> light.run
 => 3.142857142857143
->> light.green?
-=> true
+>> light.color
+=> "green"
 ```
 
 If everything goes well, you shouldn't even be able to tell that you're using a
@@ -147,12 +145,12 @@ ZeroDivisionError: divided by 0
 >> light.run
 ZeroDivisionError: divided by 0
 >> light.run
+Switching example-2 from green to red because ZeroDivisionError divided by 0
 ZeroDivisionError: divided by 0
 >> light.run
-Switching example-2 from green to red.
 Stoplight::Error::RedLight: example-2
->> light.red?
-=> true
+>> light.color
+=> "red"
 ```
 
 When the stoplight changes from green to red, it will notify every configured
@@ -165,7 +163,7 @@ these are handled elsewhere in your stack and don't represent real failures. A
 good example is `ActiveRecord::RecordNotFound`.
 
 ``` irb
->> light = Stoplight::Light.new('example-4') { User.find(123) }.
+>> light = Stoplight::Light.new('example-3') { User.find(123) }.
 ..   with_allowed_errors([ActiveRecord::RecordNotFound])
 => #<Stoplight::Light:...>
 >> light.run
@@ -174,28 +172,34 @@ ActiveRecord::RecordNotFound: Couldn't find User with ID=123
 ActiveRecord::RecordNotFound: Couldn't find User with ID=123
 >> light.run
 ActiveRecord::RecordNotFound: Couldn't find User with ID=123
->> light.green?
-=> true
+>> light.color
+=> "green"
 ```
 
 ### Custom fallback
 
-Instead of raising a `Stoplight::Error::RedLight` error when in the red state,
-you can provide a block to be run. This is useful when there's a good default
-value for the block.
+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.
 
 ``` irb
->> light = Stoplight::Light.new('example-5') { fail }.
-..   with_fallback { [] }
-=> #<Stoplight::Light:...>
+>> light = Stoplight::Light.new('example-4') { 1 / 0 }.
+..   with_fallback { |e| p e; 'default' }
+=> #<Stoplight::Light:..>
 >> light.run
-RuntimeError:
+#<ZeroDivisionError: divided by 0>
+=> "default"
 >> light.run
-RuntimeError:
+#<ZeroDivisionError: divided by 0>
+=> "default"
 >> light.run
-RuntimeError:
+Switching example-4 from green to red because ZeroDivisionError divided by 0
+#<ZeroDivisionError: divided by 0>
+=> "default"
 >> light.run
-=> []
+nil
+=> "default"
 ```
 
 ### Custom threshold
@@ -204,13 +208,14 @@ Some bits of code might be allowed to fail more or less frequently than others.
 You can configure this by setting a custom threshold in seconds.
 
 ``` irb
->> light = Stoplight::Light.new('example-6') { fail }.
+>> light = Stoplight::Light.new('example-5') { fail }.
 ..   with_threshold(1)
 => #<Stoplight::Light:...>
 >> light.run
+Switching example-5 from green to red because RuntimeError
 RuntimeError:
 >> light.run
-Stoplight::Error::RedLight: example-6
+Stoplight::Error::RedLight: example-5
 ```
 
 ### Custom timeout
@@ -220,7 +225,7 @@ A light in the red state for longer than the timeout will transition to the
 yellow state. This timeout is customizable.
 
 ``` irb
->> light = Stoplight::Light.new('example-7') { fail }.
+>> light = Stoplight::Light.new('example-6') { fail }.
 ..   with_timeout(1)
 => #<Stoplight::Light:...>
 >> light.run
@@ -228,14 +233,12 @@ RuntimeError:
 >> light.run
 RuntimeError:
 >> light.run
+Switching example-6 from green to red because RuntimeError
 RuntimeError:
->> light.run
-Switching example-7 from green to red.
-Stoplight::Error::RedLight: example-7
 >> sleep(1)
 => 1
->> light.yellow?
-=> true
+>> light.color
+=> "yellow"
 >> light.run
 RuntimeError:
 ```
@@ -254,7 +257,10 @@ class ApplicationController < ActionController::Base
   def stoplight(&block)
     Stoplight::Light.new("#{params[:controller]}##{params[:action]}", &block)
       .with_allowed_errors([ActiveRecord::RecordNotFound])
-      .with_fallback { render(nothing: true, status: :service_unavailable) }
+      .with_fallback do |error|
+        Rails.logger.error(error)
+        render(nothing: true, status: :service_unavailable)
+      end
       .run
   end
 end
@@ -269,16 +275,14 @@ override the default behavior. You can lock a light in either the green or red
 state using `set_state`.
 
 ``` irb
->> light = Stoplight::Light.new('example-8') { true }
-=> #<Stoplight::Light:...>
+>> light = Stoplight::Light.new('example-7') { true }
+=> #<Stoplight::Light:..>
 >> light.run
 => true
->> Stoplight.data_store.set_state(
-..   light.name, Stoplight::DataStore::STATE_LOCKED_RED)
+>> light.data_store.set_state(light, Stoplight::State::LOCKED_RED)
 => "locked_red"
 >> light.run
-Switching example-8 from green to red
-Stoplight::Error::RedLight: example-8
+Stoplight::Error::RedLight: example-7
 ```
 
 **Code in locked red lights may still run under certain conditions!** If you
@@ -288,13 +292,13 @@ locked state of any stoplights.
 
 ## Credits
 
-Stoplight is brought to you by [@camdez][16] and [@tfausak][17] from
-[@OrgSync][18]. We were inspired by Martin Fowler's [CircuitBreaker][19]
+Stoplight is brought to you by [@camdez][15] and [@tfausak][16] from
+[@OrgSync][17]. We were inspired by Martin Fowler's [CircuitBreaker][18]
 article.
 
 If this gem isn't cutting it for you, there are a few alternatives, including:
-[circuit_b][20], [circuit_breaker][21], [simple_circuit_breaker][22], and
-[ya_circuit_breaker][23].
+[circuit_b][19], [circuit_breaker][20], [simple_circuit_breaker][21], and
+[ya_circuit_breaker][22].
 
 [1]: https://github.com/orgsync/stoplight
 [2]: https://badge.fury.io/rb/stoplight.svg
@@ -308,14 +312,13 @@ If this gem isn't cutting it for you, there are a few alternatives, including:
 [10]: https://gemnasium.com/orgsync/stoplight.svg
 [11]: https://gemnasium.com/orgsync/stoplight
 [12]: https://github.com/orgsync/stoplight-admin
-[13]: http://semver.org/spec/v2.0.0.html
-[14]: https://rubygems.org/gems/redis
-[15]: https://rubygems.org/gems/hipchat
-[16]: https://github.com/camdez
-[17]: https://github.com/tfausak
-[18]: https://github.com/OrgSync
-[19]: http://martinfowler.com/bliki/CircuitBreaker.html
-[20]: https://github.com/alg/circuit_b
-[21]: https://github.com/wsargent/circuit_breaker
-[22]: https://github.com/soundcloud/simple_circuit_breaker
-[23]: https://github.com/wooga/circuit_breaker
+[13]: https://rubygems.org/gems/redis
+[14]: https://rubygems.org/gems/hipchat
+[15]: https://github.com/camdez
+[16]: https://github.com/tfausak
+[17]: https://github.com/OrgSync
+[18]: http://martinfowler.com/bliki/CircuitBreaker.html
+[19]: https://github.com/alg/circuit_b
+[20]: https://github.com/wsargent/circuit_breaker
+[21]: https://github.com/soundcloud/simple_circuit_breaker
+[22]: https://github.com/wooga/circuit_breaker

data/lib/stoplight.rb

@@ -1,29 +1,24 @@
 # coding: utf-8
 
+require 'stoplight/color'
+require 'stoplight/error'
+require 'stoplight/failure'
+require 'stoplight/state'
+
 require 'stoplight/data_store'
 require 'stoplight/data_store/base'
 require 'stoplight/data_store/memory'
 require 'stoplight/data_store/redis'
-require 'stoplight/error'
-require 'stoplight/failure'
-require 'stoplight/light'
+
 require 'stoplight/notifier'
 require 'stoplight/notifier/base'
 require 'stoplight/notifier/hip_chat'
 require 'stoplight/notifier/io'
 
-module Stoplight
-  # @return [Gem::Version]
-  VERSION = Gem::Version.new('0.4.1')
-
-  @data_store = DataStore::Memory.new
-  @notifiers = [Notifier::IO.new($stderr)]
+require 'stoplight/default'
 
-  class << self
-    # @return [DataStore::Base]
-    attr_accessor :data_store
+require 'stoplight/light/runnable'
+require 'stoplight/light'
 
-    # @return [Array<Notifier::Base>]
-    attr_accessor :notifiers
-  end
+module Stoplight
 end

data/lib/stoplight/color.rb

@@ -0,0 +1,9 @@
+# coding: utf-8
+
+module Stoplight
+  module Color
+    GREEN = 'green'.freeze
+    YELLOW = 'yellow'.freeze
+    RED = 'red'.freeze
+  end
+end

data/lib/stoplight/data_store.rb

@@ -2,151 +2,5 @@
 
 module Stoplight
   module DataStore
-    KEY_PREFIX = 'stoplight'.freeze
-
-    COLOR_GREEN = 'green'.freeze
-    COLOR_YELLOW = 'yellow'.freeze
-    COLOR_RED = 'red'.freeze
-    COLORS = Set.new([
-      COLOR_GREEN,
-      COLOR_YELLOW,
-      COLOR_RED
-    ]).freeze
-
-    STATE_UNLOCKED = 'unlocked'.freeze
-    STATE_LOCKED_GREEN = 'locked_green'.freeze
-    STATE_LOCKED_RED = 'locked_red'.freeze
-    STATES = Set.new([
-      STATE_UNLOCKED,
-      STATE_LOCKED_GREEN,
-      STATE_LOCKED_RED
-    ]).freeze
-
-    DEFAULT_ATTEMPTS = 0
-    DEFAULT_FAILURES = []
-    DEFAULT_STATE = STATE_UNLOCKED
-    DEFAULT_THRESHOLD = 3
-    DEFAULT_TIMEOUT = 60
-
-    module_function
-
-    # @group Colors
-
-    # @param state [String]
-    # @param threshold [Integer]
-    # @param failures [Array<Failure>]
-    # @param timeout [Integer]
-    # @return [String]
-    def colorize(state, threshold, failures, timeout)
-      case
-      when state == STATE_LOCKED_GREEN then COLOR_GREEN
-      when state == STATE_LOCKED_RED then COLOR_RED
-      when failures.size < threshold then COLOR_GREEN
-      when Time.now - failures.last.time > timeout then COLOR_YELLOW
-      else COLOR_RED
-      end
-    end
-
-    # @group Validation
-
-    # @param color [String]
-    # @raise [ArgumentError]
-    def validate_color!(color)
-      return if valid_color?(color)
-      fail Error::InvalidColor, color.inspect
-    end
-
-    # @param color [String]
-    # @return [Boolean]
-    def valid_color?(color)
-      COLORS.include?(color)
-    end
-
-    # @param failure [Failure]
-    # @raise [ArgumentError]
-    def validate_failure!(failure)
-      return if valid_failure?(failure)
-      fail Error::InvalidFailure, failure.inspect
-    end
-
-    # @param failure [Failure]
-    # @return [Boolean]
-    def valid_failure?(failure)
-      failure.is_a?(Failure)
-    end
-
-    # @param state [String]
-    # @raise [ArgumentError]
-    def validate_state!(state)
-      return if valid_state?(state)
-      fail Error::InvalidState, state.inspect
-    end
-
-    # @param state [String]
-    # @return [Boolean]
-    def valid_state?(state)
-      STATES.include?(state)
-    end
-
-    # @param threshold [Integer]
-    # @raise [ArgumentError]
-    def validate_threshold!(threshold)
-      return if valid_threshold?(threshold)
-      fail Error::InvalidThreshold, threshold.inspect
-    end
-
-    # @param threshold [Integer]
-    # @return [Boolean]
-    def valid_threshold?(threshold)
-      threshold.is_a?(Integer) && threshold > 0
-    end
-
-    # @param timeout [Integer]
-    # @raise [ArgumentError]
-    def validate_timeout!(timeout)
-      return if valid_timeout?(timeout)
-      fail Error::InvalidTimeout, timeout.inspect
-    end
-
-    # @param timeout [Integer]
-    # @return [Boolean]
-    def valid_timeout?(timeout)
-      timeout.is_a?(Integer)
-    end
-
-    # @group Keys
-
-    # @return (see #key)
-    def attempts_key
-      key('attempts')
-    end
-
-    # @param name [String]
-    # @return (see #key)
-    def failures_key(name)
-      key('failures', name)
-    end
-
-    # @return (see #key)
-    def states_key
-      key('states')
-    end
-
-    # @return (see #key)
-    def thresholds_key
-      key('thresholds')
-    end
-
-    # @return (see #key)
-    def timeouts_key
-      key('timeouts')
-    end
-
-    # @param slug [String]
-    # @param suffix [String, nil]
-    # @return [String]
-    def key(slug, suffix = nil)
-      [KEY_PREFIX, slug, suffix].compact.join(':')
-    end
   end
 end