supervision 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 11acf39bc8b8bc7f6c2ab1ac8f58696aa305c7f5
+  data.tar.gz: 697bf64670a3fe4fed371cc6f2ed7b8c700b1ae6
+SHA512:
+  metadata.gz: 6e81cdae2a3f09db0bc05511d1291e2291b54150bdd8ac7d4580e01a4010769fb05b428cd02e874f8c2766f97239ca2e941c71057e10f38f8f424b5bf25e1366
+  data.tar.gz: 04449ffd0306979981482efaf67818a37e4a2bda9cc4173933f532402c7f8c9b3ac8242b62dd3ff09444d696f2aec38e0a1c5b509509c16a10c9c5e70afc4669

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+*.sw[a-z]
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.ruby-gemset

@@ -0,0 +1 @@
+supervision

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0

data/.travis.yml

@@ -0,0 +1,22 @@
+language: ruby
+bundler_args: --without yard guard benchmarks
+script: "bundle exec rake ci"
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - ruby-head
+matrix:
+  include:
+    - rvm: jruby-19mode
+    - rvm: jruby-20mode
+    - rvm: jruby-21mode
+    - rvm: jruby-head
+    - rvm: rbx
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+    - rvm: rbx
+  fast_finish: true
+branches:
+  only: master

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake',  '~> 10.2.2'
+  gem 'rspec', '~> 2.14.1'
+  gem 'yard',  '~> 0.8.7'
+end
+
+group :metrics do
+  gem 'coveralls', '~> 0.7.0'
+  gem 'simplecov', '~> 0.8.2'
+  gem 'yardstick', '~> 0.9.9'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Piotr Murach
+
+MIT License
+
+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,154 @@
+# Supervision
+[![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]
+
+[gem]: http://badge.fury.io/rb/supervision
+[travis]: http://travis-ci.org/peter-murach/supervision
+[codeclimate]: https://codeclimate.com/github/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.
+The basic idea is to wrap dangerous method call inside protected `supervise` helper that will monitor for failure and
+handle it according to the specified rules to prevent it from cascading.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'supervision'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install supervision
+
+## 1 Usage
+
+**Supervision** instance takes the following configuration options:
+
+* `:max_failure` - maximum failure count allowed before **Supervision** raises `CircuitBreakerOpenError`. By default `5 failures` are allowed.
+* `:call_timeout` -  duration time for a method before it is assumed to have failed. By default `10 milliseconds`.
+* `:reset_timeout` - duration before a method is allowed to attempt a call. Subsequent calls will fail fast if failure is detected. By default `100 milliseconds`
+
+Next to instantiate the **Supervision** in order to protect a call to external/remote service that has potential to fail do:
+
+```ruby
+@supervision = Supervision.new { |arg| remote_api_call(arg) }
+```
+
+or alternatively use `supervise` helper
+
+```ruby
+@supervision = Supervision.supervise { |arg| remote_api_call(arg) }
+```
+
+Once the call is wrapped you can execute it by sending `call` messsage with arguments like so:
+
+```ruby
+@supervision.call({user: 'Piotr'})
+```
+
+Finally, you can also register **Supervision** instance by name
+
+```ruby
+Supervision.supervise_as(:danger) { remote_api_call }
+```
+
+The name under which method is registerd will be available as a method call
+
+```ruby
+Supervision.danger.call
+```
+
+## 2 Mixin
+
+**Supervision** can also act as a mixin and expose `supervise` and `supervise_as` accordingly.
+
+```ruby
+class Api
+  include Supervision
+
+  def remote_call
+    ...
+  end
+  supervise :danger { remote_call }
+
+  def fetch(repository)
+    danger.call(repository)
+  rescue Supervision::CircuitBreakerOpenError
+    nil
+  end
+end
+
+@api = Api.new
+@api.fetch('github_api')
+```
+
+## 3 Callbacks
+
+You can listen for `failure` and `success` by attaching `on_failure`, `on_success` listeners respectively:
+
+```ruby
+@supervision.on_failure { notify_me }
+
+def notify_me
+  puts("The circuit breaker is now open")
+end
+```
+
+## 4 Configuration
+
+If you want to configure **Supervision**, you can either pass options directly
+
+```ruby
+@supervision = Supervison.new max_failures: 2, call_timeout: 10.milli, reset_timeout: 0.1.sec do
+  remote_api_call
+end
+```
+
+or use `configure` helper
+
+```ruby
+@supervision.configure do
+  max_failures  5
+  call_timeout  10.sec
+  reset_timeout 1.min
+end
+```
+
+## 5 Time
+
+All the numeric types are extended with time related helpers to allow for more fluid parameters when creating **Supervision**
+
+```ruby
+call_timeout: 10.milliseconds
+call_timeout: 10.millis
+call_timeout: 1.millisecond
+call_timeout: 1.milli
+call_timeout: 1.second
+call_timeout: 1.sec
+call_timeout: 10.secs
+call_timeout: 10.seconds
+call_timeout: 1.minute
+call_timeout: 1.min
+call_timeout: 10.minutes
+call_timeout: 10.mins
+call_timeout: 1.hour
+call_timeout: 10.hours
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/supervision/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Copyright
+
+Copyright (c) 2014 Piotr Murach. See LICENSE for further details.

data/Rakefile

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+require "bundler/gem_tasks"
+
+FileList['tasks/**/*.rake'].each(&method(:import))
+
+desc 'Run all specs'
+task ci: %w[ spec ]

data/lib/supervision/atomic.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for creating threadsafe value objects
+  class Atomic
+
+    # Initialize an Atomic instance
+    #
+    # @param [Numeric] value
+    #
+    # @api public
+    def initialize(value = nil)
+      @mutex = Mutex.new
+      @value = value
+    end
+
+    # Retrieve value
+    #
+    # @api public
+    def get
+      @mutex.synchronize { @value }
+    end
+    alias_method :value, :get
+
+    # Set value
+    #
+    # @api public
+    def set(new_value)
+      @mutex.synchronize { @value = new_value}
+    end
+    alias_method :value=, :set
+
+    # Update value
+    #
+    # @api public
+    def update
+      set(new_value = yield(get)) if block_given?
+      new_value
+    end
+  end # Atomic
+end # Supervision

data/lib/supervision/circuit_breaker.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for protecting remote calls
+  class CircuitBreaker
+    include Timeout
+
+    attr_reader :control
+
+    def initialize(options = {}, &block)
+      if block.nil?
+        raise ArgumentError, 'CircuitBreaker.new requires a block'
+      end
+      @control = CircuitControl.new(options)
+      @circuit = Atomic.new(block)
+      @mutex   = Mutex.new
+      @before_hook  = -> {}
+      @success_hook = -> {}
+      @failure_hook = -> {}
+    end
+
+    # Configure circuit instance parameters
+    #
+    # @yield [Configuration]
+    #
+    # @api public
+    def configure(&block)
+      if block.arity.zero?
+        control.config.instance_eval(&block)
+      else
+        yield control.config
+      end
+    end
+
+    # Executes the dangerous call
+    #
+    # # TODO: this should distribute calls so we don't wait
+    #  in sync call for timeout
+    #
+    # @api public
+    def call(*args)
+      @before_hook.call
+      begin
+        result = dispatch(*args)
+        @success_hook.call
+        result
+      rescue Exception => error
+        control.handle(error)
+        @failure_hook.call
+      end
+    end
+
+    def force_open
+    end
+
+    def force_close
+    end
+
+    def before(&block)
+      @before_hook = block
+    end
+
+    # Callback executed on successful call
+    #
+    # @api public
+    def on_success(&block)
+      @success_hook = block
+    end
+    alias_method :on_closed, :on_success
+
+    def on_failure(&block)
+      @failure_hook = block
+    end
+    alias_method :on_open, :on_failure
+
+    private
+
+    # Dispatch message to the current circuit
+    #
+    # @api private
+    def dispatch(*args)
+      result = timeout(control.call_timeout) do
+        @circuit.value.call(*args)
+      end
+      control.record_success
+      result
+    end
+  end # CircuitBreaker
+end # Supervision

data/lib/supervision/circuit_control.rb

@@ -0,0 +1,182 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for controling state of the circuit
+  class CircuitControl
+    extend Forwardable
+
+    def_delegators :@config, :max_failures, :call_timeout, :failure_count
+
+    attr_reader :config
+
+    MAX_THREAD_LIFETIME = 5
+
+    # Create a circuit control
+    #
+    # @param [Hash] options
+    #
+    # @api public
+    def initialize(options = {})
+      @config            = Configuration.new(options)
+      @failure_count     = Atomic.new(0)
+      @last_failure_time = Atomic.new
+      @lock              = Mutex.new
+      fsm
+    end
+
+    # Creates internal finite state machine to
+    # transitions through three states :closed,
+    # :open and :half_open.
+    #
+    # @return [FiniteMachine]
+    #
+    # @api private
+    def fsm
+      context = self
+      @fsm ||= FiniteMachine.define do
+        initial :closed
+
+        target context
+
+        events {
+          event :trip,         [:closed, :half_open] => :open
+          event :attempt_reset, :open => :half_open
+          event :reset,         :half_open => :closed
+        }
+
+        callbacks {
+          on_enter :closed do |event|
+            reset_failure
+          end
+
+          on_enter :open do |event|
+            measure_timeout
+            fail_fast!
+          end
+
+          on_enter :half_open do |event|
+          end
+        }
+      end
+    end
+
+    def_delegators :@fsm, :trip, :attempt_reset, :reset, :current
+
+    # Total failure count for current circuit
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def failure_count
+      @failure_count.value
+    end
+
+    # Last time failure occured
+    #
+    # @return [Time]
+    #
+    # @api public
+    def last_failure_time
+      @last_failure_time.value
+    end
+
+    # Fail fast on any call
+    #
+    # @raise [CircuitBreakerOpenError]
+    #
+    # @api private
+    def fail_fast!
+      # monitor.record_open
+      raise CircuitBreakerOpenError
+    end
+
+    # @return [Boolean]
+    #
+    # @api private
+    def failure_count_exceeded?
+      failure_count > @config.max_failures
+    end
+
+    # @return [Boolean]
+    #
+    # @api private
+    def tripped?
+      fsm.open? && timeout_exceeded?
+    end
+
+    # Check if remaining duration until reset has been exceeded
+    #
+    # @return [Boolean]
+    #   whether or not the breaker will attempt a reset by transitioning
+    #   to :half_open state
+    #
+    # @api private
+    def timeout_exceeded?
+      return false unless last_failure_time
+      timeout = Time.now - last_failure_time
+      timeout > @config.reset_timeout
+    end
+
+    # Handler exception
+    #
+    # @api public
+    def handle(error = nil)
+      fail_fast! if fsm.open?
+      record_failure
+      trip if failure_count_exceeded? || fsm.half_open?
+    end
+
+    def record_success
+      reset if fsm.half_open?
+      reset_failure
+    end
+
+    # Records failure count
+    #
+    # @api public
+    def record_failure
+      if fsm.closed? || fsm.half_open?
+        @failure_count.update { |v| v + 1 }
+        @last_failure_time.value = Time.now
+      end
+    end
+
+    # Resets failure count
+    #
+    # @api public
+    def reset_failure
+      @failure_count.value = 0
+      @last_failure_time.value = nil
+    end
+
+    # Measure remaining timeout
+    #
+    # @api private
+    def measure_timeout
+      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
+          end
+        end
+      end
+    end
+
+    # Estimate maximum duration the scheduling thread should live
+    #
+    # @return [Time]
+    #
+    # @api private
+    def max_thread_lifetime
+      @config.reset_timeout + 100.milli
+    end
+  end # CircuitControl
+end # Supervision

data/lib/supervision/circuit_monitor.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for recording circuit performance
+  class CircuitMonitor
+
+    def initialize
+    end
+
+    def alert(type)
+    end
+  end
+end # Supervision

data/lib/supervision/circuit_system.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for registering circuits
+  class CircuitSystem
+    extend Forwardable
+
+    def_delegators '@registry', :[], :get, :[]=, :set,
+                   :register, :delete, :unregister
+
+    def initialize
+      @registry = Registry.new
+    end
+
+  end # CircuitSystem
+end # Supervision

data/lib/supervision/configuration.rb

@@ -0,0 +1,73 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsbile for the circuit configuration options
+  class Configuration
+    DEFAULT_MAX_FAILURES = 5
+
+    DEFAULT_CALL_TIMEOUT = 10.milli
+
+    DEFAULT_RESET_TIMEOUT = 100.milli
+
+    # Create a Configuration options
+    #
+    # @api public
+    def initialize(options = {})
+      verify_options!(options)
+      @max_failures = Atomic.new(options.fetch(:max_failures,
+                                               DEFAULT_MAX_FAILURES))
+      @call_timeout = Atomic.new(options.fetch(:call_timeout,
+                                               DEFAULT_CALL_TIMEOUT))
+      @reset_timeout = Atomic.new(options.fetch(:reset_timeout,
+                                                DEFAULT_RESET_TIMEOUT))
+    end
+
+    def max_failures=(value)
+      @max_failures.set(value)
+    end
+
+    def max_failures(number = nil)
+      return @max_failures.value unless number
+
+      self.max_failures = number
+    end
+
+    def call_timeout=(value)
+      @call_timeout.set(value)
+    end
+
+    def call_timeout(time = nil)
+      return @call_timeout.value unless time
+
+      self.call_timeout = time
+    end
+
+    def reset_timeout=(value)
+      @reset_timeout.set(value)
+    end
+
+    def reset_timeout(time = nil)
+      return @reset_timeout.value unless time
+
+      self.reset_timeout = time
+    end
+
+    private
+
+    def known_options
+      [:max_failures, :call_timeout, :reset_timeout]
+    end
+
+    def verify_options!(options)
+      options.keys.each do |key|
+        raise_unknown_config_option(key) unless known_options.include?(key)
+      end
+    end
+
+    # TODO: replace with custom error
+    def raise_unknown_config_option(option)
+      raise ArgumentError, "`#{option}` isn`t recognized as valid parameter." \
+            " Please use one of `#{known_options.join(', ')}`"
+    end
+  end # Configuration
+end # Supervision

data/lib/supervision/factory.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for creating circuits
+  class Factory
+  end
+end