stoplight 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b9db0e92d38791e2989cbd757cb1b0dcbf4e73e
-  data.tar.gz: d43063006ea37bae49bbe203f25f059390e1c7f4
+  metadata.gz: e500fe8c6d34e694cfbc2c46540a445eb997f89a
+  data.tar.gz: ec03f4f69321194449e3e0918183c6cbea4f9e2b
 SHA512:
-  metadata.gz: fa7c3d3d0895e885d977292a09081f0c8ba23d22e1f228c60d298ed935f8bb32557549ffb5ef13419eff16a86b8e8a3f7173e9efac29ba7b2fe919505d8eb610
-  data.tar.gz: c7808ed8e151962b345787aaa9634a79f191fd1bc19ee8d5dd0bb04099fcf7a2765c04279b7d359afcae5bc0be84a4cf8e77fd27a2de382bc3cc92fd1342ce70
+  metadata.gz: 8b6f647cb561a37f14e44054b2549defcf1f72df27c0d8ba93c39d98b13d1b3f44c34b5c10070aa4d9c5d5d7c4b438983a532531bbad253605769b6a53925bdf
+  data.tar.gz: 75a107deca63c8fca90ec6466f66b98524af37263750d77ae06526a280331f65de4a83e1647ad41ef568c6afa7e103241d070ebe5fedd23d6b41dcbf312514e2

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.3.0 (2014-09-11)
+
+- Allowed formatting notifications.
+- Added automatic recovery from red lights.
+- Added `Stoplight::DataStore#clear_stale` for clearing stale lights.
+
 ## v0.2.1 (2014-08-20)
 
 - Forced times to be serialized as strings.

data/README.md

@@ -11,12 +11,26 @@ Ruby.
 
 Check out [stoplight-admin][12] for controlling your stoplights.
 
