faulty 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1da265b4bb2e4ae865726930ec3855a03d31c3b47c92b9ef08d7519cdb9d9d9
-  data.tar.gz: a2fdbb6d1ccdfb7be6c68467ce45a802644ef4f9a61769e8b7387d626307facd
+  metadata.gz: f12337b51cbd0d484e4255078d7818354a79bf4138a5ef2b527d93915834bd9c
+  data.tar.gz: bbc9ec4e9e9e4707ec4d88246d77b19faead958a75b0f3e58d623fbb70d1ae59
 SHA512:
-  metadata.gz: 2ad680693b76db3f3d420d7ded71269c8ad669c23bffa0e4ab598d8d0772955c70479d1497ea51b7aa9691b8438e06bc83ff13d4f3e3f6842a3327971dcbb4d3
-  data.tar.gz: 2890441590276ecd72e16ee9866955b027a3e1df26907f9cc71a94f3f1161c01ea30665860bcf526fe871e84a10a7c9c728c050bbf961d8b9d670b4a6fb4bbfa
+  metadata.gz: 2d79bbe071f0471735795996ff7f54b0f580d445973c9c048d53bd5fac5352f0f33446e3833a39ff3cb3db88c849eb5dbb2cac253452de61d76ee467bb2e9bc9
+  data.tar.gz: a3266ee94d29c63a6e880461378223e95578518575e4b8d4795df028f0e4c717c0099b88d56e51a697fac99f43e1578cda92f48c937b8186003e4a56e0eeec2d

data/CHANGELOG.md

@@ -1,10 +1,15 @@
+## Release v0.1.3
+
+* Fix bug where memory storage would delete the newest entries #5
+* Add HoneybadgerListener for error reporting #4
+
 ## Release v0.1.2
 
-* Fix Storage::FaultTolerantProxy open and reopen methods
+* Fix Storage::FaultTolerantProxy open and reopen methods #2
 
 ## Release v0.1.1
 
-* Fix a crash when Storage::FaultTolerantProxy created a status stub
+* Fix a crash when Storage::FaultTolerantProxy created a status stub #1
 
 ## Release v0.1.0
 

data/README.md

