stoplight 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9bd1ff4a7ba5920b6b1a5e98c829b88ca495ec2
-  data.tar.gz: 3c7698e907ec212e7072b14c9d4df4e54dd9c1b9
+  metadata.gz: 82aa52cf8e9479e0549ca21744fe67cbfda5aab8
+  data.tar.gz: fbc0abddcaa21e460473e94cd3784f6bb726c832
 SHA512:
-  metadata.gz: 4e9fe6173c1b7524fe02ec8939512aea3c0a4cb5cf09ccf5f6cacde09ed461fc6ccfc1b4fc37eaf5008206b398d2aab9b71f5d9c1c39b94ded8ef4a57fb7b942
-  data.tar.gz: f6a8ffb8069abad09d6a795c5acc368b6ea954e8d9d3c6359d36b61e54625923727834a49b1ac827c55cda32d2e36a9b7d16ae9fc9939cd2f35cf14870e93a7b
+  metadata.gz: a37ee7366b9d46a8a063eeb7f3541dfaa08e474869640993de0885779261bcda58be4e3eb7968e6d24fcb044dcd2c2e1f3edcf58e29383028340c80065d6c093
+  data.tar.gz: d0a1bf0cada95b072940372e030bf9007fedbed6a17ba109430a98a62a189d22552018e4685f1d5d0b20c7e4a87a02b47e94ec55abb3c4b48893237bd058b0e4

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.2.0 (2014-08-18)
+
+- Switched `Stoplight.data_store` and `Stoplight.notifiers` over to using
+  simple accessors.
+- Modified `Stoplight::DataStore::Redis` to accept an instance of `Redis`.
+- Refactored `Stoplight::DataStore::Redis` to use fewer keys.
+- Created `Stoplight::Notifier` and subclasses.
+- Sent notifications when moving from green to red.
+- Renamed `Stoplight::Light::DEFAULT_THRESHOLD` to
+  `Stoplight::DEFAULT_THRESHOLD`.
+- Renamed `Stoplight::Error::NoFallback` to `Stoplight::Error::RedLight`.
+- Created `Stoplight::Mixin#stoplight` for easily creating and running simple
+  stoplights.
+
 ## v0.1.0 (2014-08-12)
 
 - Initial release.

data/README.md

@@ -6,14 +6,17 @@
 [![Quality status][8]][9]
 [![Dependency status][10]][11]
 
-Traffic control for code. An implementation of the circuit breaker pattern in Ruby.
+Traffic control for code. An implementation of the circuit breaker pattern in
+Ruby.
+
+Check out [stoplight-admin][12] for controlling your stoplights.
 
 ## Installation
 
 Add it to your Gemfile:
 
 ``` rb
-gem 'stoplight', '~> 0.1.0'
+gem 'stoplight', '~> 0.2.0'
 ```
 
 Or install it manually:
@@ -22,10 +25,12 @@ Or install it manually:
 $ gem install stoplight
 ```
 
-This project uses [Semantic Versioning][12].
+This project uses [Semantic Versioning][13].
 
 ## Setup
 
+### Data store
+
 Stoplight uses an in-memory data store out of the box.
 
 ``` irb
@@ -37,15 +42,39 @@ Stoplight uses an in-memory data store out of the box.
 
 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][13] installed before configuring Stoplight.
+gem][14] installed before configuring Stoplight.
 
 ``` irb
->> redis = Stoplight::DataStore::Redis.new(url: 'redis://127.0.0.1:6379/0')
+>> redis = Redis.new(url: 'redis://127.0.0.1:6379/0')
+=> #<Redis:...>
+>> data_store = Stoplight::DataStore::Redis.new(redis)
 => #<Stoplight::DataStore::Redis:...>
->> Stoplight.data_store(redis)
+>> Stoplight.data_store = data_store
 => #<Stoplight::DataStore::Redis:...>
 ```
 
+### Notifiers
+
+Stoplight sends notifications to standard error by default.
+
+``` irb
+>> Stoplight.notifiers
+=> [#<Stoplight::Notifier::StandardError:...>]
+```
+
+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][] installed before configuring Stoplight.
+
+``` irb
+>> hipchat = HipChat::Client.new('token')
+=> #<HipChat::Client:...>
+>> notifier = Stoplight::Notifier::HipChat.new(hipchat, 'room')
+=> #<Stoplight::Notifier::HipChat:...>
+>> Stoplight.notifiers = [notifier])
+=> [#<Stoplight::Notifier::HipChat:...>]
+```
+
 ### Rails
 
 Stoplight is designed to work seamlessly with Rails. If you want to use the
