supervision 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11acf39bc8b8bc7f6c2ab1ac8f58696aa305c7f5
-  data.tar.gz: 697bf64670a3fe4fed371cc6f2ed7b8c700b1ae6
+  metadata.gz: 25069ea70f148108ba3d577443b7a0d1a7deda62
+  data.tar.gz: 66d41d2d5178262807f6bab0a33f8b38189d981d
 SHA512:
-  metadata.gz: 6e81cdae2a3f09db0bc05511d1291e2291b54150bdd8ac7d4580e01a4010769fb05b428cd02e874f8c2766f97239ca2e941c71057e10f38f8f424b5bf25e1366
-  data.tar.gz: 04449ffd0306979981482efaf67818a37e4a2bda9cc4173933f532402c7f8c9b3ac8242b62dd3ff09444d696f2aec38e0a1c5b509509c16a10c9c5e70afc4669
+  metadata.gz: b4541f7b303608839038831f34f57968eabcaf924dcd7b57b638831e2370dbe9d8eb555f5b4e288a5186dbd6a30eed343b0910e3716ada40e8f69056f8f4e90c
+  data.tar.gz: 67fdf192edd72807c1406535be44daeecf982e5576dca42189b570d7b8b9b8499e94d7c984f7d3291ae2f1b371e3c1667acb26b1c88804f7623a783b3257e876

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+0.2.0 (May 12, 2014)
+
+* Add InvalidParameterError, DuplicateEntryError types
+* Add on_success & on_failure callbacks
+* Change configuration to have more expressive setters
+* Add shutdown to circuit system
+* Add ability for dynamic calls on Supervision module
+* Add ability to call supervised methods directly on object
+  when Supervision is included as a module
+* Add ability to force reset circuit to closed state
+* Add tests to ensure reset scheduler works properly
+* Add ability to query configuration options on supervision instance

data/README.md

