supervision 0.1.0

data/lib/supervision/registry.rb

@@ -0,0 +1,69 @@
+# encoding: utf-8
+
+module Supervision
+  # A class responsible for registering/unregistering circuits
+  class Registry
+
+    # Initialize a Registry
+    #
+    # @api public
+    def initialize
+      @lock = Mutex.new
+      @map = {}
+    end
+
+    # Register a circuit
+    #
+    # @api public
+    def []=(name, circuit)
+      unless circuit.is_a?(CircuitBreaker)
+        raise TypeError, 'not a circuit'
+      end
+      @lock.synchronize do
+        @map[name.to_sym] = circuit
+      end
+    end
+
+    # Retrieve a circuit by name
+    #
+    # @api public
+    def [](name)
+      @lock.synchronize do
+        @map[name.to_sym]
+      end
+    end
+
+    # Remove from registry
+    #
+    # @api public
+    def delete(name)
+      @lock.synchronize do
+        @map.delete name.to_sym
+      end
+    end
+
+    alias_method :register,   :[]=
+    alias_method :get,        :[]
+    alias_method :unregister, :delete
+
+    # Check if circuit is in registry
+    #
+    # @api public
+    def registered?(name)
+      names.include?(name)
+    end
+
+    def names
+      @lock.synchronize { @map.keys }
+    end
+
+    def clear
+      hash = nil
+      @lock.synchronize do
+        hash = @map.dup
+        @map.clear
+      end
+      hash
+    end
+  end # Registry
+end # Supervision

data/lib/supervision/time_dsl.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+module Supervision
+  # A mixin to define time related helpers
+  module TimeDSL
+    def millisecond
+      self / 1000.0
+    end
+    alias_method :milliseconds, :millisecond
+    alias_method :milli       , :millisecond
+    alias_method :millis      , :millisecond
+
+    def second
+      self * 1
+    end
+    alias_method :seconds, :second
+    alias_method :sec    , :second
+    alias_method :secs   , :second
+
+    def minute
+      self * 60
+    end
+    alias_method :minutes, :minute
+    alias_method :min    , :minute
+    alias_method :mins   , :minute
+
+    def hour
+      self * 3600
+    end
+    alias_method :hours, :hour
+  end # TimeDSL
+end # Supervision
+
+unless Numeric.method_defined?(:second)
+  Numeric.send(:include, Supervision::TimeDSL)
+end

data/lib/supervision/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Supervision
+  VERSION = "0.1.0"
+end

data/lib/supervision.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+
+require "thread"
+require "timeout"
+require "finite_machine"
+
+require "supervision/version"
+require "supervision/atomic"
+require "supervision/time_dsl"
+require "supervision/configuration"
+require "supervision/registry"
+require "supervision/circuit_control"
+require "supervision/circuit_breaker"
+require "supervision/circuit_system"
+require "supervision/circuit_monitor"
+
+module Supervision
+  # Generic error
+  SupervisionError = Class.new(::StandardError)
+
+  # Raised when circuit opens
+  CircuitBreakerOpenError = Class.new(SupervisionError)
+
+  TypeError = Class.new(SupervisionError)
+
+  class << self
+    def included(base)
+      base.send :extend, ClassMethods
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def init
+      @circuit_system = CircuitSystem.new
+    end
+
+    def circuit_system
+      Thread.current[:supervision_circuit_system] ||= @circuit_system
+    end
+
+    # Create a new circuit breaker
+    #
+    # @api public
+    def new(name = nil, options = {}, &block)
+      name ? supervise_as(name, options, &block) : supervise(options, &block)
+    end
+  end
+
+  module ClassMethods
+    def supervise(options = {}, &block)
+      CircuitBreaker.new(options, &block)
+    end
+
+    def supervise_as(name, options = {}, &block)
+      circuit = supervise(options, &block)
+      Supervision.circuit_system[name] = circuit
+      send(:define_method, name) { |*args| circuit.call(args) }
+      circuit
+    end
+  end
+
+  extend ClassMethods
+end # Supervision
+
+Supervision.init

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+require 'supervision'
+require 'timeout'
+
+module Helpers
+  def wait_for(duration = nil)
+    Timeout.timeout 1 do
+      sleep(duration || 0.01) until yield
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.order = 'random'
+  config.include Helpers
+end

data/spec/unit/atomic_spec.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Supervision::Atomic do
+
+  let(:object) { described_class }
+
+  it "sets the value to nil" do
+    atomic = object.new
+    expect(atomic.value).to eql(nil)
+  end
+
+  it "sets the value" do
+    atomic = object.new(1)
+    expect(atomic.value).to eql(1)
+  end
+
+  it "set value" do
+    atomic = object.new
+    atomic.value = 1000
+    expect(atomic.value).to eql(1000)
+  end
+
+  it "updates current value" do
+    atomic = object.new(1000)
+    new_value = atomic.update { |v| v + 1 }
+    expect(new_value).to eql(1001)
+  end
+end

data/spec/unit/circuit_breaker_spec.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Supervision::CircuitBreaker do
+
+  let(:dangerous_call_timeout) { sleep 1 }
+
+  let(:dangerous_call_error) { raise StandardError }
+
+  let(:safe_call) { 'value' }
+
+  let(:object) { described_class }
+
+
+  context 'when closed' do
+    it "successfully calls the method" do
+      circuit = object.new call_timeout: 1.milli do |arg|
+        arg == :danger ? dangerouse_call_error : safe_call
+      end
+      expect(circuit.call(:safe)).to eql(safe_call)
+    end
+
+    it "increments a failure counter for exceptions" do
+      circuit = object.new call_timeout: 1.milli do
+        arg == :danger ? dangerouse_call_error : safe_call
+      end
+      circuit.call(:danger)
+      expect(circuit.control.failure_count).to eql(1)
+    end
+
+    it "increments a failure counter for calls exceeding :call_timeout" do
+      circuit = object.new call_timeout: 1.milli do
+        dangerous_call_timeout
+      end
+      circuit.call
+      expect(circuit.control.failure_count).to eql(1)
+    end
+  end
+
+  context 'when open' do
+    it "fails all calls with a CircuitBreakerOpenError" do
+      circuit = object.new max_failures: 2, reset_timeout: 1.sec do
+        dangerous_call_error
+      end
+      circuit.call
+      circuit.call
+      expect { circuit.call }.to raise_error(Supervision::CircuitBreakerOpenError)
+    end
+
+    it "enters a :half_open state after the :reset_timeout" do
+      circuit = object.new reset_timeout: 0.1.sec, max_failures: 0 do
+        dangerous_call_error
+      end
+      expect { circuit.call }.to raise_error(Supervision::CircuitBreakerOpenError)
+      expect(circuit.control.current).to eq(:open)
+      sleep 0.2
+      expect(circuit.control.current).to eq(:half_open)
+    end
+  end
+
+  context 'when half open' do
+    it "resets the breaker back to :closed state on successful call" do
+      circuit = object.new reset_timeout: 100.milli, max_failures: 0 do |arg|
+        arg == :danger ? dangerous_call_error : safe_call
+      end
+      expect {
+        circuit.call(:danger)
+      }.to raise_error(Supervision::CircuitBreakerOpenError)
+      expect(circuit.control.current).to eql(:open)
+      sleep 0.2
+      expect(circuit.control.current).to eql(:half_open)
+      circuit.call(:safe)
+      expect(circuit.control.current).to eql(:closed)
+    end
+  end
+
+  context 'when with callback' do
+    it "notifies about successful call" do
+      callbacks = []
+      circuit = object.new do safe_call end
+      circuit.on_success { callbacks << 'on_success' }
+      circuit.call
+      expect(callbacks).to eql(["on_success"])
+    end
+
+    it "notifies about failed call" do
+      callbacks = []
+      circuit = object.new do dangerous_call_error end
+      circuit.on_failure { callbacks << 'on_failure'}
+      circuit.before { callbacks << 'before'}
+      circuit.call
+      expect(callbacks).to eql(['before', 'on_failure'])
+    end
+  end
+
+  it "fails fast with unknown config option" do
+    expect {
+      object.new max_fail: 2 do safe_call end
+    }.to raise_error(ArgumentError)
+  end
+end

data/spec/unit/circuit_control_spec.rb

@@ -0,0 +1,72 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Supervision::CircuitControl do
+  let(:object) { described_class }
+
+  let(:max_failures) { 1 }
+
+  let(:reset_timeout) { 0.1.sec }
+
+  subject(:control) {
+    object.new max_failures: max_failures,
+               reset_timeout: reset_timeout
+  }
+
+  context 'when closed' do
+    it "resets the failure count on success" do
+      expect(control.failure_count).to eql(0)
+      expect(control.fsm.current).to eql(:closed)
+      control.record_failure
+      expect(control.failure_count).to eql(1)
+      control.reset_failure
+      expect(control.failure_count).to eql(0)
+      expect(control.fsm.current).to eql(:closed)
+    end
+
+    it "increments failure count on exceptions and trips the wire" do
+      expect(control.failure_count).to eql(0)
+      expect(control.fsm.current).to eql(:closed)
+
+      control.handle
+      expect(control.failure_count).to eql(1)
+      expect(control.fsm.current).to eql(:closed)
+
+      expect{ control.handle }.to raise_error(Supervision::CircuitBreakerOpenError)
+      expect(control.failure_count).to eql(2)
+      expect(control.fsm.current).to eql(:open)
+    end
+  end
+
+  context 'when open' do
+    it "fails all calls fast with CircuitBreakerOpenError" do
+      control.fsm.state = :open
+      expect { control.handle }.to raise_error(Supervision::CircuitBreakerOpenError)
+      expect(control.fsm.current).to eql(:open)
+    end
+
+    it "enters :half_open state after the configured :reset_timeout" do
+      control.record_failure
+      expect{ control.handle }.to raise_error(Supervision::CircuitBreakerOpenError)
+      sleep 0.2
+      expect(control.fsm.current).to eql(:half_open)
+    end
+  end
+
+  context 'when half open' do
+    before { control.fsm.state = :half_open }
+
+    it "resets the breaker back to :closed state on successful call" do
+      control.record_success
+      expect(control.fsm.current).to eql(:closed)
+      expect(control.failure_count).to eql(0)
+    end
+
+    it "trips the breaker back to :open state on failed call" do
+      expect { control.handle }.to raise_error(Supervision::CircuitBreakerOpenError)
+      expect(control.failure_count).to eql(1)
+      expect(control.fsm.current).to eql(:open)
+    end
+  end
+end

data/spec/unit/circuit_monitor_spec.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+require "spec_helper"
+
+describe Supervision::CircuitMonitor do
+end

data/spec/unit/configuration_spec.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Supervision::Configuration do
+
+  subject(:config) { described_class.new }
+
+  it { expect(config.max_failures).to eql(5) }
+
+  it { expect(config.call_timeout).to eql(0.01) }
+
+  it { expect(config.reset_timeout).to eql(0.1) }
+end

data/spec/unit/initialize_spec.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Supervision do
+
+  context "when used as instance" do
+    it "permits options configuration" do
+      supervision = Supervision.new { }
+      supervision.configure do
+        call_timeout 1.sec
+        max_failures 10
+      end
+      expect(supervision.control.max_failures).to eql(10)
+      expect(supervision.control.call_timeout).to eql(1.sec)
+    end
+
+    it "allows to supervise call" do
+      called = []
+      supervision = Supervision.supervise { called << 'method_call'}
+      supervision.call
+      expect(called).to eql(['method_call'])
+    end
+
+    it "registers named supervision" do
+      called = []
+      supervision = Supervision.supervise_as(:danger) { called << 'method_call'}
+      supervision.call
+      expect(called).to eql(['method_call'])
+      expect(Supervision.circuit_system[:danger]).to eql(supervision)
+    end
+  end
+
+  context "when included as module" do
+    class RemoteApi
+      include Supervision
+
+      def danger_call(state)
+        state == :safe ? "hello" : raise(StandardError)
+      end
+      supervise_as(:danger, max_failures: 2) { |args| danger_call(args) }
+
+      def wrapped_danger
+        supervise { |args| danger_call(args) }
+      end
+    end
+
+    it "allows to call registerd circuit" do
+      api = RemoteApi.new
+      api.danger
+      api.danger
+      expect { api.danger }.to raise_error(Supervision::CircuitBreakerOpenError)
+    end
+  end
+end # Supervision

data/spec/unit/registry_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+describe Supervision::Registry do
+
+  let(:circuit) { Supervision.supervise { } }
+
+  subject(:registry) { described_class.new }
+
+  it "registers" do
+    registry[:danger] = circuit
+    expect(registry[:danger]).to eql(circuit)
+  end
+
+  it "refuses to add non circuit object" do
+    expect {
+      registry[:danger] = Object.new
+    }.to raise_error(Supervision::TypeError)
+  end
+
+  it "" do
+    registry[:danger] = circuit
+    expect(registry.names).to eql([:danger])
+  end
+
+  it "" do
+    registry[:danger] = circuit
+    registry.delete(:danger)
+    expect(registry.names).to be_empty
+  end
+end

data/spec/unit/time_dsl_spec.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Supervision::TimeDSL do
+  it "defines millisecond/milliseconds/milli/millis" do
+    expect(1.millisecond).to eql(0.001)
+    expect(1.milli).to eql(0.001)
+    expect(10.milliseconds).to eql(0.01)
+    expect(10.millis).to eql(0.01)
+  end
+
+  it "defines second/seconds" do
+    expect(1.second).to eql(1)
+    expect(10.seconds).to eql(10)
+    expect(1.sec).to eql(1)
+    expect(10.secs).to eql(10)
+  end
+
+  it "defines minute/minutes" do
+    expect(1.minute).to eql(60)
+    expect(10.minutes).to eql(600)
+    expect(1.min).to eql(60)
+    expect(10.mins).to eql(600)
+  end
+
+  it "defines hours/hours" do
+    expect(1.hour).to eql(3600)
+    expect(2.hours).to eql(7200)
+  end
+end

data/supervision.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'supervision/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "supervision"
+  spec.version       = Supervision::VERSION
+  spec.authors       = ["Piotr Murach"]
+  spec.email         = [""]
+  spec.summary       = %q{Write distributed systems that are resilient and self-heal.}
+  spec.description   = %q{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.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "finite_machine", "~> 0.4"
+  spec.add_development_dependency "bundler", "~> 1.6"
+end

data/tasks/console.rake

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+desc 'Load gem inside irb console'
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require File.join(__FILE__, '../lib/finite_machine')
+  ARGV.clear
+  IRB.start
+end

data/tasks/coverage.rake

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+desc 'Measure code coverage'
+task :coverage do
+  begin
+    original, ENV['COVERAGE'] = ENV['COVERAGE'], 'true'
+    Rake::Task['spec'].invoke
+  ensure
+    ENV['COVERAGE'] = original
+  end
+end

data/tasks/spec.rake

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc 'Run all specs'
+  RSpec::Core::RakeTask.new(:spec) do |task|
+    task.pattern = 'spec/{unit,integration}{,/*/**}/*_spec.rb'
+  end
+
+  namespace :spec do
+    desc 'Run unit specs'
+    RSpec::Core::RakeTask.new(:unit) do |task|
+      task.pattern = 'spec/unit{,/*/**}/*_spec.rb'
+    end
+
+    desc 'Run integration specs'
+    RSpec::Core::RakeTask.new(:integration) do |task|
+      task.pattern = 'spec/integration{,/*/**}/*_spec.rb'
+    end
+  end
+
+rescue LoadError
+  %w[spec spec:unit spec:integration].each do |name|
+    task name do
+      $stderr.puts "In order to run #{name}, do `gem install rspec`"
+    end
+  end
+end