stoplight 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c9bd1ff4a7ba5920b6b1a5e98c829b88ca495ec2
+  data.tar.gz: 3c7698e907ec212e7072b14c9d4df4e54dd9c1b9
+SHA512:
+  metadata.gz: 4e9fe6173c1b7524fe02ec8939512aea3c0a4cb5cf09ccf5f6cacde09ed461fc6ccfc1b4fc37eaf5008206b398d2aab9b71f5d9c1c39b94ded8ef4a57fb7b942
+  data.tar.gz: f6a8ffb8069abad09d6a795c5acc368b6ea954e8d9d3c6359d36b61e54625923727834a49b1ac827c55cda32d2e36a9b7d16ae9fc9939cd2f35cf14870e93a7b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## v0.1.0 (2014-08-12)
+
+- Initial release.

data/LICENSE.md

@@ -0,0 +1,18 @@
+Copyright (c) 2014 Cameron Desautels & Taylor Fausak
+
+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
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,208 @@
+# [Stoplight][1]
+
+[![Gem version][2]][3]
+[![Build status][4]][5]
+[![Coverage status][6]][7]
+[![Quality status][8]][9]
+[![Dependency status][10]][11]
+
+Traffic control for code. An implementation of the circuit breaker pattern in Ruby.
+
+## Installation
+
+Add it to your Gemfile:
+
+``` rb
+gem 'stoplight', '~> 0.1.0'
+```
+
+Or install it manually:
+
+``` sh
+$ gem install stoplight
+```
+
+This project uses [Semantic Versioning][12].
+
+## Setup
+
+Stoplight uses an in-memory data store out of the box.
+
+``` irb
+>> require 'stoplight'
+=> true
+>> Stoplight.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][13] installed before configuring Stoplight.
+
+``` irb
+>> redis = Stoplight::DataStore::Redis.new(url: 'redis://127.0.0.1:6379/0')
+=> #<Stoplight::DataStore::Redis:...>
+>> Stoplight.data_store(redis)
+=> #<Stoplight::DataStore::Redis:...>
+```
+
+### Rails
+
+Stoplight is designed to work seamlessly with Rails. If you want to use the
+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
+# config/initializers/stoplight.rb
+require 'stoplight'
+Stoplight.data_store(Stoplight::DataStore::Redis.new(...))
+```
+
+## Usage
+
+To get started, create a stoplight:
+
+``` irb
+>> light = Stoplight::Light.new('example-1') { 22.0 / 7 }
+=> #<Stoplight::Light:...>
+```
+
+Then you can run it and it will return the result of calling the block. This is
+the "green" state.
+
+``` irb
+>> light.run
+=> 3.142857142857143
+>> light.green?
+=> true
+```
+
+If everything goes well, you shouldn't even be able to tell that you're using a
+stoplight. That's not very interesting though. Let's create a failing stoplight:
+
+``` irb
+>> light = Stoplight::Light.new('example-2') { 1 / 0 }
+=> #<Stoplight::Light:...>
+```
+
+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.
+
+``` irb
+>> light.run
+ZeroDivisionError: divided by 0
+>> light.run
+ZeroDivisionError: divided by 0
+>> light.run
+ZeroDivisionError: divided by 0
+>> light.run
+Stoplight::Error::NoFallback: Stoplight::Error::NoFallback
+>> light.red?
+=> true
+```
+
+### 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
+good example is `ActiveRecord::RecordNotFound`.
+
+``` irb
+>> light = Stoplight::Light.new('example-3') { User.find(123) }.
+?> with_allowed_errors([ActiveRecord::RecordNotFound])
+=> #<Stoplight::Light:...>
+>> light.run
+ActiveRecord::RecordNotFound: Couldn't find User with ID=123
+>> light.run
+ActiveRecord::RecordNotFound: Couldn't find User with ID=123
+>> light.run
+ActiveRecord::RecordNotFound: Couldn't find User with ID=123
+>> light.green?
+=> true
+```
+
+### Custom fallback
+
+Instead of raising a `Stoplight::Error::NoFallback` 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 }.
+?> with_fallback { [] }
+=> #<Stoplight::Light:...>
+>> light.run
+RuntimeError:
+>> light.run
+RuntimeError:
+>> light.run
+RuntimeError:
+>> light.run
+=> []
+```
+
+### 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 in seconds.
+
+``` irb
+>> light = Stoplight::Light.new('example-5') { fail }.
+?> with_threshold(1)
+=> #<Stoplight::Light:...>
+>> light.run
+RuntimeError:
+>> light.run
+Stoplight::Error::NoFallback: Stoplight::Error::NoFallback
+```
+
+### Rails
+
+Stoplight was designed to wrap Rails actions with minimal effort. Here's an
+example configuration:
+
+``` rb
+class ApplicationController < ActionController::Base
+  around_action :stoplight
+  private
+  def stoplight(&block)
+    Stoplight::Light.new("#{params[:controller]}##{params[:action]}", &block)
+      .with_allowed_errors([ActiveRecord::RecordNotFound])
+      .with_fallback { render(nothing: true, status: :service_unavailable) }
+      .run
+  end
+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.
+
+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].
+
+[1]: https://github.com/orgsync/stoplight
+[2]: https://badge.fury.io/rb/stoplight.svg
+[3]: https://rubygems.org/gems/stoplight
+[4]: https://travis-ci.org/orgsync/stoplight.svg
+[5]: https://travis-ci.org/orgsync/stoplight
+[6]: https://img.shields.io/coveralls/orgsync/stoplight.svg
+[7]: https://coveralls.io/r/orgsync/stoplight
+[8]: https://codeclimate.com/github/orgsync/stoplight/badges/gpa.svg
+[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

data/lib/stoplight.rb

@@ -0,0 +1,65 @@
+# coding: utf-8
+
+require 'forwardable'
+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'
+
+module Stoplight
+  # @return [Gem::Version]
+  VERSION = Gem::Version.new('0.1.0')
+
+  class << self
+    extend Forwardable
+
+    def_delegators :data_store, *%w(
+      attempts
+      clear_attempts
+      clear_failures
+      failures
+      names
+      record_attempt
+      record_failure
+      set_state
+      set_threshold
+      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
+
+    # @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) || Light::DEFAULT_THRESHOLD
+    end
+  end
+end

data/lib/stoplight/data_store.rb

@@ -0,0 +1,15 @@
+# coding: utf-8
+
+module Stoplight
+  module DataStore
+    # @return [String]
+    KEY_PREFIX = 'stoplight'
+
+    # @return [Set<String>]
+    STATES = Set.new([
+      STATE_LOCKED_GREEN = 'locked_green',
+      STATE_LOCKED_RED = 'locked_red',
+      STATE_UNLOCKED = 'unlocked'
+    ]).freeze
+  end
+end

data/lib/stoplight/data_store/base.rb

@@ -0,0 +1,96 @@
+# coding: utf-8
+
+module Stoplight
+  module DataStore
+    class Base
+      # @return [Array<String>]
+      def names
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @param _error [Exception]
+      def record_failure(_name, _error)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      def clear_failures(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @return [Array<Failure>]
+      def failures(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @return [Integer]
+      def threshold(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @param _threshold [Integer]
+      # @return (see #threshold)
+      def set_threshold(_name, _threshold)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @return (see #attempts)
+      def record_attempt(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      def clear_attempts(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @return [Integer]
+      def attempts(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @return [String]
+      def state(_name)
+        fail NotImplementedError
+      end
+
+      # @param _name [String]
+      # @param _state [String]
+      # @return [String]
+      def set_state(_name, _state)
+        # REVIEW: Should we clear failures here?
+        fail NotImplementedError
+      end
+
+      private
+
+      def validate_state!(state)
+        return if DataStore::STATES.include?(state)
+        fail ArgumentError, 'Invalid state'
+      end
+
+      def key(name, slug)
+        [DataStore::KEY_PREFIX, name, slug].join(':')
+      end
+
+      def attempt_key(name)
+        key(name, 'attempts')
+      end
+
+      def failure_key(name)
+        key(name, 'failures')
+      end
+
+      def settings_key(name)
+        key(name, 'settings')
+      end
+    end
+  end
+end

data/lib/stoplight/data_store/memory.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+
+module Stoplight
+  module DataStore
+    class Memory < Base
+      def initialize
+        @data = {}
+      end
+
+      def names
+        @data.keys.map do |key|
+          match = /^#{DataStore::KEY_PREFIX}:(.+):([^:]+)$/.match(key)
+          match[1] if match
+        end.compact.uniq
+      end
+
+      def record_failure(name, error)
+        failure = Failure.new(error)
+        array = @data[failure_key(name)] ||= []
+        array.push(failure)
+      end
+
+      def clear_failures(name)
+        @data.delete(failure_key(name))
+      end
+
+      def failures(name)
+        @data[failure_key(name)] || []
+      end
+
+      def settings(name)
+        @data[settings_key(name)] ||= {}
+      end
+
+      def threshold(name)
+        settings(name)['threshold']
+      end
+
+      def set_threshold(name, threshold)
+        settings(name)['threshold'] = threshold
+      end
+
+      def record_attempt(name)
+        key = attempt_key(name)
+        @data[key] ||= 0
+        @data[key] += 1
+      end
+
+      def clear_attempts(name)
+        @data.delete(attempt_key(name))
+      end
+
+      def attempts(name)
+        @data[attempt_key(name)] || 0
+      end
+
+      def state(name)
+        settings(name)['state'] || DataStore::STATE_UNLOCKED
+      end
+
+      def set_state(name, state)
+        validate_state!(state)
+        settings(name)['state'] = state
+      end
+    end
+  end
+end