resilient 0.3.1 → 0.4.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fff95e3775a3225c6694d41256726d7cf7dd97ed
-  data.tar.gz: 3a60f913516f625995d884e8b738941f76d1e839
+  metadata.gz: d58c0c8c5444d5e583d6667644d2309fd1d76c75
+  data.tar.gz: 92b729571e650001c424eac22b707eabb5f02806
 SHA512:
-  metadata.gz: a87785935c77f251a9e9dcd738a4b51aea2d27f87504b30fb7d958a7d94de04a83502d0754a0c05a2c72494b68e7b10ef1f424f89678a434844a44d1aa215bbb
-  data.tar.gz: 54c77250844604e9dd4ff3db089a422a9bca05a4a5779ebfd73b3645fb8484df12bed9c419b44aa6977e960e584b3eb26c2416bf979cb75a0d64f588c0f92be7
+  metadata.gz: de26fd92ca043468781a0cc18544d8904a37da9170c86f347141519e07e36304f005be212618f3dd909e379e3f694b638be480a483107a2ef9627440c70153d8
+  data.tar.gz: 149eba99b8f5d6e3310d0ee4933d4b3ea23cdbee945730a74f4d3189665a6432fda514b1a40a43e7eb51f89c1cc16bc0368642e8e37850ad26724c18be8cd151

data/README.md

@@ -1,6 +1,6 @@
 # Resilient
 
-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...
+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.
 
@@ -25,8 +25,12 @@ Or install it yourself as:
 ```ruby
 require "resilient/circuit_breaker"
 
-# default properties for circuit
-circuit_breaker = Resilient::CircuitBreaker.new(key: Resilient::Key.new("example"))
+# default properties for circuit, CircuitBreaker.get is used instead of
+# 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
+circuit_breaker = Resilient::CircuitBreaker.get("example")
 if circuit_breaker.allow_request?
   begin
     # do something expensive
@@ -43,7 +47,7 @@ end
 customize properties of circuit:
 
 ```ruby
-properties = Resilient::CircuitBreaker::Properties.new({
+circuit_breaker = Resilient::CircuitBreaker.get("example", {
   # at what percentage of errors should we open the circuit
   error_threshold_percentage: 50,
   # do not try request again for 5 seconds
@@ -51,37 +55,41 @@ properties = Resilient::CircuitBreaker::Properties.new({
   # do not open circuit until at least 5 requests have happened
   request_volume_threshold: 5,
 })
-circuit_breaker = Resilient::CircuitBreaker.new(properties: properties, key: Resilient::Key.new("example"))
 # etc etc etc
 ```
 
 force the circuit to be always open:
 
 ```ruby
-properties = Resilient::CircuitBreaker::Properties.new(force_open: true)
-circuit_breaker = Resilient::CircuitBreaker.new(properties: properties, key: Resilient::Key.new("example"))
+circuit_breaker = Resilient::CircuitBreaker.get("example", force_open: true)
 # etc etc etc
 ```
 
 force the circuit to be always closed (great way to test in production with no impact, all instrumentation still runs which means you can measure in production with config and gain confidence while never actually opening a circuit incorrectly):
 
 ```ruby
-properties = Resilient::CircuitBreaker::Properties.new(force_closed: true)
-circuit_breaker = Resilient::CircuitBreaker.new(properties: properties, key: Resilient::Key.new("example"))
+circuit_breaker = Resilient::CircuitBreaker.get("example", force_closed: true)
 # etc etc etc
 ```
 
 customize rolling window to be 10 buckets of 1 second each (10 seconds in all):
 
 ```ruby
-metrics = Resilient::CircuitBreaker::Metrics.new({
+circuit_breaker = Resilient::CircuitBreaker.get("example", {
   window_size_in_seconds: 10,
   bucket_size_in_seconds: 1,
 })
-circuit_breaker = Resilient::CircuitBreaker.new(metrics: metrics, key: Resilient::Key.new("example"))
 # etc etc etc
 ```
 
+## 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.
+
+```ruby
+Resilient::CircuitBreaker.reset
+```
+
 ## Development
 
 ```bash

data/examples/basic.rb

@@ -8,12 +8,11 @@ $:.unshift(lib_path)
 require "pp"
 require "resilient/circuit_breaker"
 
-properties = Resilient::CircuitBreaker::Properties.new({
+circuit_breaker = Resilient::CircuitBreaker.get("example", {
   sleep_window_seconds: 1,
   request_volume_threshold: 10,
   error_threshold_percentage: 25,
 })
-circuit_breaker = Resilient::CircuitBreaker.new(key: Resilient::Key.new("example"), properties: properties)
 
 # success
 if circuit_breaker.allow_request?

data/examples/get_vs_new.rb

@@ -0,0 +1,40 @@
+# setting up load path
+require "pathname"
+root_path = Pathname(__FILE__).dirname.join("..").expand_path
+lib_path  = root_path.join("lib")
+$:.unshift(lib_path)
+
+# by default new is private so people don't use it, this makes it possible to
+# use it as resilient checks for this env var prior to privatizing new
+ENV["RESILIENT_PUBLICIZE_NEW"] = "1"
+
+# requiring stuff for this example
+require "pp"
+require "resilient/circuit_breaker"
+
+instance = Resilient::CircuitBreaker.get("example")
+instance_using_get = Resilient::CircuitBreaker.get("example")
+instance_using_new = Resilient::CircuitBreaker.new("example")
+
+puts "instance equals instance_using_get: #{instance.equal?(instance_using_get)}"
+puts "instance equals instance_using_new: #{instance.equal?(instance_using_new)}"
+
+instance.properties.request_volume_threshold.times do
+  instance.failure
+end
+
+puts "instance allow_request?: #{instance.allow_request?}"
+puts "instance_using_get allow_request?: #{instance_using_get.allow_request?}"
+
+# this instance allows the request because it isn't sharing internal state and
+# metrics due to being a new allocated instance; the for instance does not
+# suffer this because it looks up instances in a registry rather than always
+# generating a new instance even if you use the exact same key as it bypasses
+# the registry
+puts "instance_using_new allow_request?: #{instance_using_new.allow_request?}"
+
+# instance equals instance_using_get: true
+# instance equals instance_using_new: false
+# instance allow_request?: false
+# instance_using_get allow_request?: false
+# instance_using_new allow_request?: true

data/examples/long_running.rb

@@ -8,14 +8,13 @@ $:.unshift(lib_path)
 require "pp"
 require "resilient/circuit_breaker"
 
-properties = Resilient::CircuitBreaker::Properties.new({
+circuit_breaker = Resilient::CircuitBreaker.get("example", {
   sleep_window_seconds: 5,
   request_volume_threshold: 20,
   error_threshold_percentage: 10,
   window_size_in_seconds: 60,
   bucket_size_in_seconds: 1,
 })
-circuit_breaker = Resilient::CircuitBreaker.new(key: Resilient::Key.new("example"), properties: properties)
 
 iterations = 0
 loop do

data/lib/resilient/circuit_breaker.rb

@@ -1,24 +1,67 @@
 require "resilient/key"
 require "resilient/circuit_breaker/metrics"
 require "resilient/circuit_breaker/properties"
+require "resilient/circuit_breaker/registry"
 
 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
+
+    # 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
+    # registered. If key does exist, it returns registered instance instead of
+    # 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)
+      key = Key.wrap(key)
+      (registry || Registry.default).fetch(key) {
+        new(key, properties, metrics)
+      }
+    end
+
+    unless ENV.key?("RESILIENT_PUBLICIZE_NEW")
+      class << self
+        private :new
+        private :allocate
+      end
+    end
+
     attr_reader :key
     attr_reader :open
     attr_reader :opened_or_last_checked_at_epoch
     attr_reader :metrics
     attr_reader :properties
 
-    def initialize(key: nil, open: false, properties: nil, metrics: nil)
-      # ruby 2.0 does not support required keyword arguments, this gets around that
+    # Private: Builds new instance of a CircuitBreaker.
+    #
+    #  key - The String or Resilient::Key that determines uniqueness of the
+    #        circuit breaker in the registry and for instrumentation.
+    #
+    #  properties - The Hash or Resilient::CircuitBreaker::Properties that determine how the
+    #               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)
       raise ArgumentError, "key argument is required" if key.nil?
-      @key = key
-      @open = open
+
+      @key = Key.wrap(key)
+      @open = false
       @opened_or_last_checked_at_epoch = 0
 
       @properties = if properties
-        properties
+        Properties.wrap(properties)
       else
         Properties.new
       end

data/lib/resilient/circuit_breaker/properties.rb

@@ -3,6 +3,20 @@ require "resilient/instrumenters/noop"
 module Resilient
   class CircuitBreaker
     class Properties
+
+      # Internal: Takes a string name or instance of a Key and always returns a
+      # Key instance.
+      def self.wrap(hash_or_instance)
+        case hash_or_instance
+        when self
+          hash_or_instance
+        when Hash
+          new(hash_or_instance)
+        else
+          raise TypeError, "properties must be Hash or Resilient::Properties instance"
+        end
+      end
+
       # allows forcing the circuit open (stopping all requests)
       attr_reader :force_open
 

data/lib/resilient/circuit_breaker/registry.rb

@@ -0,0 +1,46 @@
+module Resilient
+  class CircuitBreaker
+    class Registry
+      # Internal: Default registry to use for circuit breakers.
+      def self.default
+        @default
+      end
+
+      # Internal: Allows overriding default registry for circuit breakers.
+      def self.default=(value)
+        @default = value
+      end
+
+      def initialize(source = nil)
+        @source = source || {}
+      end
+
+      # Setup default to new instance.
+      @default = new
+
+      # Internal: To be used by CircuitBreaker to either get an instance for a
+      # key or set a new instance for a key.
+      #
+      # Raises KeyError if key not found and no block provided.
+      def fetch(key, &block)
+        if value = @source[key]
+          value
+        else
+          if block_given?
+            @source[key] = yield
+          else
+            @source.fetch(key)
+          end
+        end
+      end
+
+      # Internal: To be used by CircuitBreaker to reset the stored circuit
+      # breakers, which should only really be used for cleaning up in
+      # test environment.
+      def reset
+        @source.each_value(&:reset)
+        nil
+      end
+    end
+  end
+end

data/lib/resilient/instrumenters/memory.rb

@@ -8,7 +8,7 @@ module Resilient
       attr_reader :events
 
       def initialize
-        @events = []
+        reset
       end
 
       def instrument(name, payload = {})
@@ -25,6 +25,10 @@ module Resilient
         @events << Event.new(name, payload, result)
         result
       end
+
+      def reset
+        @events = []
+      end
     end
   end
 end

data/lib/resilient/key.rb

@@ -1,9 +1,31 @@
 module Resilient
   class Key
+
+    # Internal: Takes a string name or instance of a Key and always returns a
+    # Key instance.
+    def self.wrap(string_or_instance)
+      case string_or_instance
+      when self, NilClass
+        string_or_instance
+      else
+        new(string_or_instance)
+      end
+    end
+
     attr_reader :name
 
     def initialize(name)
+      raise TypeError, "name must be a String" unless name.is_a?(String)
       @name = name
     end
+
+    def ==(other)
+      self.class == other.class && name == other.name
+    end
+    alias_method :eql?, :==
+
+    def hash
+      @name.hash
+    end
   end
 end

data/lib/resilient/test/circuit_breaker_registry_interface.rb

@@ -0,0 +1,42 @@
+module Resilient
+  class Test
+    module CircuitBreakerRegistryInterface
+      def test_responds_to_fetch
+        assert_respond_to @object, :fetch
+      end
+
+      def test_responds_to_reset
+        assert_respond_to @object, :reset
+      end
+
+      def test_fetch
+        key = "foo"
+        value = "bar".freeze
+
+        assert_raises(KeyError) { @object.fetch(key) }
+        assert_equal value, @object.fetch(key) { value }
+        assert_equal value, @object.fetch(key)
+        assert @object.fetch(key).equal?(value)
+      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 }
+
+        assert_nil @object.reset
+
+        bar_value.verify
+        wick_value.verify
+      end
+
+      def test_reset_empty_registry
+        assert_nil @object.reset
+      end
+    end
+  end
+end

data/lib/resilient/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: resilient
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0.beta1
 platform: ruby
 authors:
 - John Nunemaker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-04 00:00:00.000000000 Z
+date: 2016-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,7 @@ files:
 - LICENSE.txt
 - README.md
 - examples/basic.rb
+- examples/get_vs_new.rb
 - examples/long_running.rb
 - lib/resilient.rb
 - lib/resilient/circuit_breaker.rb
@@ -76,10 +77,12 @@ files:
 - lib/resilient/circuit_breaker/metrics/storage/memory.rb
 - lib/resilient/circuit_breaker/metrics/window_size.rb
 - lib/resilient/circuit_breaker/properties.rb
+- lib/resilient/circuit_breaker/registry.rb
 - lib/resilient/instrumenters/memory.rb
 - lib/resilient/instrumenters/noop.rb
 - lib/resilient/key.rb
 - lib/resilient/test/circuit_breaker_interface.rb
+- lib/resilient/test/circuit_breaker_registry_interface.rb
 - lib/resilient/test/metrics_interface.rb
 - lib/resilient/test/metrics_storage_interface.rb
 - lib/resilient/test/properties_interface.rb
@@ -105,12 +108,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: toolkit for resilient ruby apps