resilient 0.4.0.beta1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d58c0c8c5444d5e583d6667644d2309fd1d76c75
-  data.tar.gz: 92b729571e650001c424eac22b707eabb5f02806
+SHA256:
+  metadata.gz: 2e439a74385ae133b7d375d90c75dcc302a1cd77a56d69facda7b04f2de07124
+  data.tar.gz: bceca2780a2b2b71ff1b0084db9e2c6ed206345114d2849d1da1c957e1995365
 SHA512:
-  metadata.gz: de26fd92ca043468781a0cc18544d8904a37da9170c86f347141519e07e36304f005be212618f3dd909e379e3f694b638be480a483107a2ef9627440c70153d8
-  data.tar.gz: 149eba99b8f5d6e3310d0ee4933d4b3ea23cdbee945730a74f4d3189665a6432fda514b1a40a43e7eb51f89c1cc16bc0368642e8e37850ad26724c18be8cd151
+  metadata.gz: 8a58ea0dce1f90dc61f4a3d34d0fa6f7ad7ca64fd246776a6696ee2e7ae1f2df9447b9f1ba394a914503320b40a1d3a2b326fd27e0e954e826fb985209233330
+  data.tar.gz: '088e66a7f364869da5da43f926dead2cd62af861baaa07b3a4615e521ac1ab75ecdeb4e6c7aee0b1f40ce2a692e66cca25cd2737bfe2c3fdc1635142fb96fb3a'

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['2.5', '2.6', '2.7']
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v2
+      - name: Do some action caching
+        uses: actions/cache@v1
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-gem-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-gem-
+      - name: Set up Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install bundler
+        run: gem install bundler
+      - name: Run bundler
+        run: bundle install --jobs 4 --retry 3
+      - name: Run Tests
+        run: script/test

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## 0.5.1
+
+* [Added two new events open_circuit and close_circuit](https://github.com/jnunemaker/resilient/pull/16) and [renamed them here](https://github.com/jnunemaker/resilient/commit/407e673eb5268912814398bebdeb173793d0af05).
+
+## 0.5.0
+
+* [tweaked interface for metrics](https://github.com/jnunemaker/resilient/pull/15)
+* [stop rounding error percentage](https://github.com/jnunemaker/resilient/commit/6cdade5c3fc5f75a6ffde87082771608d582026c)
+
+## prior to 0.5.0
+
+* No changelog kept so just checkout the commits. There aren't too terrible many.

data/Gemfile

@@ -1,5 +1,10 @@
 source "https://rubygems.org"
 gemspec
 
-gem "guard", "~> 2.13.0"
-gem "guard-minitest", "~> 2.4.4"
+gem "timecop", "~> 0.8"
+gem "minitest", "~> 5.8"
+
+group :development do
+  gem "guard", "~> 2.13.0"
+  gem "guard-minitest", "~> 2.4.4"
+end

data/README.md

@@ -2,7 +2,7 @@
 
 Some tools to aid in resiliency in Ruby. For now, just a circuit breaker (~~stolen from~~ based on [hystrix](https://github.com/netflix/hystrix)). Soon much more...
 
-Nothing asynchronous or thread safe yet either, but open to it and would like to see more around it in the future.
+Nothing asynchronous or thread safe yet either, but open to it and would like to see more around it in the future. See more here: [jnunemaker/resilient#18](https://github.com/jnunemaker/resilient/issues/18).
 
 ## Installation
 
@@ -29,7 +29,7 @@ require "resilient/circuit_breaker"
 # CircuitBreaker.new as `get` keeps a registry of circuits by key to prevent
 # creating multiple instances of the same circuit breaker for a key; not using
 # `get` means you would have multiple instances of the circuit breaker and thus
-# separate state and metrics; you can read more in examples/for_vs_new.rb
+# separate state and metrics; you can read more in examples/get_vs_new.rb
 circuit_breaker = Resilient::CircuitBreaker.get("example")
 if circuit_breaker.allow_request?
   begin
@@ -82,14 +82,30 @@ circuit_breaker = Resilient::CircuitBreaker.get("example", {
 # etc etc etc
 ```
 
+## Default Properties
+
+Property                        | Default                | Notes
+--------------------------------|------------------------|--------
+**:force_open**                 | `false`                  | allows forcing the circuit open (stopping all requests)
+**:force_closed**               | `false`                  | allows ignoring errors and therefore never trip "open" (e.g. allow all traffic through); normal instrumentation will still happen, thus allowing you to "test" configuration live without impact
+**:instrumenter**               | `Instrumenters::Noop`    | what to use to instrument all events that happen (e.g.  `ActiveSupport::Notifications`)
+**:sleep_window_seconds**       | `5`                      | seconds after tripping circuit before allowing retry
+**:request_volume_threshold**   | `20`                     | number of requests that must be made within a statistical window before open/close decisions are made using stats
+**:error_threshold_percentage** | `50`                     |  % of "marks" that must be failed to trip the circuit
+**:window_size_in_seconds**     | `60`                     | number of seconds in the statistical window
+**:bucket_size_in_seconds**     | `10`                     | size of buckets in statistical window
+**:metrics**                    | `Resilient::Metrics.new` | metrics instance used to keep track of success and failure
+
 ## Tests
 
-To ensure that you have a clean circuit for each test case, be sure to run the following in the setup for your tests (which resets each registered circuit breaker) either before every test case or at a minimum each test case that uses circuit breakers.
+To ensure that you have clean circuit breakers for each test case, be sure to run the following in the setup for your tests (which resets the default registry and thus clears all the registered circuits) either before every test case or at a minimum each test case that uses circuit breakers.
 
 ```ruby
-Resilient::CircuitBreaker.reset
+Resilient::CircuitBreaker::Registry.reset
 ```
 
+**Note**: If you use a non-default registry, you'll need to reset that on your own. If you don't know what I'm talking about, you are fine.
+
 ## Development
 
 ```bash

data/examples/binary.rb

@@ -0,0 +1,114 @@
+# setting up load path
+require "pathname"
+root_path = Pathname(__FILE__).dirname.join("..").expand_path
+lib_path  = root_path.join("lib")
+$:.unshift(lib_path)
+
+# requiring stuff for this example
+require "pp"
+require "minitest/autorun"
+require "resilient/circuit_breaker"
+require "resilient/test/metrics_interface"
+
+# Metrics class that closes circuit on every success call and opens circuit for
+# sleep_window_seconds on every failure.
+class BinaryMetrics
+  def initialize(options = {})
+    reset
+  end
+
+  def success
+    reset
+    nil
+  end
+
+  def failure
+    @closed = false
+    nil
+  end
+
+  def reset
+    @closed = true
+    nil
+  end
+
+  def under_request_volume_threshold?(request_volume_threshold)
+    false
+  end
+
+  def under_error_threshold_percentage?(error_threshold_percentage)
+    @closed
+  end
+end
+
+class BinaryMetricsTest < Minitest::Test
+  def setup
+    @object = BinaryMetrics.new
+  end
+
+  include Resilient::Test::MetricsInterface
+end
+
+circuit_breaker = Resilient::CircuitBreaker.get("example", {
+  sleep_window_seconds: 1,
+  metrics: BinaryMetrics.new,
+})
+
+# success
+if circuit_breaker.allow_request?
+  begin
+    puts "do expensive thing"
+    circuit_breaker.success
+  rescue => boom
+    # won't get here in this example
+    circuit_breaker.failure
+  end
+else
+  raise "will not get here"
+end
+
+# failure
+if circuit_breaker.allow_request?
+  begin
+    raise
+  rescue => boom
+    circuit_breaker.failure
+    puts "failed slow, do fallback"
+  end
+else
+  raise "will not get here"
+end
+
+# fail fast
+if circuit_breaker.allow_request?
+  raise "will not get here"
+else
+  puts "failed fast, do fallback"
+end
+
+start = Time.now
+
+while (Time.now - start) < 3
+  if circuit_breaker.allow_request?
+    puts "doing a single attempt as we've failed fast for sleep_window_seconds"
+    break
+  else
+    puts "failed fast, do fallback"
+  end
+  sleep rand(0.1)
+end
+
+if circuit_breaker.allow_request?
+  raise "will not get here"
+else
+  puts "request denied because single request has not been marked success yet"
+end
+
+puts "marking single request as success"
+circuit_breaker.success
+
+if circuit_breaker.allow_request?
+  puts "circuit reset and back closed now, allowing requests"
+else
+  raise "will not get here"
+end

data/lib/resilient/circuit_breaker.rb

@@ -2,15 +2,11 @@ require "resilient/key"
 require "resilient/circuit_breaker/metrics"
 require "resilient/circuit_breaker/properties"
 require "resilient/circuit_breaker/registry"
+require "forwardable"
 
 module Resilient
   class CircuitBreaker
-    # Public: Resets all registered circuit breakers (and thus their state/metrics).
-    # Useful for ensuring a clean environment between tests. If you are using a
-    # registry other than the default, you will need to handle resets on your own.
-    def self.reset
-      Registry.default.reset
-    end
+    extend Forwardable
 
     # Public: Returns an instance of circuit breaker based on key and registry.
     # Default registry is used if none is provided. If key does not exist, it is
@@ -18,11 +14,11 @@ module Resilient
     # allocating a new instance in order to ensure that state/metrics are the
     # same per key.
     #
-    #  See #initialize for docs on key, properties and metrics.
-    def self.get(key, properties = nil, metrics = nil, registry = nil)
+    #  See #initialize for docs on key and properties.
+    def self.get(key, properties = nil, registry = nil)
       key = Key.wrap(key)
       (registry || Registry.default).fetch(key) {
-        new(key, properties, metrics)
+        new(key, properties)
       }
     end
 
@@ -33,10 +29,11 @@ module Resilient
       end
     end
 
+    def_delegator :@properties, :metrics
+
     attr_reader :key
     attr_reader :open
     attr_reader :opened_or_last_checked_at_epoch
-    attr_reader :metrics
     attr_reader :properties
 
     # Private: Builds new instance of a CircuitBreaker.
@@ -48,32 +45,14 @@ module Resilient
     #               circuit breaker should behave. Optional. Defaults to new
     #               Resilient::CircuitBreaker::Properties instance.
     #
-    #  metrics - The object that stores successes and failures. Optional.
-    #            Defaults to new Resilient::CircuitBreaker::Metrics instance
-    #            based on window size and bucket size properties.
-    #
     # Returns CircuitBreaker instance.
-    def initialize(key, properties = nil, metrics = nil)
+    def initialize(key, properties = nil)
       raise ArgumentError, "key argument is required" if key.nil?
 
       @key = Key.wrap(key)
+      @properties = Properties.wrap(properties)
       @open = false
       @opened_or_last_checked_at_epoch = 0
-
-      @properties = if properties
-        Properties.wrap(properties)
-      else
-        Properties.new
-      end
-
-      @metrics = if metrics
-        metrics
-      else
-        Metrics.new({
-          window_size_in_seconds: @properties.window_size_in_seconds,
-          bucket_size_in_seconds: @properties.bucket_size_in_seconds,
-        })
-      end
     end
 
     def allow_request?
@@ -102,7 +81,7 @@ module Resilient
           payload[:closed_the_circuit] = true
           close_circuit
         else
-          @metrics.success
+          metrics.success
         end
         nil
       }
@@ -110,7 +89,7 @@ module Resilient
 
     def failure
       instrument("resilient.circuit_breaker.failure", key: @key) { |payload|
-        @metrics.failure
+        metrics.failure
         nil
       }
     end
@@ -119,7 +98,7 @@ module Resilient
       instrument("resilient.circuit_breaker.reset", key: @key) { |payload|
         @open = false
         @opened_or_last_checked_at_epoch = 0
-        @metrics.reset
+        metrics.reset
         nil
       }
     end
@@ -127,22 +106,29 @@ module Resilient
     private
 
     def open_circuit
-      @opened_or_last_checked_at_epoch = Time.now.to_i
-      @open = true
+      instrument("resilient.circuit_breaker.open_circuit", key: @key) { |payload|
+        @opened_or_last_checked_at_epoch = Time.now.to_i
+        @open = true
+        payload[:open] = @open
+      }
     end
 
     def close_circuit
-      @open = false
-      @opened_or_last_checked_at_epoch = 0
-      @metrics.reset
+      instrument("resilient.circuit_breaker.close_circuit", key: @key) { |payload|
+        @open = false
+        payload[:open] = @open
+        payload[:interval] = Time.now.to_i - @opened_or_last_checked_at_epoch
+        @opened_or_last_checked_at_epoch = 0
+      }
+      metrics.reset
     end
 
     def under_request_volume_threshold?
-      @metrics.requests < @properties.request_volume_threshold
+      metrics.under_request_volume_threshold?(@properties.request_volume_threshold)
     end
 
     def under_error_threshold_percentage?
-      @metrics.error_percentage < @properties.error_threshold_percentage
+      metrics.under_error_threshold_percentage?(@properties.error_threshold_percentage)
     end
 
     def open?

data/lib/resilient/circuit_breaker/metrics.rb

@@ -30,6 +30,14 @@ module Resilient
         @buckets = []
       end
 
+      def under_request_volume_threshold?(request_volume_threshold)
+        requests < request_volume_threshold
+      end
+
+      def under_error_threshold_percentage?(error_threshold_percentage)
+        error_percentage < error_threshold_percentage
+      end
+
       def success
         @storage.increment(current_bucket, StorageSuccessKeys)
         prune_buckets
@@ -42,15 +50,12 @@ module Resilient
         nil
       end
 
-      def successes
-        prune_buckets
-        @storage.sum(@buckets, :successes)[:successes]
+      def reset
+        @storage.prune(@buckets, StorageKeys)
+        nil
       end
 
-      def failures
-        prune_buckets
-        @storage.sum(@buckets, :failures)[:failures]
-      end
+      private
 
       def requests
         prune_buckets
@@ -71,16 +76,9 @@ module Resilient
         requests = successes + failures
         return 0 if failures == 0 || requests == 0
 
-        ((failures / requests.to_f) * 100).round
+        (failures / requests.to_f) * 100
       end
 
-      def reset
-        @storage.prune(@buckets, StorageKeys)
-        nil
-      end
-
-      private
-
       def current_bucket(timestamp = Time.now.to_i)
         bucket = @buckets.detect { |bucket| bucket.include?(timestamp) }
         return bucket if bucket

data/lib/resilient/circuit_breaker/properties.rb

@@ -12,6 +12,8 @@ module Resilient
           hash_or_instance
         when Hash
           new(hash_or_instance)
+        when NilClass
+          new
         else
           raise TypeError, "properties must be Hash or Resilient::Properties instance"
         end
@@ -45,6 +47,9 @@ module Resilient
       # size of buckets in statistical window
       attr_reader :bucket_size_in_seconds
 
+      # metrics instance used to keep track of success and failure
+      attr_reader :metrics
+
       def initialize(options = {})
         @force_open = options.fetch(:force_open, false)
         @force_closed = options.fetch(:force_closed, false)
@@ -64,6 +69,13 @@ module Resilient
             "window_size_in_seconds must be perfectly divisible by" +
             " bucket_size_in_seconds in order to evenly partition the buckets"
         end
+
+        @metrics = options.fetch(:metrics) {
+          Metrics.new({
+            window_size_in_seconds: @window_size_in_seconds,
+            bucket_size_in_seconds: @bucket_size_in_seconds,
+          })
+        }
       end
     end
   end

data/lib/resilient/circuit_breaker/registry.rb

@@ -11,11 +11,19 @@ module Resilient
         @default = value
       end
 
+      # Public: Reset the default registry. This completely wipes all instances
+      # by swapping out the default registry for a new one and letting the old
+      # one get GC'd. Useful in tests to get a completely clean slate.
+      def self.reset
+        default.reset
+      end
+
       def initialize(source = nil)
         @source = source || {}
       end
 
-      # Setup default to new instance.
+      # Setup new instance as default. Needs to be after initialize so hash gets
+      # initialize correctly.
       @default = new
 
       # Internal: To be used by CircuitBreaker to either get an instance for a
@@ -38,7 +46,7 @@ module Resilient
       # breakers, which should only really be used for cleaning up in
       # test environment.
       def reset
-        @source.each_value(&:reset)
+        @source = {}
         nil
       end
     end

data/lib/resilient/test/circuit_breaker_registry_interface.rb

@@ -20,18 +20,17 @@ module Resilient
       end
 
       def test_reset
-        bar_value = Minitest::Mock.new
-        wick_value = Minitest::Mock.new
-        bar_value.expect :reset, nil, []
-        wick_value.expect :reset, nil, []
-
-        @object.fetch("foo") { bar_value }
-        @object.fetch("baz") { wick_value }
+        original_foo = @object.fetch("foo") { Object.new }
+        original_bar = @object.fetch("bar") { Object.new }
 
         assert_nil @object.reset
 
-        bar_value.verify
-        wick_value.verify
+        foo = @object.fetch("foo") { Object.new }
+        bar = @object.fetch("bar") { Object.new }
+
+        # assert that the objects before and after reset are not the same object
+        refute original_foo.equal?(foo)
+        refute original_bar.equal?(bar)
       end
 
       def test_reset_empty_registry

data/lib/resilient/test/metrics_interface.rb

@@ -1,6 +1,16 @@
 module Resilient
   class Test
     module MetricsInterface
+      def test_responds_to_under_request_volume_threshold_predicate
+        assert_respond_to @object, :under_request_volume_threshold?
+        assert_equal 1, @object.method(:under_request_volume_threshold?).arity
+      end
+
+      def test_responds_to_under_error_threshold_percentage_predicate
+        assert_respond_to @object, :under_error_threshold_percentage?
+        assert_equal 1, @object.method(:under_error_threshold_percentage?).arity
+      end
+
       def test_responds_to_success
         assert_respond_to @object, :success
       end
@@ -17,22 +27,6 @@ module Resilient
         assert_nil @object.failure
       end
 
-      def test_responds_to_successes
-        assert_respond_to @object, :successes
-      end
-
-      def test_responds_to_failures
-        assert_respond_to @object, :failures
-      end
-
-      def test_responds_to_requests
-        assert_respond_to @object, :requests
-      end
-
-      def test_responds_to_error_percentage
-        assert_respond_to @object, :error_percentage
-      end
-
       def test_responds_to_reset
         assert_respond_to @object, :reset
       end

data/lib/resilient/version.rb

@@ -1,3 +1,3 @@
 module Resilient
-  VERSION = "0.4.0.beta1"
+  VERSION = "0.5.1"
 end

data/resilient.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "bundler", "< 3.0"
   spec.add_development_dependency "minitest", "~> 5.8"
   spec.add_development_dependency "timecop", "~> 0.8.0"
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: resilient
 version: !ruby/object:Gem::Version
-  version: 0.4.0.beta1
+  version: 0.5.1
 platform: ruby
 authors:
 - John Nunemaker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-02 00:00:00.000000000 Z
+date: 2021-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -59,13 +59,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
-- ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Guardfile
 - LICENSE.txt
 - README.md
 - examples/basic.rb
+- examples/binary.rb
 - examples/get_vs_new.rb
 - examples/long_running.rb
 - lib/resilient.rb
@@ -108,12 +110,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: toolkit for resilient ruby apps

data/.travis.yml

@@ -1,7 +0,0 @@
-language: ruby
-rvm:
-  - 2.0.0
-  - 2.1.4
-  - 2.2.3
-before_install: gem install bundler -v 1.10.6
-script: script/test