circuitbox 2.0.0.pre5 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 541c5e674d62681f13021254d4304c4903e2812915c59b74fcb419468f608c9d
-  data.tar.gz: 97fdbeedc5ac6aa8aa249ca92a1202175e8bbd3f777c4c5211583130aecf5b0d
+  metadata.gz: 206d564d542dc903001281052403166a100732fc9b2b0f1f0999601e4543893b
+  data.tar.gz: '0095c6111ab38a311cb48ae8df82906185cef5b2b3ee8e761f08c9bacfb95782'
 SHA512:
-  metadata.gz: 2466098850251fab23dd6be74a292150ba8eda1e27c3ef1fefcc79aab36dedc170daf4292ae3e9d20ea49468bb487855ce4d3bd77aa7ef1ec8b3ba18bd52d1c6
-  data.tar.gz: a62d7c7a283ce4adcec0c73b69db7de8ca982f493369a7ac6534bfc9641de2bc909b8294bb634913b64c1f454861488595e0f103672fa6cc448c7f6beaa8c170
+  metadata.gz: 314fe848d0dfbcc1aab3b71f469349b950b3dd117df76fcc88d2e37da574ce03000a9f6b62f712d7e4d1b069d5428d12d75d29bb91410ed4c0a83d8a6bfd41ae
+  data.tar.gz: 613f95add06ef602442bcde07b62f12d2fdee60c5713fcb72b71d09ddcbe8085340ffdcbd9ad83161cf31b55536c2e9ec5cce0beaddfac3737fd7a39c62aec3f

data/README.md