@@ -56,7 +85,7 @@ Stoplight:
 ``` rb
 # config/initializers/stoplight.rb
 require 'stoplight'
-Stoplight.data_store(Stoplight::DataStore::Redis.new(...))
+Stoplight.data_store = Stoplight::DataStore::Redis.new(...)
 ```
 
 ## Usage
@@ -98,11 +127,26 @@ ZeroDivisionError: divided by 0
 >> light.run
 ZeroDivisionError: divided by 0
 >> light.run
-Stoplight::Error::NoFallback: Stoplight::Error::NoFallback
+Stoplight::Error::RedLight: Stoplight::Error::RedLight
 >> light.red?
 => true
 ```
 
+When the stoplight changes from green to red, it will notify every configured
+notifier.
+
+### Mixin
+
+Since creating and running a stoplight is so common, we provide a mixin that
+makes it easy.
+
+``` irb
+>> include Stoplight::Mixin
+=> Object
+>> stoplight('example-3') { 1.0 / 3 }
+=> 0.3333333333333333
+```
+
 ### Custom errors
 
 Some errors shouldn't cause your stoplight to move into the red state. Usually
@@ -110,7 +154,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-3') { User.find(123) }.
+>> light = Stoplight::Light.new('example-4') { User.find(123) }.
 ?> with_allowed_errors([ActiveRecord::RecordNotFound])
 => #<Stoplight::Light:...>
 >> light.run
@@ -125,12 +169,12 @@ ActiveRecord::RecordNotFound: Couldn't find User with ID=123
 
 ### Custom fallback
 
-Instead of raising a `Stoplight::Error::NoFallback` error when in the red state,
+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.
 
 ``` irb
->> light = Stoplight::Light.new('example-4') { fail }.
+>> light = Stoplight::Light.new('example-5') { fail }.
 ?> with_fallback { [] }
 => #<Stoplight::Light:...>
 >> light.run
@@ -149,13 +193,13 @@ 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-5') { fail }.
+>> light = Stoplight::Light.new('example-6') { fail }.
 ?> with_threshold(1)
 => #<Stoplight::Light:...>
 >> light.run
 RuntimeError:
 >> light.run
