faulty 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e68341d29ccefb2a4fa4c265f3f2d5ec37371d37cb41d5a186b3f25d2130b46
-  data.tar.gz: 56e659d66871738e8818c4874102de04ef97873cb0d1c444d58259c875b21378
+  metadata.gz: f8ce491fe09e0c6224c3ecc6da2825eeff601f15f7b5bbfbff065f898860fc48
+  data.tar.gz: caf56c1bfc86511d0acb6fbd3f7507d521bcd7b8ac74b47a85ebcbd9a4fdef1b
 SHA512:
-  metadata.gz: 7db7b915923132bd1e5d234245cc5a3adb5988013f4baf8fadc59f89bacfde6828310954f0d6ea9da59ed18c97b9224e3d0f9e02ce2700ef9f6240e8b14d3706
-  data.tar.gz: 578d4f0473ff58b1a9f6aeb3d2eab4be158de92943d6147e1521212068578ecd190094e17b02838919561d43b477b197344804478aa8288e70d0c30b26f85fd9
+  metadata.gz: 89eb97edae88432ea0e6e36a9c0b0f69d4d89075193ffd5a6eb0fe10e24c0983047289ccdb8e363619c4f83b1e80baec9decc34e4fdf029cfbef24189f244138
+  data.tar.gz: 4cabda8638d452bcac0a6375b284b4465d7eb34ed5e4b546a7247c09816eae4480620d69f9777144bd3d3aa8abcc58ca83243037e5d7aac0635e6d01d45ff289

data/.rubocop.yml

@@ -8,6 +8,9 @@ AllCops:
 Layout/ArgumentAlignment:
   EnforcedStyle: with_fixed_indentation
 
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
 Layout/ParameterAlignment:
   EnforcedStyle: with_fixed_indentation
 

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## Release v0.5.0
+
+* Allow creating a new Faulty instance in Faulty#register #24 justinhoward
+* Add support for patches to core dependencies starting with redis #14 justinhoward
+* Improve storage #entries performance by returning entries #23 justinhoward
+
+### Breaking Changes
+
+* Faulty #[] no longer differentiates between symbols and strings when accessing
+  Faulty instances
+* Faulty::Storage::Interface must now return a history array instead of a
+  circuit status object. Custom storage backends must be updated.
+
 ## Release v0.4.0
 
 * Switch from Travis CI to GitHub actions #11 justinhoward

data/README.md

@@ -81,6 +81,8 @@ Also see "Release It!: Design and Deploy Production-Ready Software" by
   + [Circuit Options](#circuit-options)
   + [Listing Circuits](#listing-circuits)
   + [Locking Circuits](#locking-circuits)
+* [Patches](#patches)
+  + [Patch::Redis](#patchredis)
 * [Event Handling](#event-handling)
   + [CallbackListener](#callbacklistener)
   + [Other Built-in Listeners](#other-built-in-listeners)
@@ -221,6 +223,10 @@ users = Faulty.circuit(:api).try_run do
 end.or_default([])
 ```
 
+If you want to globally wrap your core dependencies, like your cache or
+database, you may want to look at [Patches](#patches), which can automatically
+wrap your connections in a Faulty circuit.
+
 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.
@@ -580,6 +586,14 @@ principal to any other registered Faulty instance:
 Faulty[:api].circuit('api_circuit').run { 'ok' }
 ```
 
+You can also create and register a Faulty instance in one step:
+
+```ruby
+Faulty.register(:api) do |config|
+  # This accepts the same options as Faulty.init
+end
+```
+
 #### Standalone Instances
 
 If you choose, you can use Faulty instances without registering them globally by
@@ -915,6 +929,59 @@ 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.
 
+## Patches
+
+For certain core dependencies like a cache or a database connection, it is
+inconvenient to wrap every call in its own circuit. Faulty provides some patches
+to wrap these calls in a circuit automatically. To use a patch, it first needs
+to be loaded. Since patches modify third-party code, they are not automatically
+required with the Faulty gem, so they need to be required individually.
+
+```ruby
+require 'faulty'
+require 'faulty/patch/redis'
+```
+
+Or require them in your `Gemfile`
+
+```ruby
+gem 'faulty', require: %w[faulty faulty/patch/redis]
+```
+
+### Patch::Redis
+
+[`Faulty::Patch::Redis`](https://www.rubydoc.info/gems/faulty/Faulty/Patch/Redis)
+protects a Redis client with an internal circuit. Pass a `:faulty` key along
+with your connection options to enable the circuit breaker.
+
+Keep in mind that when using this patch, you'll most likely want to use the
+in-memory circuit storage adapter and not the Redis storage adapter. That way
+if Redis fails, your circuit storage doesn't also fail.
+
+```ruby
+require 'faulty/patch/redis'
+
+redis = Redis.new(url: 'redis://localhost:6379', faulty: {
+  # The name for the redis circuit
+  name: 'redis'
+
+  # The faulty instance to use
+  # This can also be a registered faulty instance or a constant name. See API
+  # docs for more details
+  instance: Faulty.default
+
+  # By default, circuit errors will be subclasses of Redis::BaseError
+  # To disable this behavior, set patch_errors to false and Faulty
+  # will raise its default errors
+  patch_errors: true
+})
+redis.connect # raises Faulty::CircuitError if connection fails
+
+# If the faulty key is not given, no circuit is used
+redis = Redis.new(url: 'redis://localhost:6379')
+redis.connect # not protected by a circuit
+```
+
 ## Event Handling
 
 Faulty uses an event-dispatching model to deliver notifications of internal

data/lib/faulty.rb

@@ -9,6 +9,7 @@ require 'faulty/cache'
 require 'faulty/circuit'
 require 'faulty/error'
 require 'faulty/events'
+require 'faulty/patch'
 require 'faulty/result'
 require 'faulty/status'
 require 'faulty/storage'
@@ -66,7 +67,7 @@ class Faulty
     def [](name)
       raise UninitializedError unless @instances
 
-      @instances[name]
+      @instances[name.to_s]
     end
 
     # Register an instance to the global Faulty state
@@ -75,13 +76,22 @@ class Faulty
     # return value if you need to know whether the instance already existed.
     #
     # @param name [Symbol] The name of the instance to register
-    # @param instance [Faulty] The instance to register
+    # @param instance [Faulty] The instance to register. If nil, a new instance
+    #   will be created from the given options or block.
+    # @param config [Hash] Attributes for {Faulty::Options}
+    # @yield [Faulty::Options] For setting options in a block
     # @return [Faulty, nil] The previously-registered instance of that name if
     #   it already existed, otherwise nil.
-    def register(name, instance)
+    def register(name, instance = nil, **config, &block)
       raise UninitializedError unless @instances
 
-      @instances.put_if_absent(name, instance)
+      if instance
+        raise ArgumentError, 'Do not give config options if an instance is given' if !config.empty? || block
+      else
+        instance = new(**config, &block)
+      end
+
+      @instances.put_if_absent(name.to_s, instance)
     end
 
     # Get the options for the default instance

data/lib/faulty/circuit.rb

@@ -50,6 +50,9 @@ class Faulty
     # @!attribute [r] cool_down
     #   @return [Integer] The number of seconds the circuit will
     #     stay open after it is tripped. Default 300.
+    # @!attribute [r] error_module
+    #   @return [Module] Used by patches to set the namespace module for
+    #     the faulty errors that will be raised. Default `Faulty`
     # @!attribute [r] evaluation_window
     #   @return [Integer] The number of seconds of history that
     #     will be evaluated to determine the failure rate for a circuit.
@@ -88,6 +91,7 @@ class Faulty
       :rate_threshold,
       :sample_threshold,
       :errors,
+      :error_module,
       :exclude,
       :cache,
       :notifier,
@@ -103,6 +107,7 @@ class Faulty
           cache_refreshes_after: 900,
           cool_down: 300,
           errors: [StandardError],
+          error_module: Faulty,
           exclude: [],
           evaluation_window: 60,
           rate_threshold: 0.5,
@@ -115,6 +120,7 @@ class Faulty
           cache
           cool_down
           errors
+          error_module
           exclude
           evaluation_window
           rate_threshold
@@ -213,9 +219,11 @@ class Faulty
       cached_value = cache_read(cache)
       # return cached unless cached.nil?
       return cached_value if !cached_value.nil? && !cache_should_refresh?(cache)
-      return run_skipped(cached_value) unless status.can_run?
 
-      run_exec(cached_value, cache, &block)
+      current_status = status
+      return run_skipped(cached_value) unless current_status.can_run?
+
+      run_exec(current_status, cached_value, cache, &block)
     end
 
     # Force the circuit to stay open until unlocked
@@ -282,7 +290,7 @@ class Faulty
     # @return The result from cache if available
     def run_skipped(cached_value)
       skipped!
-      raise OpenCircuitError.new(nil, self) if cached_value.nil?
+      raise options.error_module::OpenCircuitError.new(nil, self) if cached_value.nil?
 
       cached_value
     end
@@ -292,26 +300,27 @@ class Faulty
     # @param cached_value The cached value if one is available
     # @param cache_key [String, nil] The cache key if one is given
     # @return The run result
-    def run_exec(cached_value, cache_key)
+    def run_exec(status, cached_value, cache_key)
       result = yield
-      success!
+      success!(status)
       cache_write(cache_key, result)
       result
     rescue *options.errors => e
       raise if options.exclude.any? { |ex| e.is_a?(ex) }
 
       if cached_value.nil?
-        raise CircuitTrippedError.new(nil, self) if failure!(e)
+        raise options.error_module::CircuitTrippedError.new(nil, self) if failure!(status, e)
 
-        raise CircuitFailureError.new(nil, self)
+        raise options.error_module::CircuitFailureError.new(nil, self)
       else
         cached_value
       end
     end
 
     # @return [Boolean] True if the circuit transitioned to closed
-    def success!
-      status = storage.entry(self, Faulty.current_time, true)
+    def success!(status)
+      entries = storage.entry(self, Faulty.current_time, true)
+      status = Status.from_entries(entries, **status.to_h)
       closed = false
       closed = close! if should_close?(status)
 
@@ -320,8 +329,9 @@ class Faulty
     end
 
     # @return [Boolean] True if the circuit transitioned to open
-    def failure!(error)
-      status = storage.entry(self, Faulty.current_time, false)
+    def failure!(status, error)
+      entries = storage.entry(self, Faulty.current_time, false)
+      status = Status.from_entries(entries, **status.to_h)
       options.notifier.notify(:circuit_failure, circuit: self, status: status, error: error)
 
       opened = if status.half_open?

data/lib/faulty/error.rb

@@ -28,11 +28,13 @@ class Faulty
     end
   end
 
-  # The base error for all errors raised during circuit runs
-  #
-  class CircuitError < FaultyError
+  # Included in faulty circuit errors to provide common features for
+  # native and patched errors
+  module CircuitErrorBase
     attr_reader :circuit
 
+    # @param message [String]
+    # @param circuit [Circuit] The circuit that raised the error
     def initialize(message, circuit)
       message ||= %(circuit error for "#{circuit.name}")
       @circuit = circuit
@@ -41,6 +43,12 @@ class Faulty
     end
   end
 
+  # The base error for all errors raised during circuit runs
+  #
+  class CircuitError < FaultyError
+    include CircuitErrorBase
+  end
+
   # Raised when running a circuit that is already open
   class OpenCircuitError < CircuitError; end
 

data/lib/faulty/patch.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'faulty/patch/base'
+
+class Faulty
+  # Automatic wrappers for common core dependencies like database connections
+  # or caches
+  module Patch
+    class << self
+      # Create a circuit from a configuration hash
+      #
+      # This is intended to be used in contexts where the user passes in
+      # something like a connection hash to a third-party library. For example
+      # the Redis patch hooks into the normal Redis connection options to add
+      # a `:faulty` key, which is a hash of faulty circuit options. This is
+      # slightly different from the normal Faulty circuit options because
+      # we also accept an `:instance` key which is a faulty instance.
+      #
+      # @example
+      #   # We pass in a faulty instance along with some circuit options
+      #   Patch.circuit_from_hash(
+      #     :mysql,
+      #     { host: 'localhost', faulty: {
+      #       name: 'my_mysql', # A custom circuit name can be included
+      #       instance: Faulty.new,
+      #       sample_threshold: 5
+      #       }
+      #     }
+      #   )
+      #
+      # @example
+      #   # instance can be a registered faulty instance referenced by a string
+      #   or symbol
+      #   Faulty.register(:db_faulty, Faulty.new)
+      #   Patch.circuit_from_hash(
+      #     :mysql,
+      #     { host: 'localhost', faulty: { instance: :db_faulty } }
+      #   )
+      # @example
+      #   # If instance is a hash with the key :constant, the value can be
+      #   # a global constant name containing a Faulty instance
+      #   DB_FAULTY = Faulty.new
+      #   Patch.circuit_from_hash(
+      #     :mysql,
+      #     { host: 'localhost', faulty: { instance: { constant: 'DB_FAULTY' } } }
+      #   )
+      #
+      # @example
+      #   # Certain patches may want to enforce certain options like :errors
+      #   # This can be done via hash or the usual block syntax
+      #   Patch.circuit_from_hash(:mysql,
+      #     { host: 'localhost', faulty: {} }
+      #     errors: [Mysql2::Error]
+      #   )
+      #
+      #   Patch.circuit_from_hash(:mysql,
+      #     { host: 'localhost', faulty: {} }
+      #   ) do |conf|
+      #     conf.errors = [Mysql2::Error]
+      #   end
+      #
+      # @param default_name [String] The default name for the circuit
+      # @param hash [Hash] A hash of user-provided options. Supports any circuit
+      #   option and these additional options
+      # @option hash [String] :name The circuit name. Defaults to `default_name`
+      # @option hash [Boolean] :patch_errors By default, circuit errors will be
+      #   subclasses of `options[:patched_error_module]`. The user can disable
+      #   this by setting this option to false.
+      # @option hash [Faulty, String, Symbol, Hash{ constant: String }] :instance
+      #   A reference to a faulty instance. See examples.
+      # @param options [Hash] Additional override options. Supports any circuit
+      #   option and these additional ones.
+      # @option options [Module] :patched_error_module The namespace module
+      #   for patched errors
+      # @yield [Circuit::Options] For setting override options in a block
+      # @return [Circuit, nil] The circuit if one was created
+      def circuit_from_hash(default_name, hash, **options, &block)
+        return unless hash
+
+        hash = symbolize_keys(hash)
+        name = hash.delete(:name) || default_name
+        patch_errors = hash.delete(:patch_errors) != false
+        error_module = options.delete(:patched_error_module)
+        hash[:error_module] ||= error_module if error_module && patch_errors
+        faulty = resolve_instance(hash.delete(:instance))
+        faulty.circuit(name, **hash, **options, &block)
+      end
+
+      # Create a full set of {CircuitError}s with a given base error class
+      #
+      # For patches that need their errors to be subclasses of a common base.
+      #
+      # @param namespace [Module] The module to define the error classes in
+      # @param base [Class] The base class for the error classes
+      # @return [void]
+      def define_circuit_errors(namespace, base)
+        circuit_error = Class.new(base) { include CircuitErrorBase }
+        namespace.const_set('CircuitError', circuit_error)
+        namespace.const_set('OpenCircuitError', Class.new(circuit_error))
+        namespace.const_set('CircuitFailureError', Class.new(circuit_error))
+        namespace.const_set('CircuitTrippedError', Class.new(circuit_error))
+      end
+
+      private
+
+      # Resolves a constant from a constant name or returns a default
+      #
+      # - If value is a string or symbol, gets a registered Faulty instance with that name
+      # - If value is a Hash with a key `:constant`, resolves the value to a global constant
+      # - If value is nil, gets Faulty.default
+      # - Otherwise, return value directly
+      #
+      # @param value [String, Symbol, Faulty, nil] The object or constant name to resolve
+      # @return [Object] The resolved Faulty instance
+      def resolve_instance(value)
+        case value
+        when String, Symbol
+          result = Faulty[value]
+          raise NameError, "No Faulty instance for #{value}" unless result
+
+          result
+        when Hash
+          const_name = value[:constant]
+          raise ArgumentError 'Missing hash key :constant for Faulty instance' unless const_name
+
+          Kernel.const_get(const_name)
+        when nil
+          Faulty.default
+        else
+          value
+        end
+      end
+
+      # Some config files may not suport symbol keys, so we convert the hash
+      # to use symbols so that users can pass in strings
+      #
+      # We cannot use transform_keys since we support Ruby < 2.5
+      #
+      # @param hash [Hash] A hash to convert
+      # @return [Hash] The hash with keys as symbols
+      def symbolize_keys(hash)
+        result = {}
+        hash.each do |key, val|
+          result[key.to_sym] = if val.is_a?(Hash)
+            symbolize_keys(val)
+          else
+            val
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/faulty/patch/base.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Patch
+    # Can be included in patch modules to provide common functionality
+    #
+    # The patch needs to set `@faulty_circuit`
+    #
+    # @example
+    #   module ThingPatch
+    #     include Faulty::Patch::Base
+    #
+    #     def initialize(options = {})
+    #       @faulty_circuit = Faulty::Patch.circuit_from_hash('thing', options[:faulty])
+    #     end
+    #
+    #     def do_something
+    #       faulty_run { super }
+    #     end
+    #   end
+    #
+    #   Thing.prepend(ThingPatch)
+    module Base
+      # Run a block wrapped by `@faulty_circuit`
+      #
+      # If `@faulty_circuit` is not set, the block will be run with no
+      # circuit.
+      #
+      # Nested calls to this method will only cause the circuit to be triggered
+      # once.
+      #
+      # @yield A block to run inside the circuit
+      # @return The block return value
+      def faulty_run
+        faulty_running_key = "faulty_running_#{object_id}"
+        return yield unless @faulty_circuit
+        return yield if Thread.current[faulty_running_key]
+
+        Thread.current[faulty_running_key] = true
+        @faulty_circuit.run { yield }
+      ensure
+        Thread.current[faulty_running_key] = false
+      end
+    end
+  end
+end

data/lib/faulty/patch/redis.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'redis'
+
+class Faulty
+  module Patch
+    # Patch Redis to run all network IO in a circuit
+    #
+    # This module is not required by default
+    #
+    # Pass a `:faulty` key into your redis connection options to enable
+    # circuit protection. This hash is a hash of circuit options for the
+    # internal circuit. The hash may also have a `:instance` key, which is the
+    # faulty instance to create the circuit from. `Faulty.default` will be
+    # used if no instance is given. The `:instance` key can also reference a
+    # registered Faulty instance or a global constantso that it can be set
+    # from config files. See {Patch.circuit_from_hash}.
+    #
+    # @example
+    #   require 'faulty/patch/redis'
+    #
+    #   redis = Redis.new(url: 'redis://localhost:6379', faulty: {})
+    #   redis.connect # raises Faulty::CircuitError if connection fails
+    #
+    #   # If the faulty key is not given, no circuit is used
+    #   redis = Redis.new(url: 'redis://localhost:6379')
+    #   redis.connect # not protected by a circuit
+    #
+    # @see Patch.circuit_from_hash
+    module Redis
+      include Base
+
+      Patch.define_circuit_errors(self, ::Redis::BaseConnectionError)
+
+      # Patches Redis to add the `:faulty` key
+      def initialize(options = {})
+        @faulty_circuit = Patch.circuit_from_hash(
+          'redis',
+          options[:faulty],
+          errors: [::Redis::BaseConnectionError],
+          patched_error_module: Faulty::Patch::Redis
+        )
+
+        super
+      end
+
+      # The initial connection is protected by a circuit
+      def connect
+        faulty_run { super }
+      end
+
+      # Reads/writes to redis are protected
+      def io(&block)
+        faulty_run { super }
+      end
+    end
+  end
+end
+
+::Redis::Client.prepend(Faulty::Patch::Redis)

data/lib/faulty/storage/interface.rb

@@ -14,7 +14,8 @@ class Faulty
       # @param circuit [Circuit] The circuit that ran
       # @param time [Integer] The unix timestamp for the run
       # @param success [Boolean] True if the run succeeded
-      # @return [Status] The circuit status after the run is added
+      # @return [Array<Array>] An array of the new history tuples after adding
+      #   the new entry, see {#history}
       def entry(circuit, time, success)
         raise NotImplementedError
       end

data/lib/faulty/storage/memory.rb

@@ -89,7 +89,7 @@ class Faulty
           runs.push([time, success])
           runs.shift if runs.size > options.max_sample_size
         end
-        memory.status(circuit.options)
+        memory.runs.value
       end
 
       # Mark a circuit as open

data/lib/faulty/storage/redis.rb

@@ -95,15 +95,15 @@ class Faulty
       # @return (see Interface#entry)
       def entry(circuit, time, success)
         key = entries_key(circuit)
-        pipe do |r|
+        result = pipe do |r|
           r.sadd(list_key, circuit.name)
           r.expire(list_key, options.circuit_ttl + options.list_granularity) if options.circuit_ttl
           r.lpush(key, "#{time}#{ENTRY_SEPARATOR}#{success ? 1 : 0}")
           r.ltrim(key, 0, options.max_sample_size - 1)
           r.expire(key, options.sample_ttl) if options.sample_ttl
+          r.lrange(key, 0, -1)
         end
-
-        status(circuit)
+        map_entries(result.last)
       end
 
       # Mark a circuit as open

data/lib/faulty/version.rb

@@ -3,6 +3,6 @@
 class Faulty
   # The current Faulty version
   def self.version
-    Gem::Version.new('0.4.0')
+    Gem::Version.new('0.5.0')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-19 00:00:00.000000000 Z
+date: 2021-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -165,6 +165,9 @@ files:
 - lib/faulty/events/log_listener.rb
 - lib/faulty/events/notifier.rb
 - lib/faulty/immutable_options.rb
+- lib/faulty/patch.rb
+- lib/faulty/patch/base.rb
+- lib/faulty/patch/redis.rb
 - lib/faulty/result.rb
 - lib/faulty/status.rb
 - lib/faulty/storage.rb
@@ -195,8 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Fault-tolerance tools for ruby based on circuit-breakers