@@ -2,10 +2,16 @@
 
 ![Tests](https://github.com/yammer/circuitbox/workflows/Tests/badge.svg) [![Gem Version](https://badge.fury.io/rb/circuitbox.svg)](https://badge.fury.io/rb/circuitbox)
 
-Circuitbox is a Ruby circuit breaker gem. It protects your application from failures of its service dependencies. It wraps calls to external services and monitors for failures in one minute intervals. Once more than 10 requests have been made with a 50% failure rate, Circuitbox stops sending requests to that failing service for one minute. This helps your application gracefully degrade.
+Circuitbox is a Ruby circuit breaker gem.
+It protects your application from failures of its service dependencies.
+It wraps calls to external services and monitors for failures in one minute intervals.
+Using a circuit's defaults once more than 5 requests have been made with a 50% failure rate, Circuitbox stops sending requests to that failing service for 90 seconds.
+This helps your application gracefully degrade.
+
 Resources about the circuit breaker pattern:
 * [http://martinfowler.com/bliki/CircuitBreaker.html](http://martinfowler.com/bliki/CircuitBreaker.html)
-* [https://github.com/Netflix/Hystrix/wiki/How-it-Works#CircuitBreaker](https://github.com/Netflix/Hystrix/wiki/How-it-Works#CircuitBreaker)
+
+*Upgrading to 2.x? See [2.0 upgrade](docs/2.0-upgrade.md)*
 
 ## Usage
 
@@ -43,13 +49,17 @@ Using the `run` method will throw an exception when the circuit is open or the u
 ```
 
 ## Global Configuration
-Circuitbox has defaults for circuit_store and notifier.
-This can be configured through ```Circuitbox.configure```.
-The circuit cache used by ```Circuitbox.circuit``` will be cleared after running ```Circuitbox.configure```.
-This means when accessing the circuit through ```Circuitbox.circuit``` any custom configuration options should always be given.
 
-Any circuit created manually through ```Circuitbox::CircuitBreaker``` before updating the configuration
-will need to be recreated to pick up the new defaults.
+Circuitbox defaults can be configured through ```Circuitbox.configure```.
+There are two defaults that can be configured:
+* `default_circuit_store` - Defaults to a `Circuitbox::MemoryStore`. This can be changed to a compatible Moneta store.
+* `default_notifier` - Defaults to `Circuitbox::Notifier::ActiveSupport` if `ActiveSupport::Notifications` is defined, otherwise defaults to `Circuitbox::Notifier::Null`
+
+After configuring circuitbox through `Circuitbox.configure`, the internal circuit cache of `Circuitbox.circuit` is cleared.
+
+Any circuit created manually through ```Circuitbox::CircuitBreaker``` before updating the configuration will need to be recreated to pick up the new defaults.
+
+The following is an example Circuitbox configuration:
 
 ```ruby
   Circuitbox.configure do |config|
@@ -86,7 +96,6 @@ class ExampleServiceClient
       error_threshold:  50,
 
       # Customized notifier
-      # overrides the default
       # this overrides what is set in the global configuration
       notifier: Notifier.new
     })
@@ -107,12 +116,13 @@ Circuitbox.circuit(:yammer, {
 
 Holds all the relevant data to trip the circuit if a given number of requests
 fail in a specified period of time. Circuitbox also supports
-[Moneta](https://github.com/minad/moneta). As moneta is not a dependency of circuitbox
+[Moneta](https://github.com/moneta-rb/moneta). As moneta is not a dependency of circuitbox
 it needs to be loaded prior to use. There are a lot of moneta stores to choose from but
 some pre-requisits need to be satisfied first:
 
 - Needs to support increment, this is true for most but not all available stores.
 - Needs to support expiry.
+- Needs to support bulk read.
 - Needs to support concurrent access if you share them. For example sharing a
   KyotoCabinet store across process fails because the store is single writer
   multiple readers, and all circuits sharing the store need to be able to write.
@@ -120,52 +130,7 @@ some pre-requisits need to be satisfied first:
 
 ## Notifications
 
-Circuitbox has two built in notifiers, null and active support.
-The active support notifier is used if `ActiveSupport::Notifications` is defined when circuitbox is loaded.
-If `ActiveSupport::Notifications` is not defined the null notifier is used.
-The null notifier does not send notifications anywhere.
-
-The default notifier can be changed to use a specific built in notifier or a custom notifier when [configuring circuitbox](#global-configuration).
-
-### ActiveSupport
-Usage example:
-
-**Circuit open/close:**
-
-```ruby
-ActiveSupport::Notifications.subscribe('open.circuitbox') do |_name, _start, _finish, _id, payload|
-  circuit_name = payload[:circuit]
-  Rails.logger.warn("Open circuit for: #{circuit_name}")
-end
-ActiveSupport::Notifications.subscribe('close.circuitbox') do |_name, _start, _finish, _id, payload|
-  circuit_name = payload[:circuit]
-  Rails.logger.info("Close circuit for: #{circuit_name}")
-end
-```
-
-**Circuit run:**
-
-```ruby
-ActiveSupport::Notifications.subscribe('run.circuitbox') do |*args|
-  event = ActiveSupport::Notifications::Event.new(*args)
-  circuit_name = event.payload[:circuit_name]
-  
-  Rails.logger.info("Circuit: #{circuit_name} Runtime: #{event.duration}")
-end
-```
-
-**Circuit Warnings:**
-In case of misconfiguration, circuitbox will fire a `warning.circuitbox`
-notification.
-
-```ruby
-ActiveSupport::Notifications.subscribe('warning.circuitbox') do |_name, _start, _finish, _id, payload|
-  circuit_name = payload[:circuit]
-  warning      = payload[:message]
-  Rails.logger.warning("Circuit warning for: #{circuit_name} Message: #{warning}")
-end
-
-```
+See [Circuit Notifications](docs/circuit_notifications.md)
 
 ## Faraday
 

data/lib/circuitbox/configuration.rb

@@ -19,16 +19,30 @@ class Circuitbox
       end
     end
 
+    # Configure Circuitbox's defaults
+    # After configuring the cached circuits are cleared
+    #
+    # @yieldparam [Circuitbox::Configuration] Circuitbox configuration
+    #
     def configure
       yield self
       clear_cached_circuits!
       nil
     end
 
+    # Circuit store used by circuits that are not configured with a specific circuit store
+    # Defaults to Circuitbox::MemoryStore
+    #
+    # @return [Circuitbox::MemoryStore, Moneta] Circuit store
     def default_circuit_store
       @default_circuit_store ||= MemoryStore.new
     end
 
+    # Notifier used by circuits that are not configured with a specific notifier.
+    # If ActiveSupport::Notifications is defined it defaults to Circuitbox::Notifier::ActiveSupport
+    # Otherwise it defaults to Circuitbox::Notifier::Null
+    #
+    # @return [Circuitbox::Notifier::ActiveSupport, Circuitbox::Notifier::Null] Notifier
     def default_notifier
       @default_notifier ||= if defined?(ActiveSupport::Notifications)
                               Notifier::ActiveSupport.new

data/lib/circuitbox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Circuitbox
-  VERSION = '2.0.0.pre5'
+  VERSION = '2.0.0'
 end

data/lib/circuitbox.rb

@@ -11,6 +11,28 @@ class Circuitbox
   extend Configuration
 
   class << self
+    # @overload circuit(service_name, options = {})
+    #   Returns a Circuitbox::CircuitBreaker for the given service_name
+    #
+    #   @param service_name [String, Symbol] Name of the service
+    #     Mixing Symbols/Strings for the same service (:test/'test') will result in
+    #     multiple circuits being created that point to the same service.
+    #   @param options [Hash] Options for the circuit (See Circuitbox::CircuitBreaker#initialize options)
+    #     Any configuration options should always be passed when calling this method.
+    #   @return [Circuitbox::CircuitBreaker] CircuitBreaker for the given service_name
+    #
+    # @overload circuit(service_name, options = {}, &block)
+    #   Runs the circuit with the given block
+    #   The circuit's run method is called with `exception` set to false
+    #
+    #   @param service_name [String, Symbol] Name of the service
+    #     Mixing Symbols/Strings for the same service (:test/'test') will result in
+    #     multiple circuits being created that point to the same service.
+    #   @param options [Hash] Options for the circuit (See Circuitbox::CircuitBreaker#initialize options)
+    #     Any configuration options should always be passed when calling this method.
+    #
+    #   @return [Object] The result of the block
+    #   @return [nil] If the circuit is open
     def circuit(service_name, options, &block)
       circuit = find_or_create_circuit_breaker(service_name, options)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: circuitbox
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre5
+  version: 2.0.0
 platform: ruby
 authors:
 - Fahim Ferdous
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-06 00:00:00.000000000 Z
+date: 2023-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -250,9 +250,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.6
 signing_key: