faulty 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67b20b18497c36c64f2a3dc7d16de761af0c22c0a38d93f3101534a5ac85e26d
-  data.tar.gz: 3d880b9a143939ab8ef4a22393c4bb8fa2b724d0bb02986bf52ac06ac3e5cf0b
+  metadata.gz: 55bf688c3615a59f51103633db0902abf3458324945ab855894e5975981868f5
+  data.tar.gz: dab412aad317a79364782a85c2a6a184e55fa2214cd966655d74eeab69e248c0
 SHA512:
-  metadata.gz: 379c17805a9c647d71fac74e5190b6c077ef55c6d42b797f68dff008e602b005053a86c0c41572c761f32df25436b918e68f61049adf613e3a61a1a779d0364d
-  data.tar.gz: a7ff7c19ec6759282ec0f17ffe72f2a56aa5a41d83221ca53040f676951f8346fa2fa83fbe20c71a4ef843be9d2dfbbe0d23380d94342173e8bf41632d74ad12
+  metadata.gz: 7527a23df0c042ea317e99b8fafdf8c8f96ac5f9f68323ba4c4a2901f8e32dc7ca2b7c62b6b7197e446985eab6901f85dd41c6463407ae3632d86e022626d733
+  data.tar.gz: 7e3d48b82905b0ad2303449a532e85736a0681fa4dcb8a5f9ee64e6ffd10c76fdc760ac97aa9dd882f7a019d335440f9d91f0ba1efbb92f978c5e9e43c5b977a

data/.gitignore

@@ -2,6 +2,7 @@
 /Gemfile.lock
 /vendor/
 /.ruby-version
