circuit_b 1.0 → 1.1

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+Version 1.1
+===========
+
+* Added on-break handling features
+* Fixed the default fuse configuration handling
+* Added internal code execution timeouts

data/README.md

@@ -38,9 +38,11 @@ Configuration
 		# 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 = {
+		c.default_fuse_config = {
+			:on_break         => [ :rails_log, lambda { do_something } ],
 			:allowed_failures => 2,
 			:cool_off_period  => 3	# seconds
+			:timeout          => 3  # seconds, defaults to 5
 		}
 
 		# Adds a fuse named "mail" that is configured to tolerate
@@ -48,7 +50,7 @@ Configuration
 		# 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
+		c.fuse "mail", :allowed_failures => 5, :cool_off_period => 60
 
 	end
 
@@ -68,6 +70,48 @@ the fuse state that you can use:
 	and acts like a simple IPC.
 
 
+Acting on Fuse Breaks
+=====================
+
+When the ciruit is broken, meaning that your wrapped code has produced
+so many errors that we had to isolate it, the fuse opens and starts to
+fail fast. You may want to act in one way or another when it happens.
+There's a fuse configuration option `on_break` that accepts one or more
+elements describing what you want to do.
+
+*Logging.* One of the common steps is to log the event. There's a
+standard logging feature (`:rails_log`) that writes a message to the
+default Rails log. If you don't use Rails, you can use the next feature
+to take care of your logging.
+
+	config.fuse "test", :on_break => :rails_log
+
+*Handling.* If you want to handle the event in some custom way, you
+can provide a `Proc` that will be executed upon event. One common case
+is to write to the log. 
+
+	config.fuse "test", :on_break => lambda { |fuse| puts "Fuse #{fuse.name} has just broke the circuit" }
+
+To specify more than one handler, you can use an array:
+
+	config.fuse "test", :on_break => [ :rails_log, lambda { ... }, lambda { ... } ]
+
+
+Code execution timeouts
+=======================
+
+To protect your code from executing for too long, fuses in CircuitB can
+execute it wrapped into the timeout statements. All you have to do is
+to configure a fuse to use timeouts logic, like this (to allow 5 second for
+wrapped code execution):
+
+	config.fuse "test", :timeout => 2
+
+To disable timeouts (which isn't a great idea), use `:timeout => false`.
+
+By default, all fuses use 5 second timeouts.
+
+
 Usage
 =====
 
@@ -89,9 +133,7 @@ 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

data/Rakefile

@@ -0,0 +1,31 @@
+# encoding: utf-8
+require 'rubygems'
+require 'rake'
+$:.unshift(File.dirname(__FILE__) + '/lib')
+ 
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "circuit_b"
+    gem.version     = "1.1"
+    gem.summary     = %Q{Distributed circuit breaker}
+    gem.description = %Q{Classic circuit breaker to protect resources from being accessed over and over while in pain.}
+    gem.email       = "spyromus@noizeramp.com"
+    gem.homepage    = "http://github.com/alg/circuit_b"
+    gem.authors     = ["Aleksey Gureiev"]
+ 
+    gem.add_development_dependency 'shoulda', '>= 2.10.3'
+    gem.add_development_dependency 'timecop', '>= 0.3.4'
+  end
+ 
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+ 
+Dir['gem_tasks/**/*.rake'].each { |rake| load rake }
+ 
+task :default => [:check_dependencies, :test]
+ 
+require 'rake/clean'
+CLEAN.include %w(**/*.{log,pyc})

data/circuit_b.gemspec

@@ -0,0 +1,64 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{circuit_b}
+  s.version = "1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Aleksey Gureiev"]
+  s.date = %q{2010-02-04}
+  s.description = %q{Classic circuit breaker to protect resources from being accessed over and over while in pain.}
+  s.email = %q{spyromus@noizeramp.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    "CHANGELOG.md",
+     "MIT-LICENSE",
+     "README.md",
+     "Rakefile",
+     "circuit_b.gemspec",
+     "lib/circuit_b.rb",
+     "lib/circuit_b/configuration.rb",
+     "lib/circuit_b/fuse.rb",
+     "lib/circuit_b/storage.rb",
+     "lib/circuit_b/storage/base.rb",
+     "lib/circuit_b/storage/memory.rb",
+     "lib/circuit_b/storage/redis.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"
+  ]
+  s.homepage = %q{http://github.com/alg/circuit_b}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Distributed circuit breaker}
+  s.test_files = [
+    "test/test_helper.rb",
+     "test/unit/circuit_b/test_configuration.rb",
+     "test/unit/circuit_b/test_fuse.rb",
+     "test/unit/test_circuit_b.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<shoulda>, [">= 2.10.3"])
+      s.add_development_dependency(%q<timecop>, [">= 0.3.4"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 2.10.3"])
+      s.add_dependency(%q<timecop>, [">= 0.3.4"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 2.10.3"])
+    s.add_dependency(%q<timecop>, [">= 0.3.4"])
+  end
+end
+

data/lib/circuit_b/configuration.rb

@@ -5,6 +5,8 @@ module CircuitB
   class Configuration
 
     DEFAULT_CONFIG = {
+      :log              => true,
+      :timeout          => 5, # seconds
       :allowed_failures => 5,
       :cool_off_period  => 10 # seconds
     }
@@ -19,14 +21,34 @@ module CircuitB
       @fuses = {}
     end
 
+    # Sets the default fuse configuration. This configuration will be used
+    # as the basis for all fuses. You can override the values by providing
+    # your own when calling #fuse.
+    #
+    #   CircuitB.configure do |c|
+    #     c.default_fuse_config = {
+    #       :on_break         => [ :rails_log, lambda { do_something } ],
+		#       :allowed_failures => 2,
+		#       :cool_off_period  => 3	# seconds
+    #     }
+    #   end
     def default_fuse_config=(config)
       @default_fuse_config = DEFAULT_CONFIG.merge(config)
     end
     
-    def add_fuse(name, config = {})
+    # Adds a fuse with a given name and custom config.
+    # If the fuse with the same name is already there, the RuntimeError is raised.
+    # The values of the provided configuration are used to override
+    # the default configuration that can be set with #default_fuse_config.
+    #
+    #   CircuitB.configure do |c|
+    #     c.fuse "directory-auth", :on_break => lambda { notify_hoptoad(...) }, :allowed_failures => 5
+    #     c.fuse "image-resizing", :allowed_failures => 2, :cool_off_period => 30
+    #   end
+    def fuse(name, config = {})
       raise "Fuse with this name is already registered" if @fuses.include?(name)
 
-      config = DEFAULT_CONFIG.merge(config || {})
+      config = @default_fuse_config.merge(config || {})
       @fuses[name] = CircuitB::Fuse.new(name, state_storage, config)
     end
     

data/lib/circuit_b/fuse.rb

@@ -3,7 +3,16 @@ require 'circuit_b/storage/base'
 module CircuitB
   class Fuse
 
-    attr_reader :config
+    # Maximum time the handler is allowed to execute
+    DEFAULT_BREAK_HANDLER_TIMEOUT = 5
+    
+    # Standard handlers that can be refered by their names
+    STANDARD_HANDLERS = {
+      :rails_log => lambda { |fuse| RAILS_DEFAULT_LOGGER.error("CircuitB: Fuse '#{fuse.name}' has broken") }
+    }
+
+    attr_reader :name, :config
+    attr_accessor :break_handler_timeout
 
     def initialize(name, state_storage, config)
       raise "Name must be specified" if name.nil?
@@ -14,6 +23,8 @@ module CircuitB
       @name          = name
       @state_storage = state_storage
       @config        = config
+      
+      @break_handler_timeout = DEFAULT_BREAK_HANDLER_TIMEOUT
     end
 
     def wrap(&block)
@@ -21,10 +32,14 @@ module CircuitB
       raise CircuitB::FastFailure if open?
       
       begin
-        block.call
+        if @config[:timeout] && @config[:timeout].to_f > 0
+          Timeout::timeout(@config[:timeout].to_f) { block.call }
+        else
+          block.call
+        end
 
         put(:failures, 0)
-      rescue => e
+      rescue Exception => e
         # Save the time of the last failure
         put(:last_failure_at, Time.now.to_i)
       
@@ -57,6 +72,24 @@ module CircuitB
     # Open the fuse
     def open
       put(:state, :open)
+      
+      if config[:on_break]
+        require 'timeout'
+        
+        handlers = [ config[:on_break] ].flatten.map { |handler| (handler.is_a?(Symbol) ? STANDARD_HANDLERS[handler] : handler) }.compact
+
+        handlers.each do |handler|
+          begin
+            Timeout::timeout(@break_handler_timeout) {
+              handler.call(self)
+            }
+          rescue Timeout::Error
+            # We ignore handler timeouts
+          rescue
+            # We ignore handler errors
+          end
+        end
+      end
     end
     
     def get(field)

data/test/unit/circuit_b/test_configuration.rb

@@ -19,18 +19,18 @@ class CircuitB::TestConfiguration < Test::Unit::TestCase
   end
   
   should "add a named fuse with default configuration" do
-    @config.add_fuse "fuse_name"
+    @config.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
+    @config.fuse "fuse_name", :allowed_failures => 5
   end
   
   should "disallow adding fuses with the same name" do
-    @config.add_fuse "fuse_name"
+    @config.fuse "fuse_name"
     begin
-      @config.add_fuse "fuse_name"
+      @config.fuse "fuse_name"
       fail "should raise an exception"
     rescue
       # Exception is expected

data/test/unit/circuit_b/test_fuse.rb

@@ -43,7 +43,7 @@ class CircuitB::TestFuse < Test::Unit::TestCase
   
   context "operation" do
     setup do
-      @fuse = CircuitB::Fuse.new("name", CircuitB::Storage::Memory.new, :allowed_failures => 1, :cool_off_period => 60)
+      @fuse = memory_fuse
     end
     
     should "open when the allowed failures reached" do
@@ -53,7 +53,7 @@ class CircuitB::TestFuse < Test::Unit::TestCase
     end
   
     should "reset the failures counter when the attempt succeeds" do
-      @fuse = CircuitB::Fuse.new("name", CircuitB::Storage::Memory.new, :allowed_failures => 2)
+      @fuse = memory_fuse(:allowed_failures => 2)
 
       do_failure(@fuse)
       assert_equal 1, @fuse.failures
@@ -109,6 +109,65 @@ class CircuitB::TestFuse < Test::Unit::TestCase
         assert !@fuse.open?
       end
     end
+    
+    context "on-break handlers" do
+      should "call single handler" do
+        handler_fuse = nil
+        handler = lambda { |fuse| handler_fuse = fuse }
+        @fuse = memory_fuse(:on_break => handler)
+
+        do_failure(@fuse)
+        
+        assert_equal @fuse, handler_fuse
+      end
+      
+      should "call all of handlers" do
+        handler_calls   = 0
+        handler         = lambda { |fuse| handler_calls += 1 }
+        @fuse = memory_fuse(:on_break => [ handler, handler ])
+        
+        do_failure(@fuse)
+        
+        assert_equal 2, handler_calls
+      end
+      
+      should "ignore failures of handlers" do
+        handler_calls   = 0
+        handler         = lambda { |fuse| handler_calls += 1 }
+        failing_handler = lambda { |fuse| raise "Handling error" }
+        @fuse = memory_fuse(:on_break => [ failing_handler, handler ])
+        
+        do_failure(@fuse)
+        
+        assert_equal 1, handler_calls
+      end
+      
+      should "interrupt long handlers (no more than 5 seconds)" do
+        handler_calls   = 0
+        long_handler    = lambda { |fuse| sleep 10; handler_calls += 1 }
+        short_handler   = lambda { |fuse| handler_calls += 1 }
+        @fuse = memory_fuse(:on_break => [ long_handler, short_handler ])
+        @fuse.break_handler_timeout = 0.1
+        
+        do_failure(@fuse)
+        
+        assert_equal 1, handler_calls
+      end
+    end
+
+    context "execution timeouts" do
+      should "fail long tasks" do
+        @fuse = memory_fuse(:timeout => 0.1)
+        begin
+          @fuse.wrap do
+            sleep 0.2
+          end
+          fail "Timeout::Error should be thrown"
+        rescue Timeout::Error
+          assert @fuse.open?
+        end
+      end
+    end
   end
   
   def do_failure(fuse, rethrow = false)
@@ -120,4 +179,9 @@ class CircuitB::TestFuse < Test::Unit::TestCase
       raise e if rethrow
     end
   end
+  
+  def memory_fuse(options = {})
+    options = { :allowed_failures => 1, :cool_off_period => 60 }.merge(options)
+    CircuitB::Fuse.new("name", CircuitB::Storage::Memory.new, options)
+  end
 end

data/test/unit/test_circuit_b.rb

@@ -15,7 +15,7 @@ class TestCircuitB < Test::Unit::TestCase
           :cool_off_period  => 3  # seconds
         }
 
-        config.add_fuse("mail", {
+        config.fuse("mail", {
           :allowed_failures => 5,
           :cool_off_period  => 10 # seconds
         })
@@ -30,10 +30,16 @@ class TestCircuitB < Test::Unit::TestCase
   
   context "using fuses to protect code" do
     setup do
+      begin
+        CircuitB::Storage::Redis.new.get('dummy', 'field')
+      rescue Errno::ECONNREFUSED => e
+        fail "Please start Redis on default port"
+      end
+      
       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
+        c.fuse "fuse_name", :allowed_failures => 1, :cool_off_period => 10
       end
     end
     

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: circuit_b
 version: !ruby/object:Gem::Version 
-  version: "1.0"
+  version: "1.1"
 platform: ruby
 authors: 
 - Aleksey Gureiev
@@ -9,10 +9,29 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-30 00:00:00 +11:00
+date: 2010-02-04 00:00:00 +11:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.10.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: timecop
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.3.4
+    version: 
 description: Classic circuit breaker to protect resources from being accessed over and over while in pain.
 email: spyromus@noizeramp.com
 executables: []
@@ -20,30 +39,31 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- MIT-LICENSE
 - README.md
 files: 
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- circuit_b.gemspec
+- lib/circuit_b.rb
 - lib/circuit_b/configuration.rb
 - lib/circuit_b/fuse.rb
+- lib/circuit_b/storage.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
+- --charset=UTF-8
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -65,5 +85,8 @@ rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Distributed circuit breaker
-test_files: []
-
+test_files: 
+- test/test_helper.rb
+- test/unit/circuit_b/test_configuration.rb
+- test/unit/circuit_b/test_fuse.rb
+- test/unit/test_circuit_b.rb