-Stoplight::Error::NoFallback: Stoplight::Error::NoFallback
+Stoplight::Error::RedLight: Stoplight::Error::RedLight
 ```
 
 ### Rails
@@ -178,12 +222,12 @@ end
 
 ## Credits
 
-Stoplight is brought to you by [@camdez][14] and [@tfausak][15] from [@OrgSync][16]. We were
-inspired by Martin Fowler's [CircuitBreaker][17] article.
+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][18], [circuit_breaker][19], [simple_circuit_breaker][20], and
-[ya_circuit_breaker][21].
+[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
@@ -196,13 +240,15 @@ If this gem isn't cutting it for you, there are a few alternatives, including:
 [9]: https://codeclimate.com/github/orgsync/stoplight
 [10]: https://gemnasium.com/orgsync/stoplight.svg
 [11]: https://gemnasium.com/orgsync/stoplight
-[12]: http://semver.org/spec/v2.0.0.html
-[13]: https://rubygems.org/gems/redis
-[14]: https://github.com/camdez
-[15]: https://github.com/tfausak
-[16]: https://github.com/OrgSync
-[17]: http://martinfowler.com/bliki/CircuitBreaker.html
-[18]: https://github.com/alg/circuit_b
-[19]: https://github.com/wsargent/circuit_breaker
-[20]: https://github.com/soundcloud/simple_circuit_breaker
-[21]: https://github.com/wooga/circuit_breaker
+[12]: https://github.com/orgsync/stoplight-admin
+[13]: http://semver.org/spec/v2.0.0.html
+[14]: https://rubygems.org/gems/redis
+[the hipchat gem]: 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

@@ -8,10 +8,21 @@ require 'stoplight/data_store/redis'
 require 'stoplight/error'
 require 'stoplight/failure'
 require 'stoplight/light'
+require 'stoplight/mixin'
+require 'stoplight/notifier'
+require 'stoplight/notifier/base'
+require 'stoplight/notifier/hip_chat'
+require 'stoplight/notifier/standard_error'
 
 module Stoplight
   # @return [Gem::Version]
-  VERSION = Gem::Version.new('0.1.0')
+  VERSION = Gem::Version.new('0.2.0')
+
+  # @return [Integer]
+  DEFAULT_THRESHOLD = 3
+
+  @data_store = DataStore::Memory.new
+  @notifiers = [Notifier::StandardError.new]
 
   class << self
     extend Forwardable
@@ -20,8 +31,10 @@ module Stoplight
       attempts
       clear_attempts
       clear_failures
+      delete
       failures
       names
+      purge
       record_attempt
       record_failure
       set_state
@@ -29,13 +42,11 @@ module Stoplight
       state
     )
 
-    # @param data_store [DataStore::Base]
     # @return [DataStore::Base]
-    def data_store(data_store = nil)
-      @data_store = data_store if data_store
-      @data_store = DataStore::Memory.new unless defined?(@data_store)
-      @data_store
-    end
+    attr_accessor :data_store
+
+    # @return [Array<Notifier::Base>]
+    attr_accessor :notifiers
 
     # @param name [String]
     # @return [Boolean]
@@ -59,7 +70,7 @@ module Stoplight
     # @param name [String]
     # @return [Integer]
     def threshold(name)
-      data_store.threshold(name) || Light::DEFAULT_THRESHOLD
+      data_store.threshold(name) || DEFAULT_THRESHOLD
     end
   end
 end

data/lib/stoplight/data_store/base.rb

@@ -8,6 +8,16 @@ module Stoplight
         fail NotImplementedError
       end
 
+      # Deletes all green lights without failures.
+      def purge
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      def delete(_name)
+        fail NotImplementedError
+      end
+
       # @param _name [String]
       # @param _error [Exception]
       def record_failure(_name, _error)
@@ -76,20 +86,24 @@ module Stoplight
         fail ArgumentError, 'Invalid state'
       end
 
-      def key(name, slug)
-        [DataStore::KEY_PREFIX, name, slug].join(':')
+      def attempts_key
+        key('attempts')
+      end
+
+      def failures_key(name)
+        key('failures', name)
       end
 
-      def attempt_key(name)
-        key(name, 'attempts')
+      def states_key
+        key('states')
       end
 
-      def failure_key(name)
-        key(name, 'failures')
+      def thresholds_key
+        key('thresholds')
       end
 
-      def settings_key(name)
-        key(name, 'settings')
+      def key(slug, name = nil)
+        [KEY_PREFIX, name, slug].compact.join(':')
       end
     end
   end

data/lib/stoplight/data_store/memory.rb

@@ -8,59 +8,84 @@ module Stoplight
       end
 
       def names
-        @data.keys.map do |key|
-          match = /^#{DataStore::KEY_PREFIX}:(.+):([^:]+)$/.match(key)
-          match[1] if match
-        end.compact.uniq
+        all_thresholds.keys
       end
 
-      def record_failure(name, error)
-        failure = Failure.new(error)
-        array = @data[failure_key(name)] ||= []
-        array.push(failure)
+      def purge
+        names
+          .select { |l| failures(l).empty? }
+          .each   { |l| delete(l) }
       end
 
-      def clear_failures(name)
-        @data.delete(failure_key(name))
+      def delete(name)
+        clear_attempts(name)
+        clear_failures(name)
+        all_states.delete(name)
+        all_thresholds.delete(name)
       end
 
-      def failures(name)
-        @data[failure_key(name)] || []
-      end
+      # @group Attempts
 
-      def settings(name)
-        @data[settings_key(name)] ||= {}
+      def attempts(name)
+        all_attempts[name] || 0
       end
 
-      def threshold(name)
-        settings(name)['threshold']
+      def record_attempt(name)
+        all_attempts[name] ||= 0
+        all_attempts[name] += 1
       end
 
-      def set_threshold(name, threshold)
-        settings(name)['threshold'] = threshold
+      def clear_attempts(name)
+        all_attempts.delete(name)
       end
 
-      def record_attempt(name)
-        key = attempt_key(name)
-        @data[key] ||= 0
-        @data[key] += 1
+      # @group Failures
+
+      def failures(name)
+        @data[failures_key(name)] || []
       end
 
-      def clear_attempts(name)
-        @data.delete(attempt_key(name))
+      def record_failure(name, error)
+        (@data[failures_key(name)] ||= []).push(Failure.new(error))
       end
 
-      def attempts(name)
-        @data[attempt_key(name)] || 0
+      def clear_failures(name)
+        @data.delete(failures_key(name))
       end
 
+      # @group State
+
       def state(name)
-        settings(name)['state'] || DataStore::STATE_UNLOCKED
+        all_states[name] || STATE_UNLOCKED
       end
 
       def set_state(name, state)
         validate_state!(state)
-        settings(name)['state'] = state
+        all_states[name] = state
+      end
+
+      # @group Threshold
+
+      def threshold(name)
+        all_thresholds[name]
+      end
+
+      def set_threshold(name, threshold)
+        all_thresholds[name] = threshold
+      end
+
+      private
+
+      def all_attempts
+        @data[attempts_key] ||= {}
+      end
+
+      def all_states
+        @data[states_key] ||= {}
+      end
+
+      def all_thresholds
+        @data[thresholds_key] ||= {}
       end
     end
   end