+/*.gem
 
 /coverage/
 /doc/

data/.rubocop.yml

@@ -29,6 +29,9 @@ Layout/LineLength:
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
+Layout/RescueEnsureAlignment:
+  Enabled: false
+
 Lint/RaiseException:
   Enabled: true
 
@@ -59,6 +62,9 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Max: 30
 
+Naming/MethodParameterName:
+  MinNameLength: 1
+
 Style/Documentation:
   Enabled: false
 

data/.travis.yml

@@ -6,6 +6,8 @@ rvm:
   - 2.5
   - 2.6
   - 2.7
+  - jruby
+  - truffleruby
 
 env:
   global:
@@ -22,8 +24,8 @@ before_script:
   - ./cc-test-reporter before-build
 
 script:
-  - bin/rubocop
-  - bin/rspec --format doc
+  - bundle exec rubocop
+  - bundle exec rspec --format doc
   - bin/check-version
 
 after_script:

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+## Release v0.2.0
+
+* Remove Scopes and replace them with Faulty instances #9
+
+### Breaking Changes
+
+* `Faulty::Scope` has been removed. Use `Faulty.new` instead.
+* `Faulty` is now a class, not a module
+
+## Release v0.1.5
+
+* Fix redis storage to expire state key when using CAS #8
+
+## Release v0.1.4
+
+* Improve spec coverage for supporting classes #6
+* Fix redis bug where concurrent CAS requests could crash #7
+
+## 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 #2
+
+## Release v0.1.1
+
+* Fix a crash when Storage::FaultTolerantProxy created a status stub #1
+
+## Release v0.1.0
+
+Initial public release

data/Gemfile

@@ -3,3 +3,20 @@
 source 'https://rubygems.org'
 
 gemspec
+
+# We add non-essential gems like debugging tools and CI dependencies
+# here. This also allows us to use conditional dependencies that depend on the
+# platform
+
+not_jruby = %i[ruby mingw x64_mingw].freeze
+
+gem 'activesupport', '>= 4.2'
+gem 'bundler', '>= 1.17', '< 3'
+gem 'byebug', platforms: not_jruby
+gem 'irb', '~> 1.0'
+gem 'redcarpet', '~> 3.5', platforms: not_jruby
+gem 'rspec_junit_formatter', '~> 0.4'
+# For now, code climate doesn't support simplecov 0.18
+# https://github.com/codeclimate/test-reporter/issues/413
+gem 'simplecov', '>= 0.17.1', '< 0.18'
+gem 'yard', '~> 0.9.25', platforms: not_jruby

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
@@ -158,11 +203,12 @@ In addition to the classic circuit breaker design, Faulty implements caching
 that is integrated with the circuit state. See [Caching](#caching) for more
 detail.
 
-## Global Configuration
+## Configuration
 
-`Faulty.init` can set the following global configuration options. This example
-illustrates the default values. It is also possible to define multiple
-non-global configuration scopes (see [Scopes](#scopes)).
+Faulty can be configured with the following configuration options. This example
+illustrates the default values. In the first example, we configure Faulty
+globally. The second example shows the same configuration using an instance of
+Faulty instead of global configuration.
 
 ```ruby
 Faulty.init do |config|
@@ -188,6 +234,25 @@ Faulty.init do |config|
 end
 ```
 
+Here is the same configuration using an instance of `Faulty`. This is a more
+object-oriented approach.
+
+```ruby
+faulty = Faulty.new do |config|
+  config.cache = Faulty::Cache::Default.new
+  config.storage = Faulty::Storage::Memory.new
+  config.listeners = [Faulty::Events::LogListener.new]
+  config.notifier = Faulty::Events::Notifier.new(config.listeners)
+end
+```
+
+Most of the examples in this README use the global Faulty class methods, but
+they work the same way when using an instance. Just substitute your instance
+instead of `Faulty`. There is no preferred way to use Faulty. Choose whichever
+configuration mechanism works best for your application. Also see
+[Multiple Configurations](#multiple-configurations) if your application needs
+to set different options in different scenarios.
+
 For all Faulty APIs that have configuration, you can also pass in an options
 hash. For example, `Faulty.init` could be called like this:
 
@@ -199,9 +264,9 @@ Faulty.init(cache: Faulty::Cache::Null.new)
 
 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.
+the process exits. If you're using [multiple configurations](#multiple-configurations),
+the options are retained within the context of each instance. All options given
+after the first call to `Faulty.circuit` (or `Faulty#circuit`) are ignored.
 
 This is because the circuit objects themselves are internally memoized, and are
 read-only once created.
@@ -262,8 +327,8 @@ Faulty.circuit(:api, cache_expires_in: 1800)
 
 Faulty integrates caching into it's circuits in a way that is particularly
 suited to fault-tolerance. To make use of caching, you must specify the `cache`
-configuration option when initializing Faulty or creating a scope. If you're
-using Rails, this is automatically set to the Rails cache.
+configuration option when initializing Faulty or creating a new Faulty instance.
+If you're using Rails, this is automatically set to the Rails cache.
 
 Once your cache is configured, you can use the `cache` parameter when running
 a circuit to specify a cache key:
@@ -338,12 +403,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 +426,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 +486,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,11 +497,11 @@ 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
-your [scope](#scopes)).
+names. This is possible with `Faulty.list_circuits` (or `Faulty#list_circuits`
+if you're using an instance).
 
 You can get a list of all circuit statuses by mapping those names to their
 status objects. Be careful though, since this could cause performance issues for
@@ -432,73 +513,103 @@ statuses = Faulty.list_circuits.map do |name|
 end
 ```
 
-## Scopes
+## 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.
+
+## Multiple Configurations
 
 It is possible to have multiple configurations of Faulty running within the same
-process. The most common configuration is to simply use `Faulty.init` to
+process. The most common setup is to simply use `Faulty.init` to
 configure Faulty globally, however it is possible to have additional
-configurations using scopes.
+configurations.
 
-### The default scope
+### The default instance
 
-When you call `Faulty.init`, you are actually creating the default scope. You
-can access this scope directly by calling `Faulty.default`.
+When you call `Faulty.init`, you are actually creating the default instance of
+`Faulty`. You can access this instance directly by calling `Faulty.default`.
 
 ```ruby
-# We create the default scope
+# We create the default instance
 Faulty.init
 
-# Access the default scope
-scope = Faulty.default
+# Access the default instance
+faulty = Faulty.default
 
-# Alternatively, access the scope by name
-scope = Faulty[:default]
+# Alternatively, access the instance by name
+faulty = Faulty[:default]
 ```
 
-You can rename the default scope if desired:
+You can rename the default instance if desired:
 
 ```ruby
 Faulty.init(:custom_default)
 
-scope = Faulty.default
-scope = Faulty[:custom_default]
+instance = Faulty.default
+instance = Faulty[:custom_default]
 ```
 
-### Multiple Scopes
+### Multiple Instances
 
-If you want multiple scopes, but want global, thread-safe access to
+If you want multiple instance, but want global, thread-safe access to
 them, you can use `Faulty.register`:
 
 ```ruby
-api_scope = Faulty::Scope.new do |config|
+api_faulty = Faulty.new do |config|
   # This accepts the same options as Faulty.init
 end
 
-Faulty.register(:api, api_scope)
+Faulty.register(:api, api_faulty)
 
-# Now access the scope globally
+# Now access the instance globally
 Faulty[:api]
 ```
 
 When you call `Faulty.circuit`, that's the same as calling
-`Faulty.default.circuit`, so you can apply the same API to any other Faulty
-scope:
+`Faulty.default.circuit`, so you can apply the same principal to any other
+registered Faulty instance:
 
 ```ruby
 Faulty[:api].circuit(:api_circuit).run { 'ok' }
 ```
 
-### Standalone Scopes
+### Standalone Instances
 
-If you choose, you can use Faulty scopes without registering them globally. This
-could be useful if you prefer dependency injection over global state.
+If you choose, you can use Faulty instances without registering them globally.
+This is more object-oriented and is necessary if you use dependency injection.
 
 ```ruby
-faulty = Faulty::Scope.new
+faulty = Faulty.new
 faulty.circuit(:standalone_circuit)
 ```
 
-Calling `circuit` on the scope still has the same memoization behavior that
+Calling `#circuit` on the instance still has the same memoization behavior that
 `Faulty.circuit` has, so subsequent calls to the same circuit will return a
 memoized circuit object.
 
@@ -545,15 +656,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 object-oriented configuration with multiple instances
+- 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