@@ -67,6 +67,51 @@ end
 For a full list of configuration options, see the
 [Global Configuration](#global-configuration) section.
 
+## What is this for?
+
+Circuit breakers are a fault-tolerance tool for creating separation between your
+application and external dependencies. For example, your application may call an
+external API to send a text message:
+
+```ruby
+TextApi.send(message)
+```
+
+In normal operation, this API call is very fast. However what if the texting
+service started hanging? Your application would quickly use up a lot of
+resources waiting for requests to return from the service. You could consider
+adding a timeout to your request:
+
+```ruby
+TextApi.send(message, timeout: 5)
+```
+
+Now your application will terminate requests after 5 seconds, but that could
+still add up to a lot of resources if you call this thousands of times. Circuit
+breakers solve this problem.
+
+```ruby
+Faulty.circuit(:text_api).run do
+  TextApi.send(message, timeout: 5)
+end
+```
+
+Now, when the text API hangs, the first few will run and start timing out. This
+will trip the circuit. After the circuit trips
+(see [How it Works](#how-it-works)), calls to the text API will be paused for
+the configured cool down period. Your application resources are not overwhelmed.
+
+You are free to implement a fallback or error handling however you wish, for
+example, in this case, you might add the text message to a failure queue:
+
+```ruby
+Faulty.circuit(:text_api).run do
+  TextApi.send(message, timeout: 5)
+rescue Faulty::CircuitError => e
+  FailureQueue.enqueue(message)
+end
+```
+
 ## Basic Usage
 
 To create a circuit, call `Faulty.circuit`. This can be done as you use the
@@ -137,9 +182,9 @@ Faulty's implementation are:
 - Event-based monitoring
 
 Following the principals of the circuit-breaker pattern, the block given to
-`run` or `try_run` will always be executed as long as long as it never raises an
-error. If the block _does_ raise an error, then the circuit keeps track of the
-number of runs and the failure rate.
+`run` or `try_run` will always be executed as long as it never raises an error.
+If the block _does_ raise an error, then the circuit keeps track of the number
+of runs and the failure rate.
 
 Once both thresholds are breached, the circuit is opened. Once open, the
 circuit starts the cool-down period. Any executions within that cool-down are
@@ -201,7 +246,7 @@ A circuit can be created with the following configuration options. Those options
 are only set once, synchronized across threads, and will persist in-memory until
 the process exits. If you're using [scopes](#scopes), the options are retained
 within the context of each scope. All options given after the first call to
-`Faulty.circuit` (or `Scope.circuit` are ignored.
+`Faulty.circuit` (or `Scope.circuit`) are ignored.
 
 This is because the circuit objects themselves are internally memoized, and are
 read-only once created.
@@ -338,12 +383,17 @@ events. The full list of events is available from `Faulty::Events::EVENTS`.
   closed. Payload: `circuit`
 - `circuit_success` - A circuit execution was successful. Payload: `circuit`,
   `status`
-- `storage_failure` - A storage backend raised an error. Payload `circuit`,
-  `action`, `error`
+- `storage_failure` - A storage backend raised an error. Payload `circuit` (can
+  be nil), `action`, `error`
 
 By default events are logged using `Faulty::Events::LogListener`, but that can
 be replaced, or additional listeners can be added.
 
+### CallbackListener
+
+The callback listener is useful for ad-hoc handling of events. You can specify
+an event handler by calling a method on the callback handler by the same name.
+
 ```ruby
 Faulty.init do |config|
   # Replace the default listener with a custom callback listener
@@ -356,6 +406,17 @@ Faulty.init do |config|
 end
 ```
 
+### Other Built-in Listeners
+
+In addition to the log and callback listeners, Faulty intends to implement
+built-in service-specific handlers to make it easy to integrate with monitoring
+and reporting software.
+
+- `Faulty::Events::HoneybadgerListener`: Reports circuit and backend errors to
+  the Honeybadger error reporting service.
+
+### Custom Listeners
+
 You can implement your own listener by following the documentation in
 `Faulty::Events::ListenerInterface`. For example:
 
@@ -405,7 +466,7 @@ Faulty.init do |config|
     storage.key_prefix = 'faulty'
 
     # A string to separate the parts of the redis key
-    storage.key_separator: ':'
+    storage.key_separator = ':'
 
     # The maximum number of circuit runs that will be stored
     storage.max_sample_size = 100
@@ -416,7 +477,7 @@ Faulty.init do |config|
 end
 ```
 
-### Listing Circuits
+## Listing Circuits
 
 For monitoring or debugging, you may need to retrieve a list of all circuit
 names. This is possible with `Faulty.list_circuits` (or the equivalent method on
@@ -432,6 +493,36 @@ statuses = Faulty.list_circuits.map do |name|
 end
 ```
 
+## Locking Circuits
+
+It is possible to lock a circuit open or closed. A circuit that is locked open
+will never execute its block, and always raise an `Faulty::OpenCircuitError`.
+This is useful in cases where you need to manually disable a dependency
+entirely. If a cached value is available, that will be returned from the circuit
+until it expires, even outside its refresh period.
+
+```ruby
+Faulty.circuit(:broken_api).lock_open!
+```
+
+A circuit that is locked closed will never trip. This is useful in cases where a
+circuit is continuously tripping incorrectly. If a cached value is available, it
+will have the same behavior as an unlocked circuit.
+
+```ruby
+Faulty.circuit(:false_positive).lock_closed!
+```
+
+To remove a lock of either type:
+
+```ruby
+Faulty.circuit(:fixed).unlock!
+```
+
+Locking or unlocking a circuit has no concurrency guarantees, so it's not
+recommended to lock or unlock circuits from production code. Instead, locks are
+intended as an emergency tool for troubleshooting and debugging.
+
 ## Scopes
 
 It is possible to have multiple configurations of Faulty running within the same
@@ -545,15 +636,34 @@ would be useful for other users.
 Faulty has its own opinions about how to implement a circuit breaker in Ruby,
 but there are and have been many other options:
 
-- [circuitbox](https://github.com/yammer/circuitbox)
-- [circuit_breaker-ruby](https://github.com/scripbox/circuit_breaker-ruby)
-- [stoplight](https://github.com/orgsync/stoplight) (currently unmaintained)
+### Currently Active
+
+- [semian](https://github.com/Shopify/semian): A resiliency toolkit that
+  includes circuit breakers. It uses adapters to auto-wire circuits, and it has
+  only host-local storage by design.
+- [circuitbox](https://github.com/yammer/circuitbox): Similar in function to
+  Faulty, but with a different API. It uses Moneta to abstract circuit storage
+  to allow any key-value store.
+
+### Previous Work
+
+- [circuit_breaker-ruby](https://github.com/scripbox/circuit_breaker-ruby) (no
+  recent activity)
+- [stoplight](https://github.com/orgsync/stoplight) (unmaintained)
 - [circuit_breaker](https://github.com/wooga/circuit_breaker) (archived)
 - [simple_circuit_breaker](https://github.com/soundcloud/simple_circuit_breaker)
   (unmaintained)
 - [breaker](https://github.com/ahawkins/breaker) (unmaintained)
 - [circuit_b](https://github.com/alg/circuit_b) (unmaintained)
 
+### Faulty's Unique Features
+
+- Simple API but configurable for advanced users
+- Pluggable storage backends (circuitbox also has this)
+- Global, or local configuration with scopes
+- Integrated caching support tailored for fault-tolerance
+- Manually lock circuits open or closed
+
 [api docs]: https://www.rubydoc.info/github/ParentSquare/faulty/master
 [martin fowler]: https://www.martinfowler.com/bliki/CircuitBreaker.html
 [hystrix]: https://github.com/Netflix/Hystrix/wiki/How-it-Works

data/faulty.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '>= 1.17', '< 3'
   spec.add_development_dependency 'byebug', '~> 11.0'
   spec.add_development_dependency 'connection_pool', '~> 2.0'
+  spec.add_development_dependency 'honeybadger', '>= 2.0'
   spec.add_development_dependency 'irb', '~> 1.0'
   spec.add_development_dependency 'redcarpet', '~> 3.5'
   spec.add_development_dependency 'redis', '~> 3.0'

data/lib/faulty/events.rb

@@ -21,5 +21,6 @@ module Faulty
 end
 
 require 'faulty/events/callback_listener'
-require 'faulty/events/notifier'
+require 'faulty/events/honeybadger_listener'
 require 'faulty/events/log_listener'
+require 'faulty/events/notifier'

data/lib/faulty/events/honeybadger_listener.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Faulty
+  module Events
+    # Reports circuit errors to Honeybadger
+    #
+    # https://www.honeybadger.io/
+    #
+    # The honeybadger gem must be available.
+    class HoneybadgerListener
+      # (see ListenerInterface#handle)
+      def handle(event, payload)
+        return unless EVENTS.include?(event)
+
+        send(event, payload) if respond_to?(event, true)
+      end
+
+      private
+
+      def circuit_failure(payload)
+        _circuit_error(payload)
+      end
+
+      def circuit_opened(payload)
+        _circuit_error(payload)
+      end
+
+      def circuit_reopened(payload)
+        _circuit_error(payload)
+      end
+
+      def cache_failure(payload)
+        Honeybadger.notify(payload[:error], context: {
+          action: payload[:action],
+          key: payload[:key]
+        })
+      end
+
+      def storage_failure(payload)
+        Honeybadger.notify(payload[:error], context: {
+          action: payload[:action],
+          circuit: payload[:circuit]&.name
+        })
+      end
+
+      def _circuit_error(payload)
+        Honeybadger.notify(payload[:error], context: {
+          circuit: payload[:circuit].name
+        })
+      end
+    end
+  end
+end

data/lib/faulty/events/notifier.rb

@@ -11,6 +11,9 @@ module Faulty
 
       # Notify all listeners of an event
       #
+      # If a listener raises an error while handling an event, that error will
+      # be captured and written to STDERR.
+      #
       # @param event [Symbol] The event name
       # @param payload [Hash] A hash of event payload data. The payload keys
       #   differ between events, but should be consistent across calls for a
@@ -18,7 +21,13 @@ module Faulty
       def notify(event, payload)
         raise ArgumentError, "Unknown event #{event}" unless EVENTS.include?(event)
 
-        @listeners.each { |l| l.handle(event, payload) }
+        @listeners.each do |listener|
+          begin
+            listener.handle(event, payload)
+          rescue StandardError => e
+            warn "Faulty listener #{listener.class.name} crashed: #{e.message}"
+          end
+        end
       end
     end
   end

data/lib/faulty/storage/memory.rb

@@ -83,7 +83,7 @@ module Faulty
         memory = fetch(circuit)
         memory.runs.borrow do |runs|
           runs.push([time, success])
-          runs.pop if runs.size > options.max_sample_size
+          runs.shift if runs.size > options.max_sample_size
         end
         memory.status(circuit.options)
       end

data/lib/faulty/version.rb

@@ -3,6 +3,6 @@
 module Faulty
   # The current Faulty version
   def self.version
-    Gem::Version.new('0.1.2')
+    Gem::Version.new('0.1.3')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-28 00:00:00.000000000 Z
+date: 2020-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: honeybadger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: irb
   requirement: !ruby/object:Gem::Requirement
@@ -268,6 +282,7 @@ files:
 - lib/faulty/error.rb
 - lib/faulty/events.rb
 - lib/faulty/events/callback_listener.rb
+- lib/faulty/events/honeybadger_listener.rb
 - lib/faulty/events/listener_interface.rb
 - lib/faulty/events/log_listener.rb
 - lib/faulty/events/notifier.rb