simple_circuit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9d409438d122cfbfc81797059de659d2ad6a1d6a3f637d1cefa6cc23b44e2af5
+  data.tar.gz: 6b5b02f2b429b7f28fc4c622138b20cdab1f76e5e5a433c9595d228fc4b3cd38
+SHA512:
+  metadata.gz: a97e9e8635d643f2bbb41016601dd68e57ffaa9bb9ceb4def2412250fcafdfc1cab021dcb444e9d50ef6f7c521ca6586523dcd02c2dd7cf4681b24febb9f63e6
+  data.tar.gz: eeac0d15c1a5206d0392515e97d20aab7c1d7febb9a3106bde7343e29aa955652186b5929bea0574f9021af1db05a9103d118d5dca4370a13ac635751da68a00

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.15.4

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in circuit.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Ilya Vassilevsky
+
+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,101 @@
+# SimpleCircuit
+
+A simple implementation of [Circuit Breaker](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) pattern.
+
+Use it when you make calls to an unreliable service. It will not make the service reliable, but it will **fail fast** when the service is down, to prevent overload in your app.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'simple_circuit' # Circuit breaker to fail fast on external service outages
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install simple_circuit
+
+## Usage
+
+Suppose you have calls to unreliable services like these:
+
+```ruby
+client = UnreliableServiceClient.new(url: "https://api.example.io")
+client.get_some_info # => "foo bar"
+```
+
+When they go down or unresponsive, your app starts to slow down too. Queues filling up, etc.
+
+If you'd rather have the calls fail fast, and handle failures fast, use it through a circuit:
+
+```ruby
+client = UnreliableServiceClient.new(url: "https://api.example.io")
+circuit = SimpleCircuit.new(payload: client)
+circuit.pass(:get_some_info) # => "foo bar"
+```
+
+You're passing the same message (`get_some_info`) to `client` object, but now it goes through a circuit.
+It works exactly the same while the circuit is closed (there are no problems in the payload).
+
+Interesting things begin when `client` starts throwing errors.
+
+The first few errors (100 by default) are returned as is:
+
+```ruby
+circuit.pass(:get_some_info) # => HTTP::TimeoutError
+```
+
+This is still slow because it's the `client` object still working as usual.
+
+But after 100 errors, the circuit **breaks**.
+The payload is disconnected from the circuit.
+It no longer receives the `get_some_info` message.
+Instead, the circuit itself immediately throws the error.
+So, each call will fail fast.
+This will prevent overload in your app while the service is down.
+This will also reduce the load on the service and hopefully allow it to recover faster.
+
+The circuit will keep trying to connect the payload back and send the message through it, at regular intervals (by default, every minute).
+When it succeeds, it will become closed again and will rely _all_ messages to the payload, just like in the beginning.
+
+### Customization
+
+You can customize several parameters of circuits. The defaults are show below:
+
+```ruby
+circuit = SimpleCircuit.new(payload: client, max_failures: 100, retry_in: 60, logger: nil)
+```
+
+The parameters are:
+
+* `max_failures` — How many exceptions from the payload should be ignored (returned as is) before the circuit breaks and starts to fail fast.
+* `retry_in` — How many seconds should pass before every retry to connect the payload (to send the original message) when the circuit is open (broken).
+* `logger` — An object that responds to `warn(message)`. It will be called each time the circuit is broken.
+
+### Error Counting
+
+The circuit counts exceptions coming from the payload **by class** and breaks only if **a particular class** of exceptions is received too many times.
+It fails fast with the most occurred exception.
+
+For example, if the payload occasionally throws `MultiJson::ParseError` and then starts throwing `HTTP::TimeoutError` on a regular basis, then the counter of `HTTP::TimeoutError` will reach the maximum first, and the circuit will fast-throw `HTTP::TimeoutError` after breaking.
+
+It might be non-ideal. I welcome suggestions via issues or pull requests.
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies. Then, run `bundle exec rake` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `lib/circuit.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/vassilevsky/circuit.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/simple_circuit.rb

@@ -0,0 +1,57 @@
+class SimpleCircuit
+  VERSION = "0.1.0"
+
+  def initialize(payload:, max_failures: 100, retry_in: 60, logger: nil)
+    @payload      = payload
+    @max_failures = max_failures
+    @retry_in     = retry_in
+    @logger       = logger
+
+    @mutex = Mutex.new
+
+    close
+  end
+
+  def pass(message, *args)
+    fail @e if open? && !time_to_retry?
+    result = payload.public_send(message, *args)
+    close if open?
+    result
+  rescue => e
+    raise e if open?
+    @e = e
+    @mutex.synchronize{ @failures[e.class] += 1 }
+    break! if @failures[e.class] > max_failures
+    raise e
+  end
+
+  def open?
+    !closed?
+  end
+
+  def closed?
+    @closed
+  end
+
+  private
+
+  attr_reader :payload
+  attr_reader :max_failures
+  attr_reader :retry_in
+  attr_reader :logger
+
+  def break!
+    @closed = false
+    @broken_at = Time.now
+    logger&.warn('#{self} has been broken')
+  end
+
+  def close
+    @closed = true
+    @failures = Hash.new(0)
+  end
+
+  def time_to_retry?
+    @broken_at + retry_in < Time.now
+  end
+end

data/simple_circuit.gemspec

@@ -0,0 +1,21 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "simple_circuit"
+
+Gem::Specification.new do |spec|
+  spec.name          = "simple_circuit"
+  spec.version       = SimpleCircuit::VERSION
+  spec.authors       = ["Ilya Vassilevsky"]
+  spec.email         = ["vassilevsky@gmail.com"]
+
+  spec.summary       = "Allows a service to fail fast to prevent overload"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/spec/simple_circuit_spec.rb

@@ -0,0 +1,118 @@
+require "spec_helper"
+
+RSpec.describe SimpleCircuit do
+  it "has a version number" do
+    expect(SimpleCircuit::VERSION).not_to be nil
+  end
+
+  context 'happy path' do
+    let(:foo){ Class.new{ def bar(baz); baz; end }.new }
+
+    it 'passes through a message and returns the result' do
+      expect(foo).to receive(:bar).with(:baz).and_call_original
+      expect(SimpleCircuit.new(payload: foo).pass(:bar, :baz)).to eq(:baz)
+    end
+  end
+
+  context 'when method call fails' do
+    class BarError < RuntimeError; end
+
+    let(:foo){ Class.new{ def bar; fail BarError; end }.new }
+    let(:circuit){ SimpleCircuit.new(payload: foo) }
+
+    it 'counts the error and lets it raise' do
+      expect{circuit.pass(:bar)}.to raise_error(BarError)
+    end
+
+    context 'when circuit has too many errors' do
+      let(:circuit){ SimpleCircuit.new(payload: foo, max_failures: 1) }
+
+      it 'breaks the circuit - does not call the payload anymore, fails immediately' do
+        expect(circuit).to be_closed
+        expect{circuit.pass(:bar)}.to raise_error(BarError)
+        expect(circuit).to be_closed
+        expect(foo).to receive(:bar).and_call_original
+        expect{circuit.pass(:bar)}.to raise_error(BarError)
+        expect(circuit).not_to be_closed
+        expect(circuit).to be_open
+        expect(foo).not_to receive(:bar)
+        expect{circuit.pass(:bar)}.to raise_error(BarError)
+      end
+
+      context 'testing circuit via logger' do
+        let(:logger){ double(:logger, warn: true) }
+        let(:circuit){ SimpleCircuit.new(payload: foo, max_failures: 1, logger: logger) }
+
+        it 'does not break again' do
+          expect{circuit.pass(:bar)}.to raise_error(BarError)
+          expect(logger).to receive(:warn) do |message|
+            expect(message).to include('broken')
+          end
+          expect{circuit.pass(:bar)}.to raise_error(BarError)
+          expect(logger).not_to receive(:warn)
+          expect{circuit.pass(:bar)}.to raise_error(BarError)
+        end
+      end
+
+      context 'when the next call is successful again' do
+        let(:foo) do
+          Class.new do
+            def initialize
+              @messages = 0
+            end
+
+            def bar
+              @messages += 1
+
+              if @messages < 3
+                fail BarError
+              else
+                :baz
+              end
+            end
+          end.new
+        end
+
+        let(:circuit){ SimpleCircuit.new(payload: foo, max_failures: 1, retry_in: 1) }
+
+        it 'closes back the circuit' do
+          expect{circuit.pass(:bar)}.to raise_error(BarError)
+          expect{circuit.pass(:bar)}.to raise_error(BarError)
+          expect(circuit).to be_open
+          expect{circuit.pass(:bar)}.to raise_error(BarError)
+          sleep 1
+          expect(circuit.pass(:bar)).to eq(:baz)
+          expect(circuit).to be_closed
+        end
+      end
+
+      context 'when payload raises different errors' do
+        class Error1 < RuntimeError; end
+        class Error2 < RuntimeError; end
+
+        let(:foo) do
+          Class.new do
+            def initialize
+              @errors = [Error1, Error2, Error1]
+            end
+
+            def bar
+              fail @errors.shift
+            end
+          end.new
+        end
+
+        let(:circuit){ SimpleCircuit.new(payload: foo, max_failures: 1) }
+
+        it 'fails with top error after break' do
+          expect{circuit.pass(:bar)}.to raise_error(Error1)
+          expect{circuit.pass(:bar)}.to raise_error(Error2)
+          expect(circuit).to be_closed
+          expect{circuit.pass(:bar)}.to raise_error(Error1)
+          expect(circuit).to be_open
+          expect{circuit.pass(:bar)}.to raise_error(Error1)
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require "bundler/setup"
+require "simple_circuit"
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: simple_circuit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ilya Vassilevsky
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- vassilevsky@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/simple_circuit.rb
+- simple_circuit.gemspec
+- spec/simple_circuit_spec.rb
+- spec/spec_helper.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Allows a service to fail fast to prevent overload
+test_files: []