Fix ruby version compatibility and start README

Author: justinhoward

.gitignore

@@ -1,6 +1,7 @@
 /.bundle/
 /Gemfile.lock
 /vendor/
+/.ruby-version
 
 /coverage/
 /doc/

.ruby-version

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright © 2020 ParentSquare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LICENSE.txt

@@ -0,0 +1,135 @@
+# Faulty
+
+Fault-tolerance tools for ruby based on [circuit-breakers][martin fowler].
+
+```ruby
+users = Faulty.circuit(:api).try_run do
+  api.users
+end.or_default([])
+```
+
+## Installation
+
+Add it to your `Gemfile`:
+
+```ruby
+gem 'faulty'
+```
+
+Or install it manually:
+
+```sh
+gem 'faulty'
+```
+
+During your app startup, call `Faulty.init`. For Rails, you would do this in
+`config/initializers/faulty.rb`.
+
+## Setup
+
+Use the default configuration options:
+
+```ruby
+Faulty.init
+```
+
+Or specify your own configuration:
+
+```ruby
+Faulty.init do |config|
+  config.storage = Faulty::Storage::Redis.new
+
+  listener = Faulty::Events::CallbackListener.new
+  config.listeners = [
+    Faulty::Events::CallbackListener.new do |events|
+      events.circuit_open do |payload|
+        puts 'Circuit was opened'
+      end
+    end
+  ]
+end
+```
+
+For a full list of configuration options, see the Configuration section.
+
+## Basic Usage
+
+## Configuration
+
+## Faulty's Circuit Breaker Algorithm
+
+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:
+
+- Rate-based failure thresholds
+- Integrated caching inspired by Netflix's [Hystrix][hystrix] with automatic
+  cache jitter and error fallback.
+- Event-based monitoring
+
+## Circuit Options
+
+## Caching
+
+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. 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:
+
+```ruby
+feed = Faulty.circuit(:rss_feeds)
+  .try_run(cache: "rss_feeds/#{feed}" do
+    fetch_feed(feed)
+  end.or_default([])
+```
+
+By default a circuit has the following options:
+
+- `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.
+
+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.
+
+However, if the cache is hit and the block fails, then that failure is noted
+in the circuit and Faulty returns the cached value.
+
+If the circuit is open and the cache is hit, then Faulty will always return the
+cached value.
+
+If the cache query results in a miss, then faulty operates as normal. In the
+code above, the block will be executed. If the block succeeds, the cache is
+refreshed. If the block fails, the default of `[]` will be returned.
+
+## Fault Tolerance
+
+## Event Handling
+
+## Scopes
+
+## Implementing a Storage Backend
+
+## Implementing a Cache Backend
+
+## Implementing a Event Listener
+
+[martin fowler]: https://www.martinfowler.com/bliki/CircuitBreaker.html
+[hystrix]: https://github.com/Netflix/Hystrix/wiki/How-it-Works

README.md

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.authors = ['Justin Howard']
   spec.email = ['[email protected]']
 
-  spec.summary = ''
+  spec.summary = 'Fault-tolerance tools for ruby based on circuit-breakers'
   spec.homepage = 'https://github.com/ParentSquare/faulty'
 
   spec.files = `git ls-files -z`
@@ -33,8 +33,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec_junit_formatter', '~> 0.4'
   # 0.81 is the last rubocop version with Ruby 2.3 support
   spec.add_development_dependency 'rubocop', '0.81.0'
-  spec.add_development_dependency 'rubocop-rspec', '1.41.0'
-  spec.add_development_dependency 'simplecov', '~> 0.18'
+  spec.add_development_dependency 'rubocop-rspec', '1.38.1'
+  spec.add_development_dependency 'simplecov', '>= 0.17.1'
   spec.add_development_dependency 'timecop', '>= 0.9'
   spec.add_development_dependency 'yard', '~> 0.9.25'
 end

faulty.gemspec

@@ -49,7 +49,7 @@ def init(scope_name = :default, **config, &block)
       self
     end
 
-    # Get the default scope given during {#init}
+    # Get the default scope given during {.init}
     #
     # @return [Scope, nil] The default scope if it is registered
     def default

lib/faulty.rb

@@ -13,7 +13,7 @@ module Storage
     # circuits that are created. To that end, it's a good idea to avoid
     # dynamically-named circuits with this backend.
     #
-    # For a more robust multi-process implementation, use the {Redis} storage
+    # For a more robust distributed implementation, use the {Redis} storage
     # backend.
     #
     # This can be used as a reference implementation for storage backends that

lib/faulty/storage/memory.rb

@@ -5,7 +5,9 @@
 if ENV['COVERAGE']
   require 'simplecov'
   SimpleCov.start do
-    enable_coverage :branch
+    if Gem::Version.new(SimpleCov::VERSION) >= Gem::Version.new('0.18.0')
+      enable_coverage :branch
+    end
     add_filter '/spec/'
     add_filter '/vendor/'
   end