knifeswitch 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8fce0afa125f824b748eae256d752487d221343c5ca839613f2fe8547288f893
+  data.tar.gz: 8f6bfb756e1dd154449178873c459cdba208b70a3c8290329cb1d29f7da44e46
+SHA512:
+  metadata.gz: c87ebd2d6d76d1ed34e83c7fb582cd6ada8e1c7cfd5fea4fb0f70ba3a0d856f2c1d3caf434ed7a59251d7ae3d898bd7b8b0b59fed9f6845fc7a060c72119b3cf
+  data.tar.gz: 3b8cc2c3b87092340af8530003dc754d3fdf410cad2a26944a4d5575cb1bebe2b9385a25a97892ddfedb2cc49484080868444e10d782f21c9049b32d7314c6b8

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 Nigel Baillie
+
+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,70 @@
+# Knifeswitch
+Yet another circuit breaker gem. This one strives to be as small and simple as possible. In the effort to remain simple, it currently only supports Rails with MySQL.
+
+## Usage
+```ruby
+# Instantiate circuit
+circuit = Knifeswitch::Circuit.new(
+  namespace:       'whatever',
+  exceptions:      [TimeoutExceptionToCatch, Timeout::Error],
+  error_threshold: 5,
+  error_timeout:   60
+)
+
+response = circuit.run { client.request(...) }
+# 'run' will raise Knifeswitch::CircuitOpen if its error_threshold has
+# been exceeded. In this case: when a timeout occurs 5 times in a row.
+# 
+# The error threshold counter is shared among all Knifeswitch::Circuit
+# instances with the same namespace. The counters are stored in the db,
+# so the state is fully distributed among all your workers/webservers.
+#
+# After the circuit opens, it will close back down after 60 seconds of
+# rejecting requests (by raising Knifeswitch::CircuitOpen).
+#
+# When closed, it will just run the block like normal and return the result.
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'knifeswitch'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Finally, generate migrations:
+```bash
+$ rake knifeswitch:create_migrations
+```
+
+## Testing
+
+### Have Docker installed?
+``` bash
+$ bin/dockertest
+```
+
+### Manually, without docker
+You'll need to set up the test Rails app's database. Edit `test/dummy/config/database.yml` as you see fit, and run:
+
+```bash
+$ rake knifeswitch:create_migrations db:create db:migrate
+```
+inside of the `test/dummy` directory.
+
+After that you can run:
+```bash
+$ bin/test
+```
+in the project root with no problem. If you end up changing the migration generation rake task, you'll have to clean up and re-run it manually.
+
+## Limitations
+
+To keep the gem simple, Knifeswitch depends on [Rails](https://github.com/rails/rails). Technically, it should be pretty simple to make Knifeswitch work without the Rails dependency, but for us since we use Rails it's easier to just keep it as is.
+
+Knifeswitch also softly depends on MySQL, in that it uses MySQL's `ON DUPLICATE KEY UPDATE` syntax.

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Fusebox'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/lib/knifeswitch/circuit.rb

@@ -0,0 +1,132 @@
+module Knifeswitch
+  # Implements the "circuit breaker" pattern using a simple MySQL table.
+  #
+  # Example usage:
+  #
+  #   circuit = Knifeswitch::Circuit.new(
+  #     namespace:       'some third-party',
+  #     exceptions:      [Example::TimeoutError],
+  #     error_threshold: 5,
+  #     error_timeout:   30
+  #   )
+  #   response = circuit.run { client.request(...) }
+  #
+  # In this example, when a TimeoutError is raised within a circuit.run
+  # block 5 times in a row, the circuit will "open" and further calls to
+  # circuit.run will raise Knifeswitch::CircuitOpen instead of executing the
+  # block. After 30 seconds, the circuit "closes" and circuit.run blocks
+  # will be run again.
+  #
+  # Two circuits with the same namespace share the same counter and
+  # open/closed state, as long as they're connected to the same database.
+  #
+  class Circuit
+    attr_reader :namespace, :exceptions, :error_threshold, :error_timeout
+
+    # Options:
+    #
+    # namespace:       circuits in the same namespace share state
+    # exceptions:      an array of error types that bump the counter
+    # error_threshold: number of errors required to open the circuit
+    # error_timeout:   seconds to keep the circuit open
+    def initialize(
+      namespace: 'default',
+      exceptions: [Timeout::Error],
+      error_threshold: 10,
+      error_timeout: 60
+    )
+      @namespace       = namespace
+      @exceptions      = exceptions
+      @error_threshold = error_threshold
+      @error_timeout   = error_timeout
+    end
+
+    # Call this with a block to execute the contents of the block under
+    # circuit breaker protection.
+    #
+    # Raises Knifeswitch::CircuitOpen when called while the circuit is open.
+    def run
+      raise CircuitOpen if open?
+
+      result = yield
+      reset_counter!
+      result
+    rescue Exception => error
+      if exceptions.any? { |watched| error.is_a?(watched) }
+        increment_counter!
+      else
+        reset_counter!
+      end
+
+      raise error
+    end
+
+    # Queries the database to see if the circuit is open.
+    #
+    # The circuit opens when 'error_threshold' errors occur consecutively.
+    # When the circuit is open, calls to `run` will raise CircuitOpen
+    # instead of yielding.
+    def open?
+      result = sql(:select_value, %(
+        SELECT COUNT(*) c FROM knifeswitch_counters
+        WHERE name = ? AND closetime > ?
+      ), namespace, DateTime.now)
+
+      result > 0
+    end
+
+    # Retrieves the current counter value.
+    def counter
+      result = sql(:select_value, %(
+        SELECT counter FROM knifeswitch_counters
+        WHERE name = ?
+      ), namespace)
+
+      result || 0
+    end
+
+    # Increments counter and opens the circuit if it went
+    # too high
+    def increment_counter!
+      # Increment the counter
+      sql(:execute, %(
+        INSERT INTO knifeswitch_counters (name,counter)
+        VALUES (?, 1)
+        ON DUPLICATE KEY UPDATE counter=counter+1
+      ), namespace)
+
+      # Possibly open the circuit
+      sql(
+        :execute,
+        %(
+          UPDATE knifeswitch_counters
+          SET closetime = ?
+          WHERE name = ? AND COUNTER >= ?
+        ),
+        DateTime.now + error_timeout.seconds,
+        namespace, error_threshold
+      )
+    end
+
+    # Sets the counter to zero
+    def reset_counter!
+      sql(:execute, %(
+        INSERT INTO knifeswitch_counters (name,counter)
+        VALUES (?, 0)
+        ON DUPLICATE KEY UPDATE counter=0
+      ), namespace)
+    end
+
+    private
+
+    # Executes a SQL query with the given Connection method
+    # (i.e. :execute, or :select_values)
+    def sql(method, query, *args)
+      query = ActiveRecord::Base.send(:sanitize_sql_array, [query] + args)
+
+      ActiveRecord::Base.connection_pool.with_connection do |conn|
+        conn.send(method, query)
+      end
+    end
+  end
+end

data/lib/knifeswitch/railtie.rb

@@ -0,0 +1,8 @@
+module Knifeswitch
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      path = File.expand_path("#{__dir__}/..")
+      Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/knifeswitch/version.rb

@@ -0,0 +1,3 @@
+module Knifeswitch
+  VERSION = '1.0.0'
+end

data/lib/knifeswitch.rb

@@ -0,0 +1,7 @@
+require 'knifeswitch/railtie'
+require 'knifeswitch/circuit'
+
+module Knifeswitch
+  class Error < StandardError; end
+  class CircuitOpen < Error; end
+end

data/lib/tasks/knifeswitch_tasks.rake

@@ -0,0 +1,9 @@
+namespace :knifeswitch do
+  desc 'Generate the migrations necessary to use Knifeswitch'
+  task :create_migrations do
+    sh 'rails g migration CreateKnifeswitchCounters ' \
+       'name:string:uniq counter:integer closetime:datetime'
+
+    puts "Done. Don't forget to run `rake db:migrate`."
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: knifeswitch
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nigel Baillie
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.2.1
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |-
+  Implements the circuit breaker pattern using MySQL as a datastore.
+  https://martinfowler.com/bliki/CircuitBreaker.html
+email:
+- nbaillie@degica.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/knifeswitch.rb
+- lib/knifeswitch/circuit.rb
+- lib/knifeswitch/railtie.rb
+- lib/knifeswitch/version.rb
+- lib/tasks/knifeswitch_tasks.rake
+homepage: https://github.com/degica/knifeswitch
+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: []
+rubygems_version: 3.0.4
+signing_key: 
+specification_version: 4
+summary: Simple implementation of the circuit breaker pattern.
+test_files: []