shift-circuit-breaker 0.2.0

data/lib/shift/circuit_breaker/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Shift
+  module CircuitBreaker
+    VERSION = "0.2.0"
+  end
+end

data/shift-circuit-breaker.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# -*- encoding: utf-8 -*-
+
+$:.push File.expand_path("../lib", __FILE__)
+
+require "shift/circuit_breaker/version"
+
+Gem::Specification.new do |s|
+  s.name        = "shift-circuit-breaker"
+  s.version     = Shift::CircuitBreaker::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.summary     = "A generic implementation of the Circuit Breaker pattern in Ruby"
+  s.description = <<-DOC
+    The library provides a mechanism for detecting, monitoring and controlling external service calls that will
+    most-likely fail at some point (e.g. timeout) and cause request queuing, thus preventing cascading system failures.
+  DOC
+  s.homepage    = "https://github.com/shiftcommerce/shift-circuit-breaker"
+  s.authors     = ["Mufudzi Masaire"]
+  s.email       = "mufudzi.masaire@shiftcommerce.com"
+  s.date        = Time.now.strftime("%Y-%m-%d")
+  s.license     = "MIT"
+
+  s.required_ruby_version = ">= 2.3.0"
+  s.require_paths = ["lib"]
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- { test, spec, features }/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+
+  s.add_runtime_dependency "activesupport", "~> 5.1", ">= 5.1.4"
+  s.add_runtime_dependency "newrelic_rpm", "~> 4.8", ">= 4.8.0.341"
+  s.add_runtime_dependency "sentry-raven", "~> 2.7", ">= 2.7.2"
+
+  s.add_development_dependency "bundler", "~> 1.16"
+  s.add_development_dependency "pry", "~> 0.11.3"
+  s.add_development_dependency "rake", "~> 12.3"
+  s.add_development_dependency "rspec", "~> 3.7"
+  s.add_development_dependency "rubocop", "~> 0.52.1"
+  s.add_development_dependency "timecop", "~> 0.9.1"
+end

data/spec/shift/adapters/base_adapter_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Shift
+  module CircuitBreaker
+    module Adapters
+      describe BaseAdapter do
+        context "#call" do
+          it "raises NotImplementedError" do
+            # Arrange
+            message = "some message"
+
+            # Act & Assert
+            expect { described_class.call(message) }.to raise_error(NotImplementedError)
+          end
+        end
+      end
+    end
+  end
+end

data/spec/shift/adapters/newrelic_adapter_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module NewRelic
+  module Agent
+    def self.increment_metric(*); end
+  end
+end
+
+module Shift
+  module CircuitBreaker
+    module Adapters
+      describe NewRelicAdapter do
+        it "is a subclass of 'Shift::CircuitBreaker::Adapters::BaseAdapter'" do
+          expect(described_class).to be < Shift::CircuitBreaker::Adapters::BaseAdapter
+        end
+
+        context "#call" do
+          it "does not raise NotImplementedError" do
+            # Arrange
+            metric = "Custom/TestCircuitBreaker/closed"
+
+            # Act & Assert
+            expect { described_class.call(metric) }.not_to raise_error(NotImplementedError)
+          end
+
+          it "calls NewRelic::Agent#increment_metric" do
+            # Arrange
+            metric = "Custom/TestCircuitBreaker/closed"
+
+            allow(::NewRelic::Agent).to receive(:increment_metric)
+
+            # Act
+            described_class.call(metric)
+
+            # Assert
+            expect(::NewRelic::Agent).to have_received(:increment_metric).with(metric).once
+          end
+        end
+      end
+    end
+  end
+end

data/spec/shift/adapters/sentry_adapter_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Sentry
+  def self.capture_exception(*); end
+end
+
+module Shift
+  module CircuitBreaker
+    module Adapters
+      describe SentryAdapter do
+        it "is a subclass of 'Shift::CircuitBreaker::Adapters::BaseAdapter'" do
+          expect(described_class).to be < Shift::CircuitBreaker::Adapters::BaseAdapter
+        end
+
+        context "#call" do
+          it "does not raise NotImplementedError" do
+            # Arrange
+            message = "some message"
+
+            # Act & Assert
+            expect { described_class.call(message) }.not_to raise_error(NotImplementedError)
+          end
+
+          it "calls Sentry#capture_exception" do
+            # Arrange
+            message = "some exception"
+
+            allow(::Raven).to receive(:capture_exception)
+
+            # Act
+            described_class.call(message)
+
+            # Assert
+            expect(::Raven).to have_received(:capture_exception).with(message).once
+          end
+        end
+      end
+    end
+  end
+end

