circuitbox 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 00e479410c5dfdf8769c828dfbfdcae074ee524c
-  data.tar.gz: c2f06d9ceaa7ca95c6837a7abc01e79a93ecb81c
+  metadata.gz: a837fae089566b81f6ccd58a7b89b4c119f122d4
+  data.tar.gz: e78c6f2bf1437d2e5cd4495d106b8c822dbbd896
 SHA512:
-  metadata.gz: d43fff58af3f25b93be58ecaac16d7b8a815ac275d4337ff6cbf65833c9e72c3c4b1ddd930165c1393df426fa0f9250b29585e987288a4af798b951073073dcf
-  data.tar.gz: a1913c31ddc136a114ea659fe602f8358f6fecb7076cb2af6d954d04f014c70f9685c1fe871963b6cdd180e62701b9fd968aa4b5f70f5cc20ccd5e6ee8d79982
+  metadata.gz: bcd00fa6cb16dbb3a7ea62d912049a1b6c1d676b4c484f1e42e8ae65b060b215e673e3ec0ccb0ff2f15cce6ceff60c0b62e0ab1bc752a4b9d65674a74edf6afe
+  data.tar.gz: f066a4d85503ed0db075a0df074f9eacd5dd9740cc2a5af5fbb289c07b48a287cea07a64c75eb3ced6b37f06a410608f657a24ce9688cf49c0fae31171b9bb9f

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2

data/Gemfile

@@ -3,16 +3,3 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in circuitbox.gemspec
 gemspec
 
-gem 'activesupport'
-gem 'logger'
-gem 'faraday'
-
-group :test do
-  gem 'timecop'
-  gem 'mocha'
-  gem 'minitest'
-  gem 'guard-minitest'
-  gem 'gimme'
-  gem 'terminal-notifier-guard'
-end
-

data/README.md

@@ -1,3 +1,4 @@
+![Build Status](https://travis-ci.org/yammer/circuitbox.svg)
 
 # Circuitbox
 
@@ -69,7 +70,62 @@ You can also run `rake circuits:stats SERVICE={service_name}` to see successes,
 Add `PARTITION={partition_key}` to see the circuit for a particular partition.
 The stats are aggregated into 1 minute intervals.
 
-## Faraday (Caveat: Open circuits return a nil response object)
+## Notifications
+
+circuitbox use ActiveSupport Notifications.
+
+Usage example:
+
+**Log on circuit open/close:**
+
+```ruby
+class CircuitOpenException    < StandardError ; end
+
+ActiveSupport::Notifications.subscribe('circuit_open') do |name, start, finish, id, payload|
+  circuit_name = payload[:circuit]
+  Rails.logger.warning("Open circuit for: #{circuit_name}")
+end
+ActiveSupport::Notifications.subscribe('circuit_close') do |name, start, finish, id, payload|
+  circuit_name = payload[:circuit]
+  Rails.logger.info("Close circuit for: #{circuit_name}")
+end
+````
+
+**generate metrics:**
+
+```ruby
+$statsd = Statsd.new 'localhost', 9125
+
+ActiveSupport::Notifications.subscribe('circuit_gauge') do |name, start, finish, id, payload|
+  circuit_name = payload[:circuit]
+  gauge        = payload[:gauge]
+  value        = payload[:value]
+  metrics_key  = "circuitbox.circuit.#{circuit_name}.#{gauge}"
+
+  $statsd.gauge(metrics_key, value)
+end
+```
+
+`payload[:gauge]` can be:
+
+- `failure_count`
+- `success_count`
+- `error_rate`
+
+**warnings:**
+in case of misconfiguration, circuitbox will fire a circuitbox_warning
+notification.
+
+```ruby
+ActiveSupport::Notifications.subscribe('circuit_warning') do |name, start, finish, id, payload|
+  circuit_name = payload[:circuit]
+  warning      = payload[:message]
+  Rails.logger.warning("#{circuit_name} - #{warning}")
+end
+
+```
+
+## Faraday
 
 Circuitbox ships with [Faraday HTTP client](https://github.com/lostisland/faraday) middleware.
 
@@ -77,19 +133,60 @@ Circuitbox ships with [Faraday HTTP client](https://github.com/lostisland/farada
 require 'faraday'
 require 'circuitbox/faraday_middleware'
 
-conn = Faraday::Connection.new(:url => "http://example.com") do |builder|
-  builder.use Circuitbox::FaradayMiddleware
+conn = Faraday.new(:url => "http://example.com") do |c|
+  c.use Circuitbox::FaradayMiddleware
 end
 
-if response = conn.get("/api")
+response = conn.get("/api")
+if response.success?
   # success
 else
   # failure or open circuit
 end
 ```
 
+By default the Faraday middleware returns a `503` response when the circuit is
+open, but this as many other things can be configured via middleware options
+
+* `exceptions` pass a list of exceptions for the Circuitbreaker to catch,
+  defaults to Timeout and Request failures
+
+```ruby
+c.use Circuitbox::FaradayMiddleware, exceptions: [Faraday::Error::TimeoutError]
+```
+
+* `default_value` value to return for open circuits, defaults to 503 response
+  wrapping the original response given by the service and stored as
+  `original_response` property of the returned 503, this can be overwritten
+  either with a static value or a `lambda` which is passed the
+  original_response.
+
+```ruby
+c.use Circuitbox::FaradayMiddleware, default_value: lambda { |response| ... }
+```
+
+* `identifier` circuit id, defaults to request url
+
+```ruby
+c.use Circuitbox::FaradayMiddleware, identifier: "service_name_circuit"
+```
+
+* `circuit_breaker_run_options` options passed to the circuit run method, see
+  the main circuitbreaker for those.
+
+```ruby
+conn.get("/api", circuit_breaker_run_options: {})
+```
+
+* `circuit_breaker_options` options to initialize the circuit with defaults to
+  `{ volume_threshold: 10, exceptions: Circuitbox::FaradayMiddleware::DEFAULT_EXCEPTIONS }`
+
+```ruby
+c.use Circuitbox::FaradayMiddleware, circuit_breaker_options: {}
+```
+
 ## TODO
-* Fix Faraday integration to return a Faraday response object
+* ~~Fix Faraday integration to return a Faraday response object~~
 * Split stats into it's own repository
 * Circuit Breaker should raise an exception by default instead of returning nil
 * Refactor to use single state variable

data/circuitbox.gemspec

@@ -18,9 +18,18 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.4"
+  spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency 'bundler-gem_version_tasks'
+  spec.add_development_dependency "rack"
+  spec.add_development_dependency "guard-minitest"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "gimme"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "mocha"
+  spec.add_development_dependency "timecop"
+  spec.add_development_dependency "faraday"
+  spec.add_development_dependency "logger"
+  spec.add_development_dependency "bundler-gem_version_tasks"
 
   spec.add_dependency "activesupport"
 end

data/lib/circuitbox/faraday_middleware.rb

@@ -2,30 +2,90 @@ require 'faraday'
 require 'circuitbox'
 
 class Circuitbox
-  class RequestError < StandardError; end
+  class FaradayMiddleware < Faraday::Middleware
+    class RequestFailed < StandardError; end
 
-  class FaradayMiddleware < Faraday::Response::Middleware
+    DEFAULT_EXCEPTIONS = [
+      Faraday::Error::TimeoutError,
+      RequestFailed,
+    ]
 
-    attr_accessor :identifier, :exceptions
+    class NullResponse < Faraday::Response
+      attr_reader :original_response
+      def initialize(response = nil)
+        @original_response = response
+        super(status: 503, response_headers: {})
+      end
+    end
+
+    attr_reader :opts
 
-    def initialize(app, opts={})
-      @identifier = opts.fetch(:identifier) { ->(env) { env.url }}
-      @exceptions = opts.fetch(:exceptions) { [Faraday::Error::TimeoutError] }
+    def initialize(app, opts = {})
+      @app = app
+      @opts = opts
       super(app)
     end
 
-    def call(env)
-      id = identifier.respond_to?(:call) ? identifier.call(env) : identifier
-      circuit = Circuitbox.circuit id, :exceptions => exceptions
-      circuit.run do
-        super(env)
+    def call(request_env)
+      service_response = nil
+      response = circuit(request_env).run(run_options(request_env)) do
+          service_response = @app.call(request_env)
+          raise RequestFailed unless service_response.success?
+          service_response
       end
+
+      response.nil? ? circuit_open_value(request_env, service_response) : response
+    end
+
+    def exceptions
+      circuit_breaker_options[:exceptions]
+    end
+
+    def identifier
+      @identifier ||= opts.fetch(:identifier, ->(env) { env[:url] })
+    end
+
+    private
+
+    def run_options(env)
+      env[:circuit_breaker_run_options] || {}
     end
 
-    def on_complete(env)
-      if !env.success?
-        raise RequestError
+    def circuit_breaker_options
+      return @circuit_breaker_options if @current_adapter
+
+      @circuit_breaker_options = opts.fetch(:circuit_breaker_options, {})
+      @circuit_breaker_options.merge!(
+        exceptions: opts.fetch(:exceptions, DEFAULT_EXCEPTIONS),
+        volume_threshold: 10
+      )
+    end
+
+    def default_value
+      return @default_value if @default_value
+
+      default = opts.fetch(:default_value) do
+        lambda { |service_response| NullResponse.new(service_response) }
       end
+
+      @default_value = if default.respond_to?(:call)
+                         default
+                       else
+                         lambda { |_| default }
+                       end
+    end
+
+    def circuitbox
+      @circuitbox ||= opts.fetch(:circuitbox, Circuitbox)
+    end
+
+    def circuit_open_value(env, service_response)
+      env[:circuit_breaker_default_value] || default_value.call(service_response)
+    end
+
+    def circuit(env)
+      id = identifier.respond_to?(:call) ? identifier.call(env) : identifier
+      circuitbox.circuit id, circuit_breaker_options
     end
   end
 end

data/lib/circuitbox/version.rb

@@ -1,3 +1,3 @@
 class Circuitbox
-VERSION='0.7.0'
+VERSION='0.8.0'
 end

data/test/circuit_breaker_test.rb

@@ -1,5 +1,4 @@
 require 'test_helper'
-require 'circuitbox'
 require 'ostruct'
 
 class CircuitBreakerTest < Minitest::Test

data/test/circuitbox_test.rb

@@ -1,5 +1,4 @@
 require 'test_helper'
-require 'circuitbox'
 
 class Circuitbox::ExampleStore < ActiveSupport::Cache::MemoryStore; end
 

data/test/faraday_middleware_test.rb

@@ -1,41 +1,115 @@
 require 'test_helper'
-require_relative '../lib/circuitbox/faraday_middleware'
+require 'circuitbox/faraday_middleware'
+
+class SentialException < StandardError; end
 
 class Circuitbox
   class FaradayMiddlewareTest < Minitest::Test
 
+    attr_reader :app
     def setup
       @app = gimme
-      @env = gimme
-      give(@env).url { 'URL' }
+    end
+
+    def test_default_identifier
+      env = { url: "sential" }
+      assert_equal FaradayMiddleware.new(app).identifier.call(env), "sential"
+    end
+
+    def test_overwrite_identifier
+      middleware = FaradayMiddleware.new(app, identifier: "sential")
+      assert_equal middleware.identifier, "sential"
+    end
+
+    def test_overwrite_default_value_generator_lambda
+      stub_circuitbox
+      env = { url: "url" }
+      give(circuitbox).circuit("url", anything) { circuit }
+      default_value_generator = lambda { |_| :sential }
+      middleware = FaradayMiddleware.new(app,
+                                         circuitbox: circuitbox,
+                                         default_value: default_value_generator)
+      assert_equal middleware.call(env), :sential
+    end
 
-      @middleware = FaradayMiddleware.new @app,
-                                          :identifier => 'ID',
-                                          :exceptions => [StandardError]
+    def test_overwrite_default_value_generator_static_value
+      stub_circuitbox
+      env = { url: "url" }
+      give(circuitbox).circuit("url", anything) { circuit }
+      middleware = FaradayMiddleware.new(app, circuitbox: circuitbox, default_value: :sential)
+      assert_equal middleware.call(env), :sential
     end
 
-    def test_should_use_env_url_proc_if_not_provided_as_identifier
-      middleware = FaradayMiddleware.new @app, :exceptions => gimme
-      assert middleware.identifier.is_a?(Proc)
-      assert_equal 'URL', middleware.identifier.call(@env)
+    def test_default_exceptions
+      middleware = FaradayMiddleware.new(app)
+      assert_includes middleware.exceptions, Faraday::Error::TimeoutError
+      assert_includes middleware.exceptions, FaradayMiddleware::RequestFailed
     end
 
-    def test_should_use_request_error_if_not_provided_as_exception
-      middleware = FaradayMiddleware.new @app, :identifier => 'ID'
-      assert_equal [Faraday::Error::TimeoutError],
-                   middleware.exceptions
+    def test_overwrite_exceptions
+      middleware = FaradayMiddleware.new(app, exceptions: [SentialException])
+      assert_includes middleware.exceptions, SentialException
     end
 
-    def test_successful_call
-      @middleware.call(@env)
+    def test_pass_circuit_breaker_run_options
+      stub_circuitbox
+      give(circuit).run(:sential)
+      give(circuitbox).circuit("url", anything) { circuit }
+      env = { url: "url", circuit_breaker_run_options: :sential }
+      middleware = FaradayMiddleware.new(app, circuitbox: circuitbox)
+      middleware.call(env)
+      verify(circuit).run(:sential)
     end
 
-    def test_failed_call
-      assert_raises Circuitbox::RequestError do
-        give(@env).success? { false }
-        @middleware.on_complete(@env)
-      end
+    def test_pass_circuit_breaker_options
+      stub_circuitbox
+      env = { url: "url" }
+      expected_circuit_breaker_options = {
+        sential: :sential,
+        exceptions: FaradayMiddleware::DEFAULT_EXCEPTIONS,
+        volume_threshold: 10
+      }
+      give(circuitbox).circuit("url", expected_circuit_breaker_options) { circuit }
+      options = { circuitbox: circuitbox, circuit_breaker_options: { sential: :sential } }
+      middleware = FaradayMiddleware.new(app, options)
+      middleware.call(env)
+
+      verify(circuitbox).circuit("url", expected_circuit_breaker_options)
+    end
+
+    def test_overwrite_circuitbreaker_default_value
+      stub_circuitbox
+      env = { url: "url", circuit_breaker_default_value: :sential }
+      give(circuitbox).circuit("url", anything) { circuit }
+      middleware = FaradayMiddleware.new(app, circuitbox: circuitbox)
+      assert_equal middleware.call(env), :sential
+    end
+
+    def test_return_value_closed_circuit
+      stub_circuitbox
+      env = { url: "url" }
+      give(circuit).run(anything) { :sential }
+      give(circuitbox).circuit("url", anything) { circuit }
+      middleware = FaradayMiddleware.new(app, circuitbox: circuitbox)
+      assert_equal middleware.call(env), :sential
+    end
+
+    def test_return_null_response_for_open_circuit
+      stub_circuitbox
+      env = { url: "url" }
+      give(circuit).run(anything) { nil }
+      give(circuitbox).circuit("url", anything) { circuit }
+      response = FaradayMiddleware.new(app, circuitbox: circuitbox).call(env)
+      assert_kind_of Faraday::Response, response
+      assert_equal response.status, 503
+      assert response.finished?
+      refute response.success?
     end
 
+    attr_reader :circuitbox, :circuit
+    def stub_circuitbox
+      @circuitbox = gimme
+      @circuit = gimme
+    end
   end
 end

data/test/integration/faraday_middleware_test.rb

@@ -0,0 +1,36 @@
+require "integration_helper"
+
+class Circuitbox
+  class FaradayMiddlewareTest < Minitest::Test
+    @@only_once = false
+    def setup
+      @connection = Faraday.new do |c|
+        c.use FaradayMiddleware
+        c.adapter Faraday.default_adapter
+      end
+      @success_url = "http://localhost:4711"
+      @failure_url = "http://localhost:4712"
+
+      if !@@only_once
+        FakeServer.create(4711, ['200', {'Content-Type' => 'text/plain'}, ["Success!"]])
+        FakeServer.create(4712, ['500', {'Content-Type' => 'text/plain'}, ["Failure!"]])
+      end
+    end
+
+    def teardown
+      Circuitbox.reset
+    end
+
+    def test_open_circuit_response
+      10.times { @connection.get(@failure_url) } # make the CircuitBreaker open
+      open_circuit_response = @connection.get(@failure_url)
+      assert open_circuit_response.status, 503
+      assert_match open_circuit_response.original_response.body, "Failure!"
+    end
+
+    def test_closed_circuit_response
+      result = @connection.get(@success_url)
+      assert result.success?
+    end
+  end
+end

data/test/integration_helper.rb

@@ -0,0 +1,40 @@
+require "test_helper"
+require "faraday"
+require "circuitbox/faraday_middleware"
+require "rack"
+
+class FakeServer
+  def self.instance
+    @@instance ||= FakeServer.new
+    # if the FakeServer is used kill all of them after the tests are done
+    Minitest.after_run { FakeServer.shutdown }
+    @@instance
+  end
+
+  def initialize
+    @servers = []
+  end
+
+  def self.create(port, result)
+    FakeServer.instance.create(port, result)
+  end
+
+  def self.shutdown
+    FakeServer.instance.shutdown
+  end
+
+  def shutdown
+    @servers.map { |server| server.exit }
+    @servers = []
+  end
+
+  def create(port, result)
+    @servers << Thread.new do
+      Rack::Handler::WEBrick.run(Proc.new { |env| result },
+                                 Port: port,
+                                 AccessLog: [],
+                                 Logger: WEBrick::Log.new(DEV_NULL))
+    end
+    sleep 0.5 # wait for the server to spin up
+  end
+end

data/test/test_helper.rb

@@ -1,6 +1,15 @@
-require 'minitest'
 require 'minitest/autorun'
-require 'minitest/pride'
 require 'mocha/mini_test'
 require 'timecop'
 require 'gimme'
+require 'circuitbox'
+
+DEV_NULL = (RUBY_PLATFORM =~ /mswin|mingw/ ? "NUL" : "/dev/null")
+
+class Circuitbox
+  class CircuitBreaker
+    def logger
+      @_dev_null_logger ||= Logger.new(DEV_NULL)
+    end
+  end
+end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: circuitbox
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Fahim Ferdous
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-10 00:00:00.000000000 Z
+date: 2015-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +38,132 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: gimme
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler-gem_version_tasks
   requirement: !ruby/object:Gem::Requirement
@@ -74,6 +200,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - Guardfile
 - LICENSE
@@ -91,6 +218,8 @@ files:
 - test/circuit_breaker_test.rb
 - test/circuitbox_test.rb
 - test/faraday_middleware_test.rb
+- test/integration/faraday_middleware_test.rb
+- test/integration_helper.rb
 - test/notifier_test.rb
 - test/test_helper.rb
 homepage: ''
@@ -121,5 +250,7 @@ test_files:
 - test/circuit_breaker_test.rb
 - test/circuitbox_test.rb
 - test/faraday_middleware_test.rb
+- test/integration/faraday_middleware_test.rb
+- test/integration_helper.rb
 - test/notifier_test.rb
 - test/test_helper.rb