@@ -2,10 +2,12 @@
 [![Gem Version](https://badge.fury.io/rb/supervision.png)][gem]
 [![Build Status](https://secure.travis-ci.org/peter-murach/supervision.png?branch=master)][travis]
 [![Code Climate](https://codeclimate.com/github/peter-murach/supervision.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/peter-murach/supervision/badge.png)][coverage]
 
 [gem]: http://badge.fury.io/rb/supervision
 [travis]: http://travis-ci.org/peter-murach/supervision
 [codeclimate]: https://codeclimate.com/github/peter-murach/supervision
+[coverage]: https://coveralls.io/r/peter-murach/supervision
 
 Write distributed systems that are resilient and self-heal. Remote calls can fail or hang indefinietly without a response.
 **Supervision** will help to isolate failure and keep individual components from bringing down the whole system.
@@ -52,21 +54,29 @@ Once the call is wrapped you can execute it by sending `call` messsage with argu
 @supervision.call({user: 'Piotr'})
 ```
 
-Finally, you can also register **Supervision** instance by name
+## 2 System
+
+You can register more than one **Supervision** by using internal register system. Simply register name under which you want the circuit to be available by calling `supervise_as` helper:
 
 ```ruby
 Supervision.supervise_as(:danger) { remote_api_call }
 ```
 
-The name under which method is registerd will be available as a method call
+In order to retrieve registered circuit you can use hash syntax:
+
+```ruby
+Supervision[:danger]  # => returns registered circuit
+```
+
+The name under which method is registerd will be available as a method call. Consequently, to execute registered circuit do:
 
 ```ruby
-Supervision.danger.call
+Supervision.danger(:foo, :bar)  # => will call underlying method and pass :foo, :barr
 ```
 
-## 2 Mixin
+## 3 Mixin
 
-**Supervision** can also act as a mixin and expose `supervise` and `supervise_as` accordingly.
+**Supervision** can also act as a mixin and expose `supervise` and `supervise_as` accordingly. Use `supervise_as` if you want to be able to register supervised calls inside **Supervision** system. Otherwise, use `supervise` helper to create anonymous supervised call.
 
 ```ruby
 class Api
@@ -75,10 +85,10 @@ class Api
   def remote_call
     ...
   end
-  supervise :danger { remote_call }
+  supervise_as :danger { remote_call }  # => register supervision as :danger
 
   def fetch(repository)
-    danger.call(repository)
+    danger(repository)
   rescue Supervision::CircuitBreakerOpenError
     nil
   end
@@ -88,7 +98,7 @@ end
 @api.fetch('github_api')
 ```
 
-## 3 Callbacks
+## 4 Callbacks
 
 You can listen for `failure` and `success` by attaching `on_failure`, `on_success` listeners respectively:
 
@@ -100,7 +110,7 @@ def notify_me
 end
 ```
 
-## 4 Configuration
+## 5 Configuration
 
 If you want to configure **Supervision**, you can either pass options directly
 
@@ -120,7 +130,7 @@ or use `configure` helper
 end
 ```
 
-## 5 Time
+## 6 Time
 
 All the numeric types are extended with time related helpers to allow for more fluid parameters when creating **Supervision**
 

data/lib/supervision.rb

@@ -2,6 +2,7 @@
 
 require "thread"
 require "timeout"
+require "forwardable"
 require "finite_machine"
 
 require "supervision/version"
@@ -13,6 +14,7 @@ require "supervision/circuit_control"
 require "supervision/circuit_breaker"
 require "supervision/circuit_system"
 require "supervision/circuit_monitor"
+require "supervision/counter"
 
 module Supervision
   # Generic error
@@ -21,8 +23,15 @@ module Supervision
   # Raised when circuit opens
   CircuitBreakerOpenError = Class.new(SupervisionError)
 
+  # Raised when checking circuit type
   TypeError = Class.new(SupervisionError)
 
+  # Raised when invalid configuration parameter is specified
+  InvalidParameterError = Class.new(SupervisionError)
+
+  # Raised when registering duplicate circuit breaker name
+  DuplicateEntryError = Class.new(SupervisionError)
+
   class << self
     def included(base)
       base.send :extend, ClassMethods
@@ -32,6 +41,9 @@ module Supervision
       @configuration ||= Configuration.new
     end
 
+    # Initialize a circuit system
+    #
+    # @api private
     def init
       @circuit_system = CircuitSystem.new
     end
@@ -46,6 +58,22 @@ module Supervision
     def new(name = nil, options = {}, &block)
       name ? supervise_as(name, options, &block) : supervise(options, &block)
     end
+
+    # Retrieve circuit by name
+    #
+    # @return [Supervision::CircuitBreaker]
+    #
+    # @api public
+    def [](name)
+      circuit_system[name]
+    end
+
+    private
+
+    def method_missing(method_name, *args, &block)
+      super unless circuit_system.registered?(method_name)
+      self[method_name].call(*args)
+    end
   end
 
   module ClassMethods
@@ -54,8 +82,8 @@ module Supervision
     end
 
     def supervise_as(name, options = {}, &block)
-      circuit = supervise(options, &block)
-      Supervision.circuit_system[name] = circuit
+      circuit = supervise(options.merge!(name: name), &block)
+      Supervision.circuit_system.register(name, circuit)
       send(:define_method, name) { |*args| circuit.call(args) }
       circuit
     end

data/lib/supervision/circuit_breaker.rb

@@ -4,19 +4,29 @@ module Supervision
   # A class responsible for protecting remote calls
   class CircuitBreaker
     include Timeout
+    extend Forwardable
 
     attr_reader :control
 
+    attr_reader :name
+
+    def_delegators :@control, :current, :max_failures, :call_timeout,
+                   :reset_timeout
+
+    # Create a CircuitBreaker
+    #
+    # @example
+    #   circuit = CircuitBreaker { ... }
+    #
+    # @api public
     def initialize(options = {}, &block)
       if block.nil?
-        raise ArgumentError, 'CircuitBreaker.new requires a block'
+        raise InvalidParameterError, 'CircuitBreaker.new requires a block'
       end
+      @name    = options.delete(:name)
       @control = CircuitControl.new(options)
       @circuit = Atomic.new(block)
       @mutex   = Mutex.new
-      @before_hook  = -> {}
-      @success_hook = -> {}
-      @failure_hook = -> {}
     end
 
     # Configure circuit instance parameters
@@ -25,11 +35,7 @@ module Supervision
     #
     # @api public
     def configure(&block)
-      if block.arity.zero?
-        control.config.instance_eval(&block)
-      else
-        yield control.config
-      end
+      control.config.configure(&block)
     end
 
     # Executes the dangerous call
@@ -39,42 +45,100 @@ module Supervision
     #
     # @api public
     def call(*args)
-      @before_hook.call
+      handle_before
       begin
         result = dispatch(*args)
-        @success_hook.call
+        handle_success
         result
       rescue Exception => error
-        control.handle(error)
-        @failure_hook.call
+        handle_failure(error)
       end
     end
 
-    def force_open
-    end
-
-    def force_close
+    # Reset this circuit to closed state
+    #
+    # @example
+    #   supervision.reset!
+    #
+    # @return [nil]
+    #
+    # @api public
+    def reset!
+      control.reset!
     end
 
+    # Define before handler
+    #
+    # @api public
     def before(&block)
-      @before_hook = block
+      @before = block
+      self
     end
 
-    # Callback executed on successful call
+    # Define success handler
+    #
+    # @return [Supervision::CircuitBreaker]
     #
     # @api public
     def on_success(&block)
-      @success_hook = block
+      @on_success = block
+      self
     end
     alias_method :on_closed, :on_success
 
+    # Define failure handler
+    #
+    # @return [Supervision::CircuitBreaker]
+    #
+    # @api public
     def on_failure(&block)
-      @failure_hook = block
+      @on_failure = block
+      self
     end
     alias_method :on_open, :on_failure
 
+    # Detailed string representation of this circuit
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      "#<#{self.class.name}:#{object_id} @name=#{name}>"
+    end
+
+    # Detailed string representation of this circuit
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_s
+      "#<#{self.class.name}:#{object_id} @name=#{name}>"
+    end
+
     private
 
+    # Invoke before handler
+    #
+    # @api private
+    def handle_before
+      @before.call if @before
+    end
+
+    # Invoke success handler
+    #
+    # @api private
+    def handle_success
+      @on_success.call if @on_success
+    end
+
+    # Invoke failure handler and instrument circuit controller
+    #
+    # @api private
+    def handle_failure(error)
+      control.handle_failure(error)
+      @on_failure.call(error) if @on_failure
+    end
+
     # Dispatch message to the current circuit
     #
     # @api private

data/lib/supervision/circuit_control.rb

@@ -5,10 +5,24 @@ module Supervision
   class CircuitControl
     extend Forwardable
 
-    def_delegators :@config, :max_failures, :call_timeout, :failure_count
+    def_delegators :@config, :max_failures, :call_timeout, :reset_timeout,
+                   :failure_count
 
+    # The circuit configuration
+    #
+    # @api private
     attr_reader :config
 
+    # The reset timeout scheduler
+    #
+    # @api private
+    attr_reader :scheduler
+
+    # The circuit performance monitor
+    #
+    # @api private
+    attr_reader :monitor
+
     MAX_THREAD_LIFETIME = 5
 
     # Create a circuit control
@@ -21,6 +35,7 @@ module Supervision
       @failure_count     = Atomic.new(0)
       @last_failure_time = Atomic.new
       @lock              = Mutex.new
+      @monitor           = CircuitMonitor.new
       fsm
     end
 
@@ -38,13 +53,13 @@ module Supervision
 
         target context
 
-        events {
+        events do
           event :trip,         [:closed, :half_open] => :open
-          event :attempt_reset, :open => :half_open
-          event :reset,         :half_open => :closed
-        }
+          event :attempt_reset, :open                => :half_open
+          event :reset,         :half_open           => :closed
+        end
 
-        callbacks {
+        callbacks do
           on_enter :closed do |event|
             reset_failure
           end
@@ -55,12 +70,14 @@ module Supervision
           end
 
           on_enter :half_open do |event|
+            monitor.measure(:half_open_circuit)
           end
-        }
+        end
       end
     end
 
-    def_delegators :@fsm, :trip, :attempt_reset, :reset, :current
+    def_delegators :@fsm, :trip, :trip!, :attempt_reset, :attempt_reset!,
+                   :reset, :current
 
     # Total failure count for current circuit
     #
@@ -80,13 +97,24 @@ module Supervision
       @last_failure_time.value
     end
 
+    # Force closed state and reset failure statistics
+    #
+    # @return [nil]
+    #
+    # @api public
+    def reset!
+      fsm.reset!
+      reset_failure
+      throw(:terminate) if @scheduler && @scheduler.alive?
+    end
+
     # Fail fast on any call
     #
     # @raise [CircuitBreakerOpenError]
     #
     # @api private
     def fail_fast!
-      # monitor.record_open
+      monitor.measure(:open_circuit)
       raise CircuitBreakerOpenError
     end
 
@@ -120,18 +148,23 @@ module Supervision
     # Handler exception
     #
     # @api public
-    def handle(error = nil)
+    def handle_failure(error = nil)
       fail_fast! if fsm.open?
       record_failure
+      monitor.record_failure
       trip if failure_count_exceeded? || fsm.half_open?
     end
 
+    # Record successful call
+    #
+    # @api public
     def record_success
       reset if fsm.half_open?
       reset_failure
+      monitor.record_success
     end
 
-    # Records failure count
+    # Record failure count
     #
     # @api public
     def record_failure
@@ -153,18 +186,27 @@ module Supervision
     #
     # @api private
     def measure_timeout
-      Thread.new do
+      @scheduler = Thread.new do
         Thread.current.abort_on_exception = true
         thread = Thread.current
         thread[:created_at] = Time.now
         @lock.synchronize do
-          loop do
-            if tripped?
-              attempt_reset
-              break
-            elsif Time.now - thread[:created_at] > max_thread_lifetime
-              thread.kill
-            end
+          run_loop(thread)
+        end
+      end
+    end
+
+    # Run scheduler loop
+    #
+    # @api private
+    def run_loop(thread)
+      catch(:terminate) do
+        loop do
+          if tripped?
+            attempt_reset && break
+          elsif Time.now - thread[:created_at] > max_thread_lifetime
+            thread.kill if thread.alive?
+            break
           end
         end
       end