data/spec/shift/circuit_breaker/circuit_handler_exception_handling_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Shift
+  module CircuitBreaker
+    describe CircuitHandler do
+      before do
+        allow($stdout).to receive(:write)
+      end
+
+      context "Exception Handling" do
+        let(:default_error_threshold) { 10 }
+        let(:default_skip_duration)   { 60 }
+
+        context "when a timeout exception is raised" do
+          it "returns the fallback" do
+            # Arrange
+            operation_stub  = instance_double("Operation")
+            fallback_stub   = instance_double("Fallback")
+
+            allow(operation_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+
+            # Act
+            cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+            operation_result = cb.call(operation: -> { operation_stub.perform_task }, fallback: -> { fallback_stub })
+
+            # Assert
+            expect(operation_result).to eq(fallback_stub)
+          end
+        end
+
+        context "when the error_threshold is exceeded" do
+          it "opens the curcuit returns the fallback" do
+            # Arrange
+            operation_1_stub = instance_double("Operation1")
+            operation_2_stub = instance_double("Operation2")
+            operation_3_stub = instance_double("Operation3")
+            fallback_stub    = instance_double("Fallback")
+
+            allow(operation_1_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+            allow(operation_2_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+            allow(operation_3_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+
+            # Act & Assert
+            cb = described_class.new(:test_circuit_breaker, error_threshold: 2, skip_duration: default_skip_duration)
+
+            # The first operation will fail with Timeout::Error, resulting in the exception being caught and
+            # the fallback being returned as the operation result. The error_count is incremented to 1.
+            aggregate_failures do
+              expect(operation_1_stub).to receive(:perform_task)
+              operation_1_result = cb.call(operation: -> { operation_1_stub.perform_task }, fallback: -> { fallback_stub })
+              # Check Circuit Breaker state and result
+              expect(cb.state).to eq(:closed)
+              expect(cb.error_count).to eq(1)
+              expect(operation_1_result).to eq(fallback_stub)
+            end
+
+            # The second operation will also fail with Timeout::Error, resulting in the exception being caught and
+            # the fallback being returned as the operation result. The error_count is incremented to 2 and the circuit
+            # is opened.
+            aggregate_failures do
+              expect(operation_2_stub).to receive(:perform_task)
+              operation_2_result = cb.call(operation: -> { operation_2_stub.perform_task }, fallback: -> { fallback_stub })
+              # Check Circuit Breaker state and result
+              expect(cb.state).to eq(:open)
+              expect(cb.error_count).to eq(2)
+              expect(operation_2_result).to eq(fallback_stub)
+            end
+
+            # The third operation will not be run as the circuit is open. This should result in #call not being executed
+            # and the fallback being returned early.
+            aggregate_failures do
+              expect(operation_3_stub).not_to receive(:perform_task)
+              operation_3_result = cb.call(operation: -> { operation_3_stub.perform_task }, fallback: -> { fallback_stub })
+              # Check Circuit Breaker state and result
+              expect(cb.state).to eq(:open)
+              expect(cb.error_count).to eq(2)
+              expect(operation_3_result).to eq(fallback_stub)
+            end
+          end
+        end
+
+        context "when the error_threshold is exceeded and skip_duration has expired" do
+          after { Timecop.return }
+
+          it "closes the circuit and returns the operation result" do
+            # Arrange
+            operation_1_stub      = instance_double("Operation1")
+            operation_2_stub      = instance_double("Operation2")
+            operation_3_stub      = instance_double("Operation3")
+            fallback_stub         = instance_double("Fallback")
+            expected_result_stub  = instance_double("ExpectedResult")
+
+            allow(operation_1_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+            allow(operation_2_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+            allow(operation_3_stub).to receive(:perform_task).and_return(expected_result_stub)
+
+            # Act & Assert
+            cb = described_class.new(:test_circuit_breaker, error_threshold: 2, skip_duration: 10)
+
+            # The first operation will fail with Timeout::Error, resulting in the exception being caught and
+            # the fallback being returned as the operation result. The error_count is incremented to 1.
+            aggregate_failures do
+              expect(operation_1_stub).to receive(:perform_task)
+              operation_1_result = cb.call(operation: -> { operation_1_stub.perform_task }, fallback: -> { fallback_stub })
+              # Check Circuit Breaker state and result
+              expect(cb.state).to eq(:closed)
+              expect(cb.error_count).to eq(1)
+              expect(operation_1_result).to eq(fallback_stub)
+            end
+
+            # The second operation will also fail with Timeout::Error, resulting in the exception being caught and
+            # the fallback being returned as the operation result. The error_count is incremented to 2 and the circuit
+            # is opened.
+            aggregate_failures do
+              expect(operation_2_stub).to receive(:perform_task)
+              operation_2_result = cb.call(operation: -> { operation_2_stub.perform_task }, fallback: -> { fallback_stub })
+              # Check Circuit Breaker state and result
+              expect(cb.state).to eq(:open)
+              expect(cb.error_count).to eq(2)
+              expect(operation_2_result).to eq(fallback_stub)
+            end
+
+            # The third request is fired after the skip duration has expired. It should the allowed to execute,
+            # ie. #call should be executed, and the expected operation result returned.
+            Timecop.travel(Time.now + 10.seconds) do
+              aggregate_failures do
+                expect(operation_3_stub).to receive(:perform_task)
+                operation_3_result = cb.call(operation: -> { operation_3_stub.perform_task }, fallback: -> { fallback_stub })
+
+                # Check Circuit Breaker state and result
+                expect(cb.state).to eq(:closed)
+                expect(operation_3_result).to eq(expected_result_stub)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/shift/circuit_breaker/circuit_handler_monitoring_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Shift
+  module CircuitBreaker
+    describe CircuitHandler do
+      before do
+        allow($stdout).to receive(:write)
+      end
+
+      context "Monitoring" do
+        let(:default_error_threshold) { 10 }
+        let(:default_skip_duration)   { 60 }
+
+        context "when an operation is successful" do
+          it "records the metric" do
+            # Arrange
+            monitor_stub          = instance_double("Shift::CircuitMonitor")
+            operation_stub        = instance_double("Operation")
+            fallback_stub         = instance_double("Fallback")
+            expected_result_stub  = instance_double("ExpectedResult")
+
+            allow(monitor_stub).to receive(:record_metric)
+            allow(operation_stub).to receive(:perform_task).and_return(expected_result_stub)
+
+            # Act
+            cb = described_class.new(:test_circuit_breaker,
+                                     error_threshold: default_skip_duration,
+                                     skip_duration: default_skip_duration,
+                                     monitor: monitor_stub)
+
+            # Assert
+            aggregate_failures do
+              expect(operation_stub).to receive(:perform_task).and_return(expected_result_stub)
+
+              operation_result = cb.call(operation: -> { operation_stub.perform_task }, fallback: -> { fallback_stub })
+
+              expect(monitor_stub).to have_received(:record_metric)
+              expect(operation_result).to eq(expected_result_stub)
+            end
+          end
+        end
+
+        context "when an exception is raised" do
+          it "records the metric" do
+            # Arrange
+            monitor_stub    = instance_double("Shift::CircuitMonitor")
+            operation_stub  = instance_double("Operation")
+            fallback_stub   = instance_double("Fallback")
+
+            allow(monitor_stub).to receive(:record_metric)
+            allow(operation_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+
+            # Act
+            cb = described_class.new(:test_circuit_breaker, error_threshold: 1, skip_duration: default_skip_duration, monitor: monitor_stub)
+
+            # Assert
+            aggregate_failures do
+              expect(operation_stub).to receive(:perform_task).and_raise(Timeout::Error, "Request Timeout")
+
+              operation_result = cb.call(operation: -> { operation_stub.perform_task }, fallback: -> { fallback_stub })
+
+              expect(monitor_stub).to have_received(:record_metric)
+              expect(operation_result).to eq(fallback_stub)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/shift/circuit_breaker/circuit_handler_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Shift
+  module CircuitBreaker
+    describe CircuitHandler do
+      before do
+        allow($stdout).to receive(:write)
+      end
+
+      context "when given a valid operation" do
+        let(:default_error_threshold) { 10 }
+        let(:default_skip_duration)   { 60 }
+
+        it "returns the expected result" do
+          # Arrange
+          operation_stub        = instance_double("Operation")
+          fallback_stub         = instance_double("Fallback")
+          expected_result_stub  = instance_double("ExpectedResult")
+
+          allow(operation_stub).to receive(:perform_task).and_return(expected_result_stub)
+
+          # Act
+          cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+          operation_result = cb.call(operation: -> { operation_stub.perform_task }, fallback: -> { fallback_stub })
+
+          # Assert
+          expect(operation_result).to eq(expected_result_stub)
+        end
+      end
+
+      context "when given additional exception classes" do
+        let(:default_error_threshold) { 10 }
+        let(:default_skip_duration)   { 60 }
+
+        it "rescues the exception and returns the fallback" do
+          # Arrange
+          operation_stub                = instance_double("Operation")
+          fallback_stub                 = instance_double("Fallback")
+          additional_exception_classes  = [Faraday::ClientError]
+
+          allow(operation_stub).to receive(:perform_task).and_raise(Faraday::ClientError, "client error")
+
+          # Act
+          cb = described_class.new(:test_circuit_breaker,
+                                   error_threshold: default_error_threshold,
+                                   skip_duration: default_skip_duration,
+                                   additional_exception_classes: additional_exception_classes)
+
+          operation_result = cb.call(operation: -> { operation_stub.perform_task }, fallback: -> { fallback_stub })
+
+          # Assert
+          expect(operation_result).to eq(fallback_stub)
+        end
+      end
+
+      context "Invalid Arguments" do
+        context "when initialising service" do
+          let(:default_error_threshold) { 10 }
+          let(:default_skip_duration)   { 60 }
+
+          context "when no error_threshold is provided" do
+            it "raises an ArgumentError" do
+              # Act & Assert
+              expect { described_class.new(:test_circuit_breaker, skip_duration: default_skip_duration) }.to raise_error(ArgumentError)
+            end
+          end
+
+          context "when no skip_duration is provided" do
+            it "raises an ArgumentError" do
+              # Act & Assert
+              expect { described_class.new(:test_circuit_breaker, error_threshold: default_skip_duration) }.to raise_error(ArgumentError)
+            end
+          end
+        end
+
+        context "Invalid #call arguments" do
+          let(:default_error_threshold) { 10 }
+          let(:default_skip_duration)   { 60 }
+
+          context "when no operation is given" do
+            it "raises an ArgumentError" do
+              # Arrange
+              fallback_stub = instance_double("Fallback")
+
+              # Act
+              cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+
+              # Assert
+              expect { cb.call(fallback: -> { fallback_stub }) }.to raise_error(ArgumentError)
+            end
+          end
+
+          context "when no fallback is given" do
+            it "raises an ArgumentError" do
+              # Arrange
+              operation_stub = instance_double("Operation")
+
+              # Act
+              cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+
+              # Act & Assert
+              expect { cb.call(operation: -> { operation_stub }) }.to raise_error(ArgumentError)
+            end
+          end
+
+          context "when given nil as the operation" do
+            it "raises an ArgumentError" do
+              # Arrange
+              fallback_stub = instance_double("Fallback")
+
+              # Act
+              cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+
+              # Assert
+              expect { cb.call(operation: nil, fallback: -> { fallback_stub }) }.to raise_error(ArgumentError)
+            end
+          end
+
+          context "when given nil as the fallback" do
+            it "raises an ArgumentError" do
+              # Arrange
+              operation_stub = instance_double("Operation")
+
+              # Act
+              cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+
+              # Assert
+              expect { cb.call(operation: -> { operation_stub }, fallback: nil) }.to raise_error(ArgumentError)
+            end
+          end
+
+          context "when given an operation that does not implement #call" do
+            it "raises an ArgumentError" do
+              # Arrange
+              operation_stub  = instance_double("Operation")
+              fallback_stub   = instance_double("Fallback")
+
+              # Act
+              cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+
+              # Assert
+              expect { cb.call(operation: operation_stub, fallback: -> { fallback_stub }) }.to raise_error(ArgumentError)
+            end
+          end
+
+          context "when given a fallback that does not implement #call" do
+            it "raises an ArgumentError" do
+              # Arrange
+              operation_stub  = instance_double("Operation")
+              fallback_stub   = instance_double("Fallback")
+
+              # Act
+              cb = described_class.new(:test_circuit_breaker, error_threshold: default_error_threshold, skip_duration: default_skip_duration)
+
+              # Assert
+              expect { cb.call(operation: -> { operation_stub }, fallback: fallback_stub) }.to raise_error(ArgumentError)
+            end
+          end
+        end
+      end
+    end
+  end
+end