+- [Installation](#installation)
+- [Setup](#setup)
+  - [Data store](#data-store)
+  - [Notifiers](#notifiers)
+  - [Rails](#rails)
+- [Usage](#usage)
+  - [Mixin](#mixin)
+  - [Custom errors](#custom-errors)
+  - [Custom fallback](#custom-fallback)
+  - [Custom threshold](#custom-threshold)
+  - [Custom timeout](#custom-timeout)
+  - [Rails](#rails-1)
+- [Credits](#credits)
+
 ## Installation
 
 Add it to your Gemfile:
 
 ``` rb
-gem 'stoplight', '~> 0.2.1'
+gem 'stoplight', '~> 0.3.0'
 ```
 
 Or install it manually:
@@ -45,6 +59,8 @@ the only supported persistent data store is Redis. Make sure you have [the Redis
 gem][14] installed before configuring Stoplight.
 
 ``` irb
+>> require 'redis'
+=> true
 >> redis = Redis.new(url: 'redis://127.0.0.1:6379/0')
 => #<Redis:...>
 >> data_store = Stoplight::DataStore::Redis.new(redis)
@@ -64,15 +80,17 @@ Stoplight sends notifications to standard error by default.
 
 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.
+HipChat gem][15] installed before configuring Stoplight.
 
 ``` irb
+>> require 'hipchat'
+=> true
 >> hipchat = HipChat::Client.new('token')
 => #<HipChat::Client:...>
 >> notifier = Stoplight::Notifier::HipChat.new(hipchat, 'room')
 => #<Stoplight::Notifier::HipChat:...>
->> Stoplight.notifiers = [notifier])
-=> [#<Stoplight::Notifier::HipChat:...>]
+>> Stoplight.notifiers << notifier
+=> [#<Stoplight::Notifier::StandardError:...>, #<Stoplight::Notifier::HipChat:...>]
 ```
 
 ### Rails
@@ -86,6 +104,7 @@ Stoplight:
 # config/initializers/stoplight.rb
 require 'stoplight'
 Stoplight.data_store = Stoplight::DataStore::Redis.new(...)
+Stoplight.notifiers << Stoplight::Notifier::HipChat.new(...)
 ```
 
 ## Usage
@@ -98,7 +117,7 @@ To get started, create a stoplight:
 ```
 
 Then you can run it and it will return the result of calling the block. This is
-the "green" state.
+the green state.
 
 ``` irb
 >> light.run
@@ -117,7 +136,7 @@ stoplight. That's not very interesting though. Let's create a failing stoplight:
 
 Now 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.
 
 ``` irb
 >> light.run
@@ -127,7 +146,8 @@ ZeroDivisionError: divided by 0
 >> light.run
 ZeroDivisionError: divided by 0
 >> light.run
-Stoplight::Error::RedLight: Stoplight::Error::RedLight
+Switching example-2 from green to red.
+Stoplight::Error::RedLight: example-2
 >> light.red?
 => true
 ```
@@ -155,7 +175,7 @@ good example is `ActiveRecord::RecordNotFound`.
 
 ``` irb
 >> light = Stoplight::Light.new('example-4') { User.find(123) }.
-?> with_allowed_errors([ActiveRecord::RecordNotFound])
+..   with_allowed_errors([ActiveRecord::RecordNotFound])
 => #<Stoplight::Light:...>
 >> light.run
 ActiveRecord::RecordNotFound: Couldn't find User with ID=123
@@ -175,7 +195,7 @@ value for the block.
 
 ``` irb
 >> light = Stoplight::Light.new('example-5') { fail }.
-?> with_fallback { [] }
+..   with_fallback { [] }
 => #<Stoplight::Light:...>
 >> light.run
 RuntimeError:
@@ -194,14 +214,42 @@ You can configure this by setting a custom threshold in seconds.
 
 ``` irb
 >> light = Stoplight::Light.new('example-6') { fail }.
-?> with_threshold(1)
+..   with_threshold(1)
+=> #<Stoplight::Light:...>
+>> light.run
+RuntimeError:
+>> light.run
+Stoplight::Error::RedLight: example-6
+```
+
+### Custom timeout
+
+Stoplights will automatically attempt to recover after a certain amount of time.
+This timeout is customizable.
+
+``` irb
+>> light = Stoplight::Light.new('example-7') { fail }.
+..   with_timeout(1)
 => #<Stoplight::Light:...>
 >> light.run
 RuntimeError:
 >> light.run
-Stoplight::Error::RedLight: Stoplight::Error::RedLight
+RuntimeError:
+>> light.run
+RuntimeError:
+>> light.run
+Switching example-7 from green to red.
+Stoplight::Error::RedLight: example-7
+>> sleep(1)
+=> 1
+>> light.yellow?
+=> true
+>> light.run
+RuntimeError:
 ```
 
+Set the timeout to `-1` to disable automatic recovery.
+
 ### Rails
 
 Stoplight was designed to wrap Rails actions with minimal effort. Here's an
@@ -222,12 +270,13 @@ end
 
 ## Credits
 
-Stoplight is brought to you by [@camdez][15] and [@tfausak][16] from [@OrgSync][17]. We were
-inspired by Martin Fowler's [CircuitBreaker][18] article.
+Stoplight is brought to you by [@camdez][16] and [@tfausak][17] from
+[@OrgSync][18]. We were inspired by Martin Fowler's [CircuitBreaker][19]
+article.
 
 If this gem isn't cutting it for you, there are a few alternatives, including:
-[circuit_b][19], [circuit_breaker][20], [simple_circuit_breaker][21], and
-[ya_circuit_breaker][22].
+[circuit_b][20], [circuit_breaker][21], [simple_circuit_breaker][22], and
+[ya_circuit_breaker][23].
 
 [1]: https://github.com/orgsync/stoplight
 [2]: https://badge.fury.io/rb/stoplight.svg
@@ -243,12 +292,12 @@ If this gem isn't cutting it for you, there are a few alternatives, including:
 [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
+[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

data/lib/stoplight.rb

@@ -1,6 +1,5 @@
 # coding: utf-8
 
-require 'forwardable'
 require 'stoplight/data_store'
 require 'stoplight/data_store/base'
 require 'stoplight/data_store/memory'
@@ -16,61 +15,16 @@ require 'stoplight/notifier/standard_error'
 
 module Stoplight
   # @return [Gem::Version]
-  VERSION = Gem::Version.new('0.2.1')
-
-  # @return [Integer]
-  DEFAULT_THRESHOLD = 3
+  VERSION = Gem::Version.new('0.3.0')
 
   @data_store = DataStore::Memory.new
   @notifiers = [Notifier::StandardError.new]
 
   class << self
-    extend Forwardable
-
-    def_delegators :data_store, *%w(
-      attempts
-      clear_attempts
-      clear_failures
-      delete
-      failures
-      names
-      purge
-      record_attempt
-      record_failure
-      set_state
-      set_threshold
-      state
-    )
-
     # @return [DataStore::Base]
     attr_accessor :data_store
 
     # @return [Array<Notifier::Base>]
     attr_accessor :notifiers
-
-    # @param name [String]
-    # @return [Boolean]
-    def green?(name)
-      case data_store.state(name)
-      when DataStore::STATE_LOCKED_GREEN
-        true
-      when DataStore::STATE_LOCKED_RED
-        false
-      else
-        data_store.failures(name).size < threshold(name)
-      end
-    end
-
-    # @param name [String]
-    # @return (see .green?)
-    def red?(name)
-      !green?(name)
-    end
-
-    # @param name [String]
-    # @return [Integer]
-    def threshold(name)
-      data_store.threshold(name) || DEFAULT_THRESHOLD
-    end
   end
 end

data/lib/stoplight/data_store.rb

@@ -2,14 +2,152 @@
 
 module Stoplight
   module DataStore
-    # @return [String]
-    KEY_PREFIX = 'stoplight'
+    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
 
-    # @return [Set<String>]
+    STATE_UNLOCKED = 'unlocked'.freeze
+    STATE_LOCKED_GREEN = 'locked_green'.freeze
+    STATE_LOCKED_RED = 'locked_red'.freeze
     STATES = Set.new([
-      STATE_LOCKED_GREEN = 'locked_green',
-      STATE_LOCKED_RED = 'locked_red',
-      STATE_UNLOCKED = 'unlocked'
+      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 threshold < 1 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)
+    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

data/lib/stoplight/data_store/base.rb

@@ -8,66 +8,101 @@ module Stoplight
         fail NotImplementedError
       end
 
-      # Deletes all green lights without failures.
-      def purge
+      # @return [nil]
+      def clear_stale
         fail NotImplementedError
       end
 
       # @param _name [String]
-      def delete(_name)
+      # @return [nil]
+      def clear(_name)
         fail NotImplementedError
       end
 
       # @param _name [String]
-      # @param _error [Exception]
-      def record_failure(_name, _error)
+      # @return [nil]
+      def sync(_name)
         fail NotImplementedError
       end
 
+      # @group Colors
+
+      # @param name [String]
+      # @return [Boolean]
+      def green?(name)
+        color = get_color(name)
+        DataStore.validate_color!(color)
+        color == COLOR_GREEN
+      end
+
+      # @param name [String]
+      # @return [Boolean]
+      def yellow?(name)
+        color = get_color(name)
+        DataStore.validate_color!(color)
+        color == COLOR_YELLOW
+      end
+
+      # @param name [String]
+      # @return [Boolean]
+      def red?(name)
+        color = get_color(name)
+        DataStore.validate_color!(color)
+        color == COLOR_RED
+      end
+
       # @param _name [String]
-      def clear_failures(_name)
+      # @return [String]
+      def get_color(_name)
         fail NotImplementedError
       end
 
+      # @group Attempts
+
       # @param _name [String]
-      # @return [Array<Failure>]
-      def failures(_name)
+      # @return [Integer]
+      def get_attempts(_name)
         fail NotImplementedError
       end
 
       # @param _name [String]
       # @return [Integer]
-      def threshold(_name)
+      def record_attempt(_name)
         fail NotImplementedError
       end
 
       # @param _name [String]
-      # @param _threshold [Integer]
-      # @return (see #threshold)
-      def set_threshold(_name, _threshold)
+      # @return [nil]
+      def clear_attempts(_name)
         fail NotImplementedError
       end
 
+      # @group Failures
+
       # @param _name [String]
-      # @return (see #attempts)
-      def record_attempt(_name)
+      # @return [Array<Failure>]
+      def get_failures(_name)
         fail NotImplementedError
       end
 
       # @param _name [String]
-      def clear_attempts(_name)
+      # @param _failure [Failure]
+      # @return [Failure]
+      def record_failure(_name, _failure)
         fail NotImplementedError
       end
 
       # @param _name [String]
-      # @return [Integer]
-      def attempts(_name)
+      # @return [nil]
+      def clear_failures(_name)
         fail NotImplementedError
       end
 
+      # @group States
+
       # @param _name [String]
       # @return [String]
-      def state(_name)
+      def get_state(_name)
         fail NotImplementedError
       end
 
@@ -75,35 +110,55 @@ module Stoplight
       # @param _state [String]
       # @return [String]
       def set_state(_name, _state)
-        # REVIEW: Should we clear failures here?
         fail NotImplementedError
       end
 
-      private
+      # @param _name [String]
+      # @return [nil]
+      def clear_state(_name)
+        fail NotImplementedError
+      end
 
-      def validate_state!(state)
-        return if DataStore::STATES.include?(state)
-        fail ArgumentError, 'Invalid state'
+      # @group Thresholds
+
+      # @param _name [String]
+      # @return [Integer]
+      def get_threshold(_name)
+        fail NotImplementedError
       end
 
-      def attempts_key
-        key('attempts')
+      # @param _name [String]
+      # @param _threshold [Integer]
+      # @return [Integer]
+      def set_threshold(_name, _threshold)
+        fail NotImplementedError
       end
 
-      def failures_key(name)
-        key('failures', name)
+      # @param _name [String]
+      # @return [nil]
+      def clear_threshold(_name)
+        fail NotImplementedError
       end
 
-      def states_key
-        key('states')
+      # @group Timeouts
+
+      # @param _name [String]
+      # @return [Integer]
+      def get_timeout(_name)
+        fail NotImplementedError
       end
 
-      def thresholds_key
-        key('thresholds')
+      # @param _name [String]
+      # @param _timeout [Integer]
+      # @return [Integer]
+      def set_timeout(_name, _timeout)
+        fail NotImplementedError
       end
 
-      def key(slug, name = nil)
-        [KEY_PREFIX, name, slug].compact.join(':')
+      # @param _name [String]
+      # @return [nil]
+      def clear_timeout(_name)
+        fail NotImplementedError
       end
     end
   end