faulty 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1da265b4bb2e4ae865726930ec3855a03d31c3b47c92b9ef08d7519cdb9d9d9
-  data.tar.gz: a2fdbb6d1ccdfb7be6c68467ce45a802644ef4f9a61769e8b7387d626307facd
+  metadata.gz: 7e68341d29ccefb2a4fa4c265f3f2d5ec37371d37cb41d5a186b3f25d2130b46
+  data.tar.gz: 56e659d66871738e8818c4874102de04ef97873cb0d1c444d58259c875b21378
 SHA512:
-  metadata.gz: 2ad680693b76db3f3d420d7ded71269c8ad669c23bffa0e4ab598d8d0772955c70479d1497ea51b7aa9691b8438e06bc83ff13d4f3e3f6842a3327971dcbb4d3
-  data.tar.gz: 2890441590276ecd72e16ee9866955b027a3e1df26907f9cc71a94f3f1161c01ea30665860bcf526fe871e84a10a7c9c728c050bbf961d8b9d670b4a6fb4bbfa
+  metadata.gz: 7db7b915923132bd1e5d234245cc5a3adb5988013f4baf8fadc59f89bacfde6828310954f0d6ea9da59ed18c97b9224e3d0f9e02ce2700ef9f6240e8b14d3706
+  data.tar.gz: 578d4f0473ff58b1a9f6aeb3d2eab4be158de92943d6147e1521212068578ecd190094e17b02838919561d43b477b197344804478aa8288e70d0c30b26f85fd9

data/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+---
+name: CI
+on:
+  push:
+    tags: ['v*']
+    branches: [master]
+  pull_request:
+    branches: ['**']
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        redis: [4]
+        ruby: [2.3, 2.4, 2.5, 2.6, 2.7, 3.0, jruby-9.2.10, truffleruby-20.2.0]
+        include:
+          - redis: 3
+            ruby: 2.7
+    services:
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rubocop
+        if: matrix.ruby == '2.7'
+      - run: bundle exec rspec --format doc
+      - name: Run codacy-coverage-reporter
+        uses: codacy/codacy-coverage-reporter-action@master
+        with:
+          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+          coverage-reports: coverage/lcov/faulty.lcov
+      - run: bin/check-version
+
+  release:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dawidd6/action-publish-gem@v1
+        with:
+          api_key: ${{secrets.RUBYGEMS_API_KEY}}

data/.rubocop.yml

@@ -29,6 +29,9 @@ Layout/LineLength:
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
+Layout/RescueEnsureAlignment:
+  Enabled: false
+
 Lint/RaiseException:
   Enabled: true
 
@@ -44,6 +47,9 @@ RSpec/FilePath:
 RSpec/NamedSubject:
   Enabled: false
 
+RSpec/MessageSpies:
+  Enabled: false
+
 RSpec/MultipleExpectations:
   Enabled: false
 
@@ -59,6 +65,9 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Max: 30
 
+Naming/MethodParameterName:
+  MinNameLength: 1
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,10 +1,58 @@
+## Release v0.4.0
+
+* Switch from Travis CI to GitHub actions #11 justinhoward
+* Only run rubocop for Ruby 2.7 in CI #12 justinhoward
+* Explicitly add support for Redis 3 and 4 #15 justinhoward
+* Allow setting default circuit options on Faulty instances #16 justinhoward
+* Switch to codacy for quality metrics #17 justinhoward
+* Small logic fix to README #19 silasb
+* Fix Redis storage dependency on ConnectionPool #21 justinhoward
+* Allow passing custom circuit to AutoWire #22 justinhoward
+
+### Breaking Changes
+
+AutoWire.new is replaced with AutoWire.wrap and no longer creates an instance
+of AutoWire.
+
+## Release v0.3.0
+
+* Add tools for backend fault-tolerance #10
+  * CircuitProxy for wrapping storage in an internal circuit
+  * FallbackChain storage backend for falling back to stable storage
+  * Timeout warnings for Redis backend
+  * AutoWire wrappers for automatically configuring storage and cache
+  * Better documentation for fault-tolerance
+
+## 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
+* 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/Gemfile

@@ -3,3 +3,25 @@
 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'
+gem 'simplecov', '>= 0.17.1'
+# 0.8 is incompatible with simplecov < 0.18
+# https://github.com/fortissimo1997/simplecov-lcov/pull/25
+gem 'simplecov-lcov', '~> 0.7', '< 0.8'
+gem 'yard', '~> 0.9.25', platforms: not_jruby
+
+if ENV['REDIS_VERSION']
+  gem 'redis', "~> #{ENV['REDIS_VERSION']}"
+end

data/README.md

@@ -1,19 +1,100 @@
 # Faulty
 
 [![Gem Version](https://badge.fury.io/rb/faulty.svg)](https://badge.fury.io/rb/faulty)
-[![Build Status](https://travis-ci.org/ParentSquare/faulty.svg?branch=master)](https://travis-ci.org/ParentSquare/faulty)
-[![Code Climate](https://codeclimate.com/github/ParentSquare/faulty/badges/gpa.svg)](https://codeclimate.com/github/ParentSquare/faulty)
-[![Test Coverage](https://codeclimate.com/github/ParentSquare/faulty/badges/coverage.svg)](https://codeclimate.com/github/ParentSquare/faulty)
+[![CI](https://github.com/ParentSquare/faulty/workflows/CI/badge.svg)](https://github.com/ParentSquare/faulty/actions?query=workflow%3ACI+branch%3Amaster)
+[![Code Quality](https://app.codacy.com/project/badge/Grade/16bb1df1569a4ddba893a866673dac2a)](https://www.codacy.com/gh/ParentSquare/faulty/dashboard?utm_source=github.com&utm_medium=referral&utm_content=ParentSquare/faulty&utm_campaign=Badge_Grade)
+[![Code Coverage](https://app.codacy.com/project/badge/Coverage/16bb1df1569a4ddba893a866673dac2a)](https://www.codacy.com/gh/ParentSquare/faulty/dashboard?utm_source=github.com&utm_medium=referral&utm_content=ParentSquare/faulty&utm_campaign=Badge_Coverage)
 [![Inline docs](http://inch-ci.org/github/ParentSquare/faulty.svg?branch=master)](http://inch-ci.org/github/ParentSquare/faulty)
 
 Fault-tolerance tools for ruby based on [circuit-breakers][martin fowler].
 
+**Without Faulty**
+
+External dependencies like APIs can start failing at any time When they do, it
+could cause cascading failures in your application.
+
 ```ruby
-users = Faulty.circuit(:api).try_run do
+# The application will always try to execute this even if the API
+# fails repeatedly
+api.users
+```
+
+**With Faulty**
+
+Faulty monitors errors inside this block and will "trip" a circuit if your
+threshold is passed. Once a circuit is tripped, Faulty stops executing this
+block until it recovers. Your application can detect external failures, and
+prevent their effects from degrading overall performance.
+
+```ruby
+users = Faulty.circuit('api').try_run do
+
+  # If this raises an exception, it counts towards the failure rate
+  # The exceptions that count as failures are configurable
+  # All failures will be sent to your event listeners for monitoring
   api.users
+
 end.or_default([])
+# Here we return a stubbed value so the app can continue to function
+# Another strategy is just to re-raise the exception so the app can handle it
+# or use its default error handler
 ```
 
+See [What is this for?](#what-is-this-for) for a more detailed explanation.
+Also see "Release It!: Design and Deploy Production-Ready Software" by
+[Michael T. Nygard][michael nygard] and the
+[Martin Fowler Article][martin fowler] post on circuit breakers.
+
+## Contents
+
+* [Installation](#installation)
+* [API Docs](#api-docs)
+* [Setup](#setup)
+* [Basic Usage](#basic-usage)
+* [What is this for?](#what-is-this-for-)
+* [Configuration](#configuration)
+  + [Configuring the Storage Backend](#configuring-the-storage-backend)
+    - [Memory](#memory)
+    - [Redis](#redis)
+    - [FallbackChain](#fallbackchain)
+    - [Storage::FaultTolerantProxy](#storagefaulttolerantproxy)
+    - [Storage::CircuitProxy](#storagecircuitproxy)
+  + [Configuring the Cache Backend](#configuring-the-cache-backend)
+    - [Null](#null)
+    - [Rails](#rails)
+    - [Cache::FaultTolerantProxy](#cachefaulttolerantproxy)
+    - [Cache::CircuitProxy](#cachecircuitproxy)
+  + [Multiple Configurations](#multiple-configurations)
+    - [The default instance](#the-default-instance)
+    - [Multiple Instances](#multiple-instances)
+    - [Standalone Instances](#standalone-instances)
+* [Working with circuits](#working-with-circuits)
+  + [Running a Circuit](#running-a-circuit)
+    - [With Exceptions](#with-exceptions)
+    - [With Faulty::Result](#with-faultyresult)
+  + [Specifying the Captured Errors](#specifying-the-captured-errors)
+  + [Using the Cache](#using-the-cache)
+  + [Configuring the Circuit Threshold](#configuring-the-circuit-threshold)
+    - [Rate Threshold](#rate-threshold)
+    - [Sample Threshold](#sample-threshold)
+    - [Cool Down](#cool-down)
+  + [Circuit Options](#circuit-options)
+  + [Listing Circuits](#listing-circuits)
+  + [Locking Circuits](#locking-circuits)
+* [Event Handling](#event-handling)
+  + [CallbackListener](#callbacklistener)
+  + [Other Built-in Listeners](#other-built-in-listeners)
+  + [Custom Listeners](#custom-listeners)
+* [How it Works](#how-it-works)
+  + [Caching](#caching)
+  + [Fault Tolerance](#fault-tolerance)
+* [Implementing a Cache Backend](#implementing-a-cache-backend)
+* [Implementing a Storage Backend](#implementing-a-storage-backend)
+* [Alternatives](#alternatives)
+  + [Currently Active](#currently-active)
+  + [Previous Work](#previous-work)
+  + [Faulty's Unique Features](#faulty-s-unique-features)
+
 ## Installation
 
 Add it to your `Gemfile`:
@@ -28,8 +109,10 @@ Or install it manually:
 gem install faulty
 ```
 
-During your app startup, call `Faulty.init`. For Rails, you would do this in
-`config/initializers/faulty.rb`. See [Setup](#setup) for details.
+During your app startup, call
+[`Faulty.init`](https://www.rubydoc.info/gems/faulty/Faulty.init).
+For Rails, you would do this in `config/initializers/faulty.rb`. See
+[Setup](#setup) for details.
 
 ## API Docs
 
@@ -64,21 +147,31 @@ Faulty.init do |config|
 end
 ```
 
+Or use a faulty instance instead for an object-oriented approach
+
+```ruby
+faulty = Faulty.new do
+  config.storage = Faulty::Storage::Redis.new
+end
+```
+
 For a full list of configuration options, see the
-[Global Configuration](#global-configuration) section.
+[Configuration](#configuration) section.
 
 ## Basic Usage
 
-To create a circuit, call `Faulty.circuit`. This can be done as you use the
-circuit, or you can set it up beforehand. Any options passed to the `circuit`
-method are synchronized across threads and saved as long as the process is alive.
+To create a circuit, call
+[`Faulty.circuit`](https://www.rubydoc.info/gems/faulty/Faulty.circuit).
+This can be done as you use the circuit, or you can set it up beforehand. Any
+options passed to the `circuit` method are synchronized across threads and saved
+as long as the process is alive.
 
 ```ruby
-circuit1 = Faulty.circuit(:api, cache_refreshes_after: 1800)
+circuit1 = Faulty.circuit(:api, rate_threshold: 0.6)
 
 # The options from above are also used when called here
 circuit2 = Faulty.circuit(:api)
-circuit2.options.cache_refreshes_after == 1800 # => true
+circuit2.options.rate_threshold == 0.6 # => true
 
 # The same circuit is returned on each consecutive call
 circuit1.equal?(circuit2) # => true
@@ -95,11 +188,12 @@ end
 See [How it Works](#how-it-works) for more details about how Faulty handles
 circuit failures.
 
-If the `run` block above fails, a `Faulty::CircuitError` will be raised. It is
-up to your application to handle that error however necessary or crash. Often
-though, you don't want to crash your application when a circuit fails, but
-instead apply a fallback or default behavior. For this, Faulty provides the
-`try_run` method:
+If the `run` block above fails, a
+[`Faulty::CircuitError`](https://www.rubydoc.info/gems/faulty/Faulty/CircuitError)
+will be raised. It is up to your application to handle that error however
+necessary or crash. Often though, you don't want to crash your application when
+a circuit fails, but instead apply a fallback or default behavior. For this,
+Faulty provides the `try_run` method:
 
 ```ruby
 result = Faulty.circuit(:api).try_run do
@@ -113,11 +207,13 @@ else
 end
 ```
 
-The `try_run` method returns a result type instead of raising errors. See the
-API docs for `Result` for more information. Here we use it to check whether the
-result is `ok?` (not an error). If it is we set the users variable, otherwise we
-set a default of an empty array. This pattern is so common, that `Result` also
-implements a helper method `or_default` to do the same thing:
+The [`try_run`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:try_run)
+method returns a result type instead of raising errors. See the API docs for
+[`Result`](https://www.rubydoc.info/gems/faulty/Faulty/Result) for more
+information. Here we use it to check whether the result is `ok?` (not an error).
+If it is we set the users variable, otherwise we set a default of an empty
+array. This pattern is so common, that `Result` also implements a helper method
+`or_default` to do the same thing:
 
 ```ruby
 users = Faulty.circuit(:api).try_run do
@@ -125,55 +221,83 @@ users = Faulty.circuit(:api).try_run do
 end.or_default([])
 ```
 
-## How it Works
+See [Running a Circuit](#running-a-circuit) for more in-depth examples. Also,
+make sure you have proper [Event Handlers](#event-handling) setup so that you
+can monitor your circuits for failures.
 
-Faulty implements a version of circuit breakers inspired by
-[Martin Fowler's post][martin fowler] on the subject. A few notable features of
-Faulty's implementation are:
+## What is this for?
 
-- Rate-based failure thresholds
-- Integrated caching inspired by Netflix's [Hystrix][hystrix] with automatic
-  cache jitter and error fallback.
-- Event-based monitoring
+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:
 
-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.
+```ruby
+TextApi.send(message)
+```
 
-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
-skipped, and a `Faulty::OpenCircuitError` will be raised.
+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:
 
-After the cool-down has elapsed, the circuit enters the half-open state. In this
-state, Faulty allows a single execution of the block as a test run. If the test
-run succeeds, the circuit is fully opened and the circuit state is reset. If the
-test run fails, the circuit is closed and the cool-down is reset.
+```ruby
+TextApi.send(message, timeout: 5)
+```
 
-Each time the circuit changes state or executes the block, events are raised
-that are sent to the Faulty event notifier. The notifier should be used to track
-circuit failure rates, open circuits, etc.
+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.
 
-In addition to the classic circuit breaker design, Faulty implements caching
-that is integrated with the circuit state. See [Caching](#caching) for more
-detail.
+```ruby
+Faulty.circuit('text_api').run do
+  TextApi.send(message, timeout: 5)
+end
+```
 
-## Global Configuration
+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.
 
-`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)).
+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
+```
+
+## Configuration
+
+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|
   # The cache backend to use. By default, Faulty looks for a Rails cache. If
   # that's not available, it uses an ActiveSupport::Cache::Memory instance.
   # Otherwise, it uses a Faulty::Cache::Null and caching is disabled.
+  # Whatever backend is given here is automatically wrapped in
+  # Faulty::Cache::AutoWire. This adds fault-tolerance features, see the
+  # AutoWire API docs for more details.
   config.cache = Faulty::Cache::Default.new
 
+  # A hash of default options to be used when creating new Circuits.
+  # See Circuit Options below for a full list of these
+  config.circuit_defaults = {}
+
   # The storage backend. By default, Faulty uses an in-memory store. For most
   # production applications, you'll want a more robust backend. Faulty also
   # provides Faulty::Storage::Redis for this.
+  # Whatever backend is given here is automatically wrapped in
+  # Faulty::Storage::AutoWire. This adds fault-tolerance features, see the
+  # AutoWire APi docs for more details. If an array of storage backends is
+  # given, each one will be tried in order until one succeeds.
   config.storage = Faulty::Storage::Memory.new
 
   # An array of event listeners. Each object in the array should implement
@@ -188,6 +312,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:
 
@@ -195,13 +338,471 @@ hash. For example, `Faulty.init` could be called like this:
 Faulty.init(cache: Faulty::Cache::Null.new)
 ```
 
-## Circuit Options
+### Configuring the Storage Backend
+
+A storage backend is required to use Faulty. By default, it uses in-memory
+storage, but Redis is also available, along with a number of wrappers used to
+improve resiliency and fault-tolerance.
+
+#### Memory
+
+The
+[`Faulty::Storage::Memory`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Memory)
+backend is the default storage backend. You may prefer this implementation if
+you want to avoid the complexity and potential failure-mode of cross-network
+circuit storage. The trade-off is that circuit state is only contained within a
+single process and will not be saved across application restarts. Locks will
+also be cleared on restart.
+
+The default configuration:
+
+```ruby
+Faulty.init do |config|
+  config.storage = Faulty::Storage::Memory.new do |storage|
+    # The maximum number of circuit runs that will be stored
+    storage.max_sample_size = 100
+  end
+end
+```
+
+#### Redis
+
+The [`Faulty::Storage::Redis`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Redis)
+backend provides distributed circuit storage using Redis. Although Faulty takes
+steps to reduce risk (See [Fault Tolerance](#fault-tolerance)), using
+cross-network storage does introduce some additional failure modes. To reduce
+this risk, be sure to set conservative timeouts for your Redis connection.
+Setting high timeouts will print warnings to stderr.
+
+The default configuration:
+
+```ruby
+Faulty.init do |config|
+  config.storage = Faulty::Storage::Redis.new do |storage|
+    # The Redis client. Accepts either a Redis instance, or a ConnectionPool
+    # of Redis instances. A low timeout is highly recommended to prevent
+    # cascading failures when evaluating circuits.
+    storage.client = ::Redis.new(timeout: 1)
+
+    # The prefix to prepend to all redis keys used by Faulty circuits
+    storage.key_prefix = 'faulty'
+
+    # A string to separate the parts of the redis key
+    storage.key_separator = ':'
+
+    # The maximum number of circuit runs that will be stored
+    storage.max_sample_size = 100
+
+    # The maximum number of seconds that a circuit run will be stored
+    storage.sample_ttl = 1800
+
+    # The maximum number of seconds to store a circuit. Does not apply to
+    # locks, which are indefinite.
+    storage.circuit_ttl = 604_800 # 1 Week
+
+    # The number of seconds between circuit expirations. Changing this setting
+    # is not recommended. See API docs for more implementation details.
+    storage.list_granularity = 3600
+
+    # If true, disables warnings about recommended client settings like timeouts
+    storage.disable_warnings = false
+  end
+end
+```
+
+#### FallbackChain
+
+The [`Faulty::Storage::FallbackChain`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/FallbackChain)
+backend is a wrapper for multiple prioritized storage backends. If the first
+backend in the chain fails, consecutive backends are tried until one succeeds.
+The recommended use-case for this is to fall back on reliable storage if a
+networked storage backend fails.
+
+For example, you may configure Redis as your primary storage backend, with an
+in-memory storage backend as a fallback:
+
+```ruby
+Faulty.init do |config|
+  config.storage = Faulty::Storage::FallbackChain.new([
+    Faulty::Storage::Redis.new,
+    Faulty::Storage::Memory.new
+  ])
+end
+```
+
+Faulty instances will automatically use a fallback chain if an array is given to
+the `storage` option, so this example is equivalent to the above:
+
+```ruby
+Faulty.init do |config|
+  config.storage = [
+    Faulty::Storage::Redis.new,
+    Faulty::Storage::Memory.new
+  ]
+end
+```
+
+If the fallback chain fails-over to backup storage, circuit states will not
+carry over, so failover could be temporarily disruptive to your application.
+However, any calls to `#lock` or `#unlock` will always be persisted to all
+backends so that locks are maintained during failover.
+
+#### Storage::FaultTolerantProxy
+
+This wrapper is applied to all non-fault-tolerant storage backends by default
+(see the [API docs for `Faulty::Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/AutoWire)).
+
+[`Faulty::Storage::FaultTolerantProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/FaultTolerantProxy)
+is a wrapper that suppresses storage errors and returns sensible defaults during
+failures. If a storage backend is failing, all circuits will be treated as
+closed regardless of locks or previous history.
+
+If you wish your application to use a secondary storage backend instead of
+failing closed, use [`FallbackChain`](#storagefallbackchain).
+
+#### Storage::CircuitProxy
+
+This wrapper is applied to all non-fault-tolerant storage backends by default
+(see the [API docs for `Faulty::Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/AutoWire)).
+
+[`Faulty::Storage::CircuitProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/CircuitProxy)
+is a wrapper that uses an independent in-memory circuit to track failures to
+storage backends. If a storage backend fails continuously, it will be
+temporarily disabled and raise `Faulty::CircuitError`s.
+
+Typically this is used inside a [`FaultTolerantProxy`](#storagefaulttolerantproxy) or
+[`FallbackChain`](#storagefallbackchain) so that these storage failures are handled
+gracefully.
+
+### Configuring the Cache Backend
+
+#### Null
+
+The [`Faulty::Cache::Null`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/Null)
+cache disables caching. It is the default if Rails and ActiveSupport are not
+present.
+
+#### Rails
+
+[`Faulty::Cache::Rails`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/Rails)
+is the default cache if Rails or ActiveSupport are present. If Rails is present,
+it uses `Rails.cache` as the backend. If ActiveSupport is present, but Rails is
+not, it creates a new `ActiveSupport::Cache::MemoryStore` by default.  This
+backend can be used with any `ActiveSupport::Cache`.
+
+```ruby
+Faulty.init do |config|
+  config.cache = Faulty::Cache::Rails.new(
+    ActiveSupport::Cache::RedisCacheStore.new
+  )
+end
+```
+
+#### Cache::FaultTolerantProxy
+
+This wrapper is applied to all non-fault-tolerant cache backends by default
+(see the API docs for `Faulty::Cache::AutoWire`).
+
+[`Faulty::Cache::FaultTolerantProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/FaultTolerantProxy)
+is a wrapper that suppresses cache errors and acts like a null cache during
+failures. Reads always return `nil`, and writes are no-ops.
+
+#### Cache::CircuitProxy
+
+This wrapper is applied to all non-fault-tolerant circuit backends by default
+(see the API docs for `Faulty::Circuit::AutoWire`).
+
+[`Faulty::Cache::CircuitProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/CircuitProxy)
+is a wrapper that uses an independent in-memory circuit to track failures to
+cache backends. If a cache backend fails continuously, it will be
+temporarily disabled and raise `Faulty::CircuitError`s.
+
+Typically this is used inside a
+[`FaultTolerantProxy`](#cachefaulttolerantproxy) so that these cache failures
+are handled gracefully.
+
+### Multiple Configurations
+
+It is possible to have multiple configurations of Faulty running within the same
+process. The most common setup is to simply use `Faulty.init` to
+configure Faulty globally, however it is possible to have additional
+configurations.
+
+#### The default instance
+
+When you call [`Faulty.init`](https://www.rubydoc.info/gems/faulty/Faulty.init),
+you are actually creating the default instance of `Faulty`. You can access this
+instance directly by calling
+[`Faulty.default`](https://www.rubydoc.info/gems/faulty/Faulty.default).
+
+```ruby
+# We create the default instance
+Faulty.init
+
+# Access the default instance
+faulty = Faulty.default
+
+# Alternatively, access the instance by name
+faulty = Faulty[:default]
+```
+
+You can rename the default instance if desired:
+
+```ruby
+Faulty.init(:custom_default)
+
+instance = Faulty.default
+instance = Faulty[:custom_default]
+```
+
+#### Multiple Instances
+
+If you want multiple instance, but want global, thread-safe access to
+them, you can use
+[`Faulty.register`](https://www.rubydoc.info/gems/faulty/Faulty.register):
+
+```ruby
+api_faulty = Faulty.new do |config|
+  # This accepts the same options as Faulty.init
+end
+
+Faulty.register(:api, api_faulty)
+
+# Now access the instance globally
+Faulty[:api]
+```
+
+When you call [`Faulty.circuit`](https://www.rubydoc.info/gems/faulty/Faulty.circuit),
+that's the same as calling `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 Instances
+
+If you choose, you can use Faulty instances without registering them globally by
+simply calling [`Faulty.new`](https://www.rubydoc.info/gems/faulty/Faulty:initialize).
+This is more object-oriented and is necessary if you use dependency injection.
+
+```ruby
+faulty = Faulty.new
+faulty.circuit('standalone_circuit')
+```
+
+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.
+
+
+## Working with circuits
+
+A circuit can be created by calling the `#circuit` method on `Faulty`, or on
+your Faulty instance:
+
+```ruby
+# With global Faulty configuration
+circuit = Faulty.circuit('api')
+
+# Or with a Faulty instance
+circuit = faulty.circuit('api')
+```
+
+### Running a Circuit
+
+You can handle circuit errors either with exceptions, or with a Faulty
+[`Result`](https://www.rubydoc.info/gems/faulty/Faulty/Result). They both have
+the same behavior, but you can choose whatever syntax is more convenient for
+your use-case.
+
+#### With Exceptions
+
+If we want exceptions to be raised, we use the
+[`#run`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:run) method. This
+does not suppress exceptions, only monitors them. If `api.users` raises an
+exception here, it will bubble up to the caller. The exception will be a
+sub-class of [`Faulty::CircuitError`](https://www.rubydoc.info/gems/faulty/Faulty/CircuitError),
+and the error `cause` will be the original error object.
+
+```ruby
+begin
+  Faulty.circuit('api').run do
+    api.users
+  end
+rescue Faulty::CircuitError => e
+  e.cause # The original error
+end
+```
+
+#### With Faulty::Result
+
+Sometimes exception handling is awkward to deal with, and could cause a lot of
+extra boilerplate code. In simple cases, it's can be more concise to allow
+Faulty to capture exceptions. Use the
+[`#try_run`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:try_run) method
+for this.
+
+```ruby
+  result = Faulty.circuit('api').try_run do
+    api.users
+  end
+```
+
+The `result` variable is an instance of
+[`Faulty::Result`](https://www.rubydoc.info/gems/faulty/Faulty/Result). A result
+can either be an error if the circuit failed, or an "ok" value if it succeeded.
+
+You can check whether it's an error with the `ok?` or `error?` method.
+
+```ruby
+if result.ok?
+  users = result.get
+else
+  error = result.error
+end
+```
+
+Sometimes you want your application to crash when a circuit fails, but other
+times, you might want to return a default or fallback value. The `Result` object
+has a method [`#or_default`](https://www.rubydoc.info/gems/faulty/Faulty/Result:or_default)
+to do that.
+
+```ruby
+# Users will be nil if the result is an error
+users = result.or_default
+
+# Users will be an empty array if the result is an error
+users = result.or_default([])
+
+# Users will be the return value of the block
+users = result.or_default do
+  # ...
+end
+```
+
+As we showed in the [Basic Usage](#basic-usage) section, you can put this
+together in a nice one-liner.
+
+```ruby
+Faulty.circuit('api').try_run { api.users }.or_default([])
+```
+
+### Specifying the Captured Errors
+
+By default, Faulty circuits will capture all `StandardError` errors, but
+sometimes you might not want every error to count as a circuit failure. For
+example, an HTTP 404 Not Found response typically should not cause a circuit to
+fail. You can customize the errors that Faulty captures
+
+```ruby
+Faulty.circuit('api', errors: [Net::HTTPServerException]).run do
+  # If this raises any exception other than Net::HTTPServerException
+  # Faulty will not capture it at all, and it will not count as a circuit failure
+  api.find_user(3)
+end
+```
+
+Or, if you'd instead like to specify errors to be excluded:
+
+```ruby
+Faulty.circuit('api', exclude: [Net::HTTPClientException]).run do
+  # If this raises a Net::HTTPClientException, Faulty will not capture it
+  api.find_user(3)
+end
+```
+
+Both options can even be specified together.
+
+```ruby
+Faulty.circuit(
+  'api',
+  errors: [ActiveRecord::ActiveRecordError]
+  exclude: [ActiveRecord::RecordNotFound, ActiveRecord::RecordNotUnique]
+).run do
+  # This only captures ActiveRecord::ActiveRecordError errors, but not
+  # ActiveRecord::RecordNotFound or ActiveRecord::RecordNotUnique errors
+  user = User.find(3)
+  user.save!
+end
+```
+
+### Using the Cache
+
+Circuit runs can be given a cache key, and if they are, the result of the circuit
+block will be cached. Calls to that circuit block will try to fetch from the
+cache, and only execute the block if the cache misses.
+
+```ruby
+Faulty.circuit('api').run(cache: 'all_users') do
+  api.users
+end
+```
+
+The cache will be refreshed (meaning the circuit will be allowed to execute)
+after `cache_refreshes_after` (default 900 second). However, the value remains
+stored in the cache for `cache_expires_in` (default 86400 seconds, 1 day). If
+the circuit fails, the last cached value will be returned even if
+`cache_refreshes_after` has passed.
+
+See the [Caching](#caching) section for more details on Faulty's caching
+strategy.
+
+### Configuring the Circuit Threshold
+
+To configure how a circuit responds to error, use the `cool_down`,
+`rate_threshold` and `sample_threshold` options.
+
+#### Rate Threshold
+
+The first option to look at is `rate_threshold`. This specifies the percentage
+of circuit runs that must fail before a circuit is opened.
+
+```ruby
+# This circuit must fail 70% of the time before the circuit will be tripped
+Faulty.circuit('api', rate_threshold: 0.7).run { api.users }
+```
+
+#### Sample Threshold
+
+We typically don't want circuits to trip immediately if the first execution
+fails. This is why we have the `sample_threshold` option. The circuit will never
+be tripped until we record at least this number of executions.
+
+```ruby
+# This circuit must run 10 times before it is allowed to trip. Those 10 runs
+# can be successes or fails. If at least 70% of them are failures, the circuit
+# will be opened.
+Faulty.circuit('api', sample_threshold: 10, rate_threshold: 0.7).run { api.users }
+```
+
+#### Cool Down
+
+The `cool_down` option specifies how much time to wait after a circuit is
+opened. During this period, the circuit will not be executed. After the cool
+down elapses, the circuit enters the "half open" state, and execution can be
+retried. See [How it Works](#how-it-works).
+
+```ruby
+# If this circuit trips, it will skip executions for 120 seconds before retrying
+Faulty.circuit('api', cool_down: 120).run { api.users }
+```
+
+### Circuit Options
 
 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.
+
+```ruby
+Faulty.circuit('api', rate_threshold: 0.7)
+
+# These options are ignored since with already initialized the circuit
+circuit = Faulty.circuit('api', rate_threshold: 0.3)
+circuit.options.rate_threshold # => 0.7
+```
 
 This is because the circuit objects themselves are internally memoized, and are
 read-only once created.
@@ -209,7 +810,7 @@ read-only once created.
 The following example represents the defaults for a new circuit:
 
 ```ruby
-Faulty.circuit(:api) do |config|
+Faulty.circuit('api') do |config|
   # The cache backend for this circuit. Inherits the global cache by default.
   config.cache = Faulty.options.cache
 
@@ -230,6 +831,10 @@ Faulty.circuit(:api) do |config|
   # circuit to half-open.
   config.cool_down = 300
 
+  # The number of seconds of history that is considered when calculating
+  # the circuit failure rate. The length of the sliding window.
+  config.evaluation_window = 60
+
   # The errors that will be captured by Faulty and used to trigger circuit
   # state changes.
   config.errors = [StandardError]
@@ -237,7 +842,7 @@ Faulty.circuit(:api) do |config|
   # Errors that should be ignored by Faulty and not captured.
   config.exclude = []
 
-  # The event notifier. Inherits the global notifier by default
+  # The event notifier. Inherits the Faulty instance notifier by default
   config.notifier = Faulty.options.notifier
 
   # The minimum failure rate required to trip a circuit
@@ -246,7 +851,8 @@ Faulty.circuit(:api) do |config|
   # The minimum number of runs required before a circuit can trip
   config.sample_threshold = 3
 
-  # The storage backend for this circuit. Inherits the global storage by default
+  # The storage backend for this circuit. Inherits the Faulty instance storage
+  # by default
   config.storage = Faulty.options.storage
 end
 ```
@@ -258,70 +864,62 @@ with an options hash:
 Faulty.circuit(:api, cache_expires_in: 1800)
 ```
 
-## Caching
+### Listing Circuits
 
-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.
+For monitoring or debugging, you may need to retrieve a list of all circuit
+names. This is possible with [`Faulty.list_circuits`](https://www.rubydoc.info/gems/faulty/Faulty.list_circuits)
+(or [`Faulty#list_circuits`](https://www.rubydoc.info/gems/faulty/Faulty:list_circuits)
+if you're using an instance).
 
-Once your cache is configured, you can use the `cache` parameter when running
-a circuit to specify a cache key:
+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
+very large numbers of circuits.
 
 ```ruby
-feed = Faulty.circuit(:rss_feeds)
-  .try_run(cache: "rss_feeds/#{feed}") do
-    fetch_feed(feed)
-  end.or_default([])
+statuses = Faulty.list_circuits.map do |name|
+  Faulty.circuit(name).status
+end
 ```
 
-By default a circuit has the following options:
+### Locking Circuits
 
-- `cache_expires_in`: 86400 (1 day). This is sent to the cache backend and
-  defines how long the cache entry should be stored. After this time elapses,
-  queries will result in a cache miss.
-- `cache_refreshes_after`: 900 (15 minutes). This is used internally by Faulty
-  to indicate when a cache should be refreshed. It does not affect how long the
-  cache entry is stored.
-- `cache_refresh_jitter`: 180 (3 minutes = 20% of `cache_refreshes_after`). The
-  maximum number of seconds to randomly add or subtract from
-  `cache_refreshes_after` when determining whether to refresh a cache entry.
-  This mitigates the "thundering herd" effect caused by many processes
-  simultaneously refreshing the cache.
-
-This code will attempt to fetch an RSS feed protected by a circuit. If the feed
-is within the cache refresh period, then the result will be returned from the
-cache and the block will not be executed regardless of the circuit state.
+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.
 
-If the cache is hit, but outside its refresh period, then Faulty will check the
-circuit state. If the circuit is closed or half-open, then it will run the
-block. If the block is successful, then it will update the circuit, write to the
-cache and return the new value.
+* [`lock_open!`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:lock_open!)
+* [`lock_closed!`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:lock_closed!)
+* [`unlock!`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:unlock!)
 
-However, if the cache is hit and the block fails, then that failure is noted
-in the circuit and Faulty returns the cached value.
+```ruby
+Faulty.circuit('broken_api').lock_open!
+```
 
-If the circuit is open and the cache is hit, then Faulty will always return the
-cached value.
+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.
 
-If the cache query results in a miss, then faulty operates as normal. In the
-code above, if the circuit is closed, the block will be executed. If the block
-succeeds, the cache is refreshed. If the block fails, the default of `[]` will
-be returned.
+```ruby
+Faulty.circuit('false_positive').lock_closed!
+```
 
-## Fault Tolerance
+To remove a lock of either type:
 
-Faulty backends are fault-tolerant by default. Any `StandardError`s raised by
-the storage or cache backends are captured and suppressed. Failure events for
-these errors are sent to the notifier.
+```ruby
+Faulty.circuit('fixed').unlock!
+```
 
-If the storage backend fails, all circuits will default to open. If the cache
-backend fails, all cache queries will miss.
+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.
 
 ## Event Handling
 
 Faulty uses an event-dispatching model to deliver notifications of internal
-events. The full list of events is available from `Faulty::Events::EVENTS`.
+events. The full list of events is available from
+[`Faulty::Events::EVENTS`](https://www.rubydoc.info/gems/faulty/Faulty/Events).
 
 - `cache_failure` -  A cache backend raised an error. Payload: `key`, `action`, `error`
 - `circuit_cache_hit` -  A circuit hit the cache. Payload: `circuit`, `key`
@@ -338,12 +936,18 @@ 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 [`CallbackListener`](https://www.rubydoc.info/gems/faulty/Faulty/Events/CallbackListener)
+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,157 +960,147 @@ Faulty.init do |config|
 end
 ```
 
-You can implement your own listener by following the documentation in
-`Faulty::Events::ListenerInterface`. For example:
+### Other Built-in Listeners
 
-```ruby
-class MyFaultyListener
-  def handle(event, payload)
-    MyNotifier.alert(event, payload)
-  end
-end
-```
+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.
 
-```ruby
-Faulty.init do |config|
-  config.listeners = [MyFaultyListener.new]
-end
-```
+* [`Faulty::Events::LogListener`](https://www.rubydoc.info/gems/faulty/Faulty/Events/LogListener):
+  Logs all circuit events to a specified `Logger` or `$stderr` by default. This
+  is enabled by default if no listeners are specified.
+* [`Faulty::Events::HoneybadgerListener`](https://www.rubydoc.info/gems/faulty/Faulty/Events/HoneybadgerListener):
+  Reports circuit and backend errors to the Honeybadger error reporting service.
 
-## Configuring the Storage Backend
+If your favorite monitoring software is not supported here, please open a PR
+that implements a listener for it.
 
-### Memory
+### Custom Listeners
 
-The `Faulty::Cache::Memory` backend is the default storage backend. The default
-configuration:
+You can implement your own listener by following the documentation in
+[`Faulty::Events::ListenerInterface`](https://www.rubydoc.info/gems/faulty/Faulty/Events/ListenerInterface).
+For example:
 
 ```ruby
-Faulty.init do |config|
-  config.storage = Faulty::Storage::Memory.new do |storage|
-    # The maximum number of circuit runs that will be stored
-    storage.max_sample_size = 100
+class MyFaultyListener
+  def handle(event, payload)
+    MyNotifier.alert(event, payload)
   end
 end
 ```
 
-### Redis
-
-The `Faulty::Cache::Redis` backend provides distributed circuit storage using
-Redis. The default configuration:
-
 ```ruby
 Faulty.init do |config|
-  config.storage = Faulty::Storage::Redis.new do |storage|
-    # The Redis client. Accepts either a Redis instance, or a ConnectionPool
-    # of Redis instances.
-    storage.client = ::Redis.new
-
-    # The prefix to prepend to all redis keys used by Faulty circuits
-    storage.key_prefix = 'faulty'
-
-    # A string to separate the parts of the redis key
-    storage.key_separator: ':'
-
-    # The maximum number of circuit runs that will be stored
-    storage.max_sample_size = 100
-
-    # The maximum number of seconds that a circuit run will be stored
-    storage.sample_ttl = 1800
-  end
+  config.listeners = [MyFaultyListener.new]
 end
 ```
 
-### 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)).
+## How it Works
 
-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
-very large numbers of circuits.
+Faulty implements a version of circuit breakers inspired by "Release It!: Design
+and Deploy Production-Ready Software" by [Michael T. Nygard][michael nygard] and
+[Martin Fowler's post][martin fowler] on the subject. A few notable features of
+Faulty's implementation are:
 
-```ruby
-statuses = Faulty.list_circuits.map do |name|
-  Faulty.circuit(name).status
-end
-```
+- Rate-based failure thresholds
+- Integrated caching inspired by Netflix's [Hystrix][hystrix] with automatic
+  cache jitter and error fallback.
+- Event-based monitoring
+- Flexible fault-tolerant storage with optional fallbacks
 
-## Scopes
+Following the principals of the circuit-breaker pattern, the block given to
+`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.
 
-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
-configure Faulty globally, however it is possible to have additional
-configurations using scopes.
+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
+skipped, and a `Faulty::OpenCircuitError` will be raised.
 
-### The default scope
+After the cool-down has elapsed, the circuit enters the half-open state. In this
+state, Faulty allows a single execution of the block as a test run. If the test
+run succeeds, the circuit is fully closed and the circuit state is reset. If the
+test run fails, the circuit is opened and the cool-down is reset.
 
-When you call `Faulty.init`, you are actually creating the default scope. You
-can access this scope directly by calling `Faulty.default`.
+Each time the circuit changes state or executes the block, events are raised
+that are sent to the Faulty event notifier. The notifier should be used to track
+circuit failure rates, open circuits, etc.
 
-```ruby
-# We create the default scope
-Faulty.init
+In addition to the classic circuit breaker design, Faulty implements caching
+that is integrated with the circuit state. See [Caching](#caching) for more
+detail.
 
-# Access the default scope
-scope = Faulty.default
+### Caching
 
-# Alternatively, access the scope by name
-scope = Faulty[:default]
-```
+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 new Faulty instance.
+If you're using Rails, this is automatically set to the Rails cache.
 
-You can rename the default scope if desired:
+Once your cache is configured, you can use the `cache` parameter when running
+a circuit to specify a cache key:
 
 ```ruby
-Faulty.init(:custom_default)
-
-scope = Faulty.default
-scope = Faulty[:custom_default]
+feed = Faulty.circuit('rss_feeds')
+  .try_run(cache: "rss_feeds/#{feed}") do
+    fetch_feed(feed)
+  end.or_default([])
 ```
 
-### Multiple Scopes
+By default a circuit has the following options:
 
-If you want multiple scopes, but want global, thread-safe access to
-them, you can use `Faulty.register`:
+- `cache_expires_in`: 86400 (1 day). This is sent to the cache backend and
+  defines how long the cache entry should be stored. After this time elapses,
+  queries will result in a cache miss.
+- `cache_refreshes_after`: 900 (15 minutes). This is used internally by Faulty
+  to indicate when a cache should be refreshed. It does not affect how long the
+  cache entry is stored.
+- `cache_refresh_jitter`: 180 (3 minutes = 20% of `cache_refreshes_after`). The
+  maximum number of seconds to randomly add or subtract from
+  `cache_refreshes_after` when determining whether to refresh a cache entry.
+  This mitigates the "thundering herd" effect caused by many processes
+  simultaneously refreshing the cache.
 
-```ruby
-api_scope = Faulty::Scope.new do |config|
-  # This accepts the same options as Faulty.init
-end
+This code will attempt to fetch an RSS feed protected by a circuit. If the feed
+is within the cache refresh period, then the result will be returned from the
+cache and the block will not be executed regardless of the circuit state.
 
-Faulty.register(:api, api_scope)
+If the cache is hit, but outside its refresh period, then Faulty will check the
+circuit state. If the circuit is closed or half-open, then it will run the
+block. If the block is successful, then it will update the circuit, write to the
+cache and return the new value.
 
-# Now access the scope globally
-Faulty[:api]
-```
+However, if the cache is hit and the block fails, then that failure is noted
+in the circuit and Faulty returns the cached value.
 
-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:
+If the circuit is open and the cache is hit, then Faulty will always return the
+cached value.
 
-```ruby
-Faulty[:api].circuit(:api_circuit).run { 'ok' }
-```
+If the cache query results in a miss, then faulty operates as normal. In the
+code above, if the circuit is closed, the block will be executed. If the block
+succeeds, the cache is refreshed. If the block fails, the default of `[]` will
+be returned.
 
-### Standalone Scopes
+### Fault Tolerance
 
-If you choose, you can use Faulty scopes without registering them globally. This
-could be useful if you prefer dependency injection over global state.
+Faulty backends are fault-tolerant by default. Any `StandardError`s raised by
+the storage or cache backends are captured and suppressed. Failure events for
+these errors are sent to the notifier.
 
-```ruby
-faulty = Faulty::Scope.new
-faulty.circuit(:standalone_circuit)
-```
+In case of a flaky storage or cache backend, Faulty also uses independent
+in-memory circuits to track failures so that we don't keep calling a backend
+that is failing. See the API docs for [`Cache::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/AutoWire),
+and [`Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/AutoWire)
+for more details.
 
-Calling `circuit` on the scope still has the same memoization behavior that
-`Faulty.circuit` has, so subsequent calls to the same circuit will return a
-memoized circuit object.
+If the storage backend fails, circuits will default to closed. If the cache
+backend fails, all cache queries will miss.
 
 ## Implementing a Cache Backend
 
 You can implement your own cache backend by following the documentation in
-`Faulty::Cache::Interface`. It is a fairly simple API, with only get/set
-methods. For example:
+[`Faulty::Cache::Interface`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/Interface).
+It is a fairly simple API, with only get/set methods. For example:
 
 ```ruby
 class MyFaultyCache
@@ -535,25 +1129,47 @@ users.
 ## Implementing a Storage Backend
 
 You can implement your own storage backend by following the documentation in
-`Faulty::Storage::Interface`. Since the storage has some tricky requirements
-regarding concurrency, the `Faulty::Storage::Memory` can be used as a reference
-implementation. Feel free to open a pull request if your storage backend
-would be useful for other users.
+[`Faulty::Storage::Interface`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Interface).
+Since the storage has some tricky requirements regarding concurrency, the
+[`Faulty::Storage::Memory`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Memory)
+can be used as a reference implementation. Feel free to open a pull request if
+your storage backend would be useful for other users.
 
 ## Alternatives
 
 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 in-memory storage by design.
+- [circuitbox](https://github.com/yammer/circuitbox): Similar in design 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)
+- Protected storage access with fallback to safe storage
+- 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
+[michael nygard]: https://www.michaelnygard.com/
 [martin fowler]: https://www.martinfowler.com/bliki/CircuitBreaker.html
 [hystrix]: https://github.com/Netflix/Hystrix/wiki/How-it-Works