circuit_b 1.0

data/MIT-LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2010 Aleksey Gureiev
+
+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,104 @@
+Theory
+======
+
+When you are accessing some resource that is known to be unreliable,
+it's better to wrap your requests with a circuit breaking logic.
+The breaker acts as a fuse. When it senses that all your requests
+end up with errors, it breaks the circuit and starts throwing fail-fast
+errors instead without even trying to execute the code block in question.
+Often it gives enough time for the resource (mail server, directory service,
+router etc) to recover and resume normal operation.
+
+After a certain period of time, circuit breaker attempts to restore
+the link and, if it sees that the problem is still there, it breaks it
+again.
+
+
+Installation
+============
+
+	gem install circuit_b
+
+
+Configuration
+=============
+
+	CircuitB.configure do |c|
+
+		# Configure the storage that will be used to store the
+		# state of the fuses across multiple invocations.
+		# There are Memory- and Redis-based stores:
+		#   - Memore store is good when you don't have
+		#     several threads working with the same fuse,
+		#     like in Rails or other multi-threaded environments.
+		#   - Redis store is good for shared multi-threaded
+		#     environments.
+		c.state_storage = CircuitB::Storage::Redis.new
+
+		# Configure the default fuse configuration that will be
+		# used as the basis when you add your custom fuses. You
+		# can specify only the parameters you want to override then.
+		config.default_fuse_config = {
+			:allowed_failures => 2,
+			:cool_off_period  => 3	# seconds
+		}
+
+		# Adds a fuse named "mail" that is configured to tolerate
+		# 5 failures before opening. After the cool off period
+		# of 60 seconds it will close again. During the cool-off
+		# time it will be raising FastFailure's without even
+		# executing the code to protect the system from overload.
+		c.add_fuse "mail", :allowed_failures => 5, :cool_off_period => 60
+
+	end
+
+
+Available storages
+==================
+
+In order to share the state between co-named fuses, one needs to use
+the storage of the correct type. There are currently two storages for
+the fuse state that you can use:
+
+* _CircuitB::Storage::Memory_ -- the simplest memory-based storage.
+	Ideal for the single-threaded situations.
+
+* _CircuitB::Storage::Redis_ -- Redis-based storage. Well-suited
+	for distributed setups (like multiple workers in Rails and alike)
+	and acts like a simple IPC.
+
+
+Usage
+=====
+
+Every time you want to protect a piece of code, you do this:
+
+	CircuitB("mail") do
+		# Attempting to send mail
+	end
+
+Note, that in order to use "mail" fuse you need to add it to your
+configuration first (see above).
+
+You can use fuses in any number of places, but since the state is
+shared across all fuses with the same name, make sure you use them
+for the same purpose, or better yet, refactor your code to have
+it all in one place.
+
+
+To Do
+=====
+
+* notifications and logging
+* half-open state to open back faster if the problem still exists
+* internal code block execution timeout support
+* incrementing cool-off period on recurring errors (in half-open state)
+* CouchDB storage
+* Memcached storage
+* passing storage configuration through the initializer
+
+License
+=======
+
+Circuit Breaker is Copyright © 2010 [Aleksey Gureiev](mailto:spyromus@noizeramp.com).
+It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

data/lib/circuit_b/configuration.rb

@@ -0,0 +1,34 @@
+require "circuit_b/storage"
+require "circuit_b/fuse"
+
+module CircuitB
+  class Configuration
+
+    DEFAULT_CONFIG = {
+      :allowed_failures => 5,
+      :cool_off_period  => 10 # seconds
+    }
+    
+    attr_accessor :state_storage
+    attr_reader   :default_fuse_config
+    attr_reader   :fuses
+    
+    def initialize
+      @state_storage = CircuitB::Storage::Memory.new
+      @default_fuse_config = DEFAULT_CONFIG.clone
+      @fuses = {}
+    end
+
+    def default_fuse_config=(config)
+      @default_fuse_config = DEFAULT_CONFIG.merge(config)
+    end
+    
+    def add_fuse(name, config = {})
+      raise "Fuse with this name is already registered" if @fuses.include?(name)
+
+      config = DEFAULT_CONFIG.merge(config || {})
+      @fuses[name] = CircuitB::Fuse.new(name, state_storage, config)
+    end
+    
+  end
+end

data/lib/circuit_b/fuse.rb

@@ -0,0 +1,74 @@
+require 'circuit_b/storage/base'
+
+module CircuitB
+  class Fuse
+
+    attr_reader :config
+
+    def initialize(name, state_storage, config)
+      raise "Name must be specified" if name.nil?
+      raise "Storage must be specified" if state_storage.nil?
+      raise "Storage must be of CircuitB::Storage::Base kind" unless state_storage.kind_of?(CircuitB::Storage::Base)
+      raise "Config must be specified" if config.nil?
+      
+      @name          = name
+      @state_storage = state_storage
+      @config        = config
+    end
+
+    def wrap(&block)
+      close_if_cooled_off if open?
+      raise CircuitB::FastFailure if open?
+      
+      begin
+        block.call
+
+        put(:failures, 0)
+      rescue => e
+        # Save the time of the last failure
+        put(:last_failure_at, Time.now.to_i)
+      
+        # Increment the number of failures and open if the limit has been reached
+        failures = inc(:failures)
+        open if failures >= @config[:allowed_failures]
+      
+        # Re-raise the original exception
+        raise e
+      end
+    end
+    
+    def open?
+      get(:state) == :open
+    end
+
+    def failures
+      get(:failures)
+    end
+    
+    private
+
+    def close_if_cooled_off
+      if Time.now.to_i - get(:last_failure_at).to_i > config[:cool_off_period]
+        put(:state, :closed)
+        put(:failures, 0)
+      end
+    end
+    
+    # Open the fuse
+    def open
+      put(:state, :open)
+    end
+    
+    def get(field)
+      @state_storage.get(@name, field)
+    end
+    
+    def put(field, value)
+      @state_storage.put(@name, field, value)
+    end
+    
+    def inc(field)
+      @state_storage.inc(@name, field)
+    end
+  end
+end

data/lib/circuit_b/storage/base.rb

@@ -0,0 +1,18 @@
+module CircuitB
+  module Storage
+    class Base
+      
+      def put(fuse_name, field, value)
+        raise "Unimplemented"
+      end
+      
+      def get(fuse_name, field)
+        raise "Unimplemented"
+      end
+
+      def inc(fuse_name, field)
+        raise "Unimplemented"
+      end
+    end
+  end
+end

data/lib/circuit_b/storage/memory.rb

@@ -0,0 +1,27 @@
+require 'circuit_b/storage/base'
+
+module CircuitB
+  module Storage
+    class Memory < Base
+
+      def initialize
+        @fuse_states = {}
+      end
+      
+      def put(fuse_name, field, value)
+        @fuse_states[fuse_name] ||= {}
+        @fuse_states[fuse_name][field.to_sym] = value
+      end
+      
+      def get(fuse_name, field)
+        (@fuse_states[fuse_name] || {})[field.to_sym]
+      end
+  
+      def inc(fuse_name, field)
+        new_val = get(fuse_name, field).to_i + 1
+        put(fuse_name, field, new_val)
+        return new_val
+      end
+    end
+  end
+end

data/lib/circuit_b/storage/redis.rb

@@ -0,0 +1,31 @@
+require 'circuit_b/storage/base'
+require 'redis'
+
+module CircuitB
+  module Storage
+    class Redis < Base
+
+      def initialize
+        @redis = ::Redis.new
+      end
+      
+      def put(fuse_name, field, value)
+        @redis[key(fuse_name, field)] = value
+      end
+      
+      def get(fuse_name, field)
+        @redis[key(fuse_name, field)]
+      end
+  
+      def inc(fuse_name, field)
+        return @redis.incr(key(fuse_name, field))
+      end
+      
+      private
+      
+      def key(fuse_name, field)
+        "circuit_b:#{fuse_name}:#{field}"
+      end
+    end
+  end
+end

data/lib/circuit_b/storage.rb

@@ -0,0 +1,2 @@
+require "circuit_b/storage/memory"
+require "circuit_b/storage/redis"

data/lib/circuit_b.rb

@@ -0,0 +1,34 @@
+require "circuit_b/fuse"
+require "circuit_b/configuration"
+require "circuit_b/storage"
+
+module CircuitB
+  
+  class FastFailure < StandardError; end
+  
+  def self.configure(&block)
+    block.call(configuration)
+  end
+  
+  def self.configuration
+    @configuration ||= CircuitB::Configuration.new
+  end
+  
+  def self.reset_configuration
+    @configuration = nil
+  end
+  
+  def self.fuse(name, &block)
+    raise "Fuse with the name '#{name}' is not registered" unless fuse = configuration.fuses[name]
+    
+    if block
+      fuse.wrap(&block)
+    else
+      return fuse
+    end
+  end
+end
+
+def CircuitB(fuse_name, &block)
+  CircuitB.fuse(fuse_name, &block)
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require "rubygems"
+require "test/unit"
+require "shoulda"
+require "timecop"
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")

data/test/unit/circuit_b/test_configuration.rb

@@ -0,0 +1,39 @@
+require File.dirname(__FILE__) + "/../../test_helper"
+require "circuit_b/configuration"
+
+class CircuitB::TestConfiguration < Test::Unit::TestCase
+
+  def setup
+    @config = CircuitB::Configuration.new
+  end
+  
+  should "configure memory storage by default" do
+    assert @config.state_storage.is_a?(CircuitB::Storage::Memory)
+  end
+
+  should "accept default fuse configuration updates" do
+    @config.default_fuse_config = {
+      :allowed_failures => 2,
+      :cool_off_period => 3  # seconds
+    }
+  end
+  
+  should "add a named fuse with default configuration" do
+    @config.add_fuse "fuse_name"
+    assert_equal 1, @config.fuses.size
+  end
+  
+  should "add a named fuse with custom configuration" do
+    @config.add_fuse "fuse_name", :allowed_failures => 5
+  end
+  
+  should "disallow adding fuses with the same name" do
+    @config.add_fuse "fuse_name"
+    begin
+      @config.add_fuse "fuse_name"
+      fail "should raise an exception"
+    rescue
+      # Exception is expected
+    end
+  end
+end

data/test/unit/circuit_b/test_fuse.rb

@@ -0,0 +1,123 @@
+require File.dirname(__FILE__) + "/../../test_helper"
+require "circuit_b"
+
+class CircuitB::TestFuse < Test::Unit::TestCase
+  
+  context "initialization" do
+    should "not allow nil names" do
+      begin
+        CircuitB::Fuse.new(nil, nil, {})
+        fail "Exception is expected"
+      rescue => e
+        assert_equal "Name must be specified", e.message
+      end
+    end
+
+    should "not allow nil-storages" do
+      begin
+        CircuitB::Fuse.new("name", nil, {})
+        fail "Exception is expected"
+      rescue => e
+        assert_equal "Storage must be specified", e.message
+      end
+    end
+
+    should "disallow storages of the wrong type" do
+      begin
+        CircuitB::Fuse.new("name", "", nil)
+        fail "Exception is expected"
+      rescue => e
+        assert_equal "Storage must be of CircuitB::Storage::Base kind", e.message
+      end
+    end
+  
+    should "not allow nil-configs" do
+      begin
+        CircuitB::Fuse.new("name", CircuitB::Storage::Memory.new, nil)
+        fail "Exception is expected"
+      rescue => e
+        assert_equal "Config must be specified", e.message
+      end
+    end
+  end
+  
+  context "operation" do
+    setup do
+      @fuse = CircuitB::Fuse.new("name", CircuitB::Storage::Memory.new, :allowed_failures => 1, :cool_off_period => 60)
+    end
+    
+    should "open when the allowed failures reached" do
+      assert !@fuse.open?
+      do_failure(@fuse)
+      assert @fuse.open?
+    end
+  
+    should "reset the failures counter when the attempt succeeds" do
+      @fuse = CircuitB::Fuse.new("name", CircuitB::Storage::Memory.new, :allowed_failures => 2)
+
+      do_failure(@fuse)
+      assert_equal 1, @fuse.failures
+      
+      @fuse.wrap do
+        # Successful code
+      end
+      
+      assert_equal 0, @fuse.failures
+    end
+  
+    should "fail fast when open" do
+      # Open the fuse and verify it's open
+      do_failure(@fuse)
+      assert @fuse.open?
+    
+      begin
+        @fuse.wrap do
+          fail "Must not execute as fail-fast exception is expected"
+        end
+      rescue => e
+        assert e.is_a?(CircuitB::FastFailure), "Wrong exception: #{e.inspect}"
+      end
+    end
+    
+    should "close after the cooling period" do
+      do_failure(@fuse)
+
+      Timecop.travel(Time.now + @fuse.config[:cool_off_period] + 1) do
+        @fuse.send(:close_if_cooled_off)
+        
+        assert !@fuse.open?
+        assert_equal 0, @fuse.failures
+      end
+    end
+    
+    should "not count fast failure as an error" do
+      do_failure(@fuse)
+
+      # Get the fast failure
+      Timecop.travel(Time.now + @fuse.config[:cool_off_period] / 2) do
+        begin
+          do_failure(@fuse, true)
+          fail "Fast failure is expected"
+        rescue CircuitB::FastFailure => e
+          # Expected
+        end
+      end
+
+      # The above fast failure should not affect the cooling off schedule
+      Timecop.travel(Time.now + @fuse.config[:cool_off_period] + 1) do
+        @fuse.send(:close_if_cooled_off)
+        assert !@fuse.open?
+      end
+    end
+  end
+  
+  def do_failure(fuse, rethrow = false)
+    begin
+      @fuse.wrap do
+        raise "Exceptional code"
+      end
+    rescue => e
+      raise e if rethrow
+    end
+  end
+end

data/test/unit/test_circuit_b.rb

@@ -0,0 +1,77 @@
+require File.dirname(__FILE__) + "/../test_helper"
+require "circuit_b"
+require "circuit_b/configuration"
+require "circuit_b/storage"
+
+class TestCircuitB < Test::Unit::TestCase
+  
+  context "configuration" do
+    should "accept configuration paramters" do
+      CircuitB.configure do |config|
+        config.state_storage = CircuitB::Storage::Memory.new
+
+        config.default_fuse_config = {
+          :allowed_failures => 2,
+          :cool_off_period  => 3  # seconds
+        }
+
+        config.add_fuse("mail", {
+          :allowed_failures => 5,
+          :cool_off_period  => 10 # seconds
+        })
+      end
+    end
+    
+    should "return configuration" do
+      config = CircuitB.configuration
+      assert config.is_a?(CircuitB::Configuration)
+    end
+  end
+  
+  context "using fuses to protect code" do
+    setup do
+      CircuitB.reset_configuration
+      CircuitB.configure do |c|
+        c.state_storage = CircuitB::Storage::Redis.new
+        c.add_fuse "fuse_name", :allowed_failures => 1, :cool_off_period => 10
+      end
+    end
+    
+    should "let wrap the code with fuse" do      
+      executed = false
+      CircuitB("fuse_name") do
+        # Some lengthy and potentially failing operation
+        executed = true
+      end
+      
+      assert executed, "Code wasn't executed"
+    end
+    
+    should "error out if the fuse doesn't exist" do
+      begin
+        CircuitB("non_existent_fuse") do
+          # Will never be executed
+          fail "Should never be executed"
+        end
+      rescue => e
+        assert_equal "Fuse with the name 'non_existent_fuse' is not registered", e.message
+      end
+    end
+    
+    should "pass the error when it's raised by the code" do
+      begin
+        CircuitB("fuse_name") do
+          raise "App error"
+        end
+        fail "App error should be raised"
+      rescue => e
+        assert_equal "App error", e.message
+      end
+    end
+    
+    should "return the fuse if no block is given" do
+      assert CircuitB("fuse_name").is_a?(CircuitB::Fuse)
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: circuit_b
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Aleksey Gureiev
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-30 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: Classic circuit breaker to protect resources from being accessed over and over while in pain.
+email: spyromus@noizeramp.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- MIT-LICENSE
+- README.md
+files: 
+- lib/circuit_b/configuration.rb
+- lib/circuit_b/fuse.rb
+- lib/circuit_b/storage/base.rb
+- lib/circuit_b/storage/memory.rb
+- lib/circuit_b/storage/redis.rb
+- lib/circuit_b/storage.rb
+- lib/circuit_b.rb
+- test/test_helper.rb
+- test/unit/circuit_b/test_configuration.rb
+- test/unit/circuit_b/test_fuse.rb
+- test/unit/test_circuit_b.rb
+- MIT-LICENSE
+- README.md
+has_rdoc: true
+homepage: http://github.com/alg/circuit_b
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- CircuitB - Distributed circuit breaker
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Distributed circuit breaker
+test_files: []
+