faulty 0.1.4 → 0.5.1

data/lib/faulty/cache/fault_tolerant_proxy.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A wrapper for cache backends that may raise errors
     #
-    # {Scope} automatically wraps all non-fault-tolerant cache backends with
+    # {Faulty#initialize} automatically wraps all non-fault-tolerant cache backends with
     # this class.
     #
     # If the cache backend raises a `StandardError`, it will be captured and
-    # sent to the notifier.
+    # sent to the notifier. Reads errors will return `nil`, and writes will be
+    # a no-op.
     class FaultTolerantProxy
       attr_reader :options
 
@@ -36,6 +37,16 @@ module Faulty
         @options = Options.new(options, &block)
       end
 
+      # Wrap a cache in a FaultTolerantProxy unless it's already fault tolerant
+      #
+      # @param cache [Cache::Interface] The cache to maybe wrap
+      # @return [Cache::Interface] The original cache or a {FaultTolerantProxy}
+      def self.wrap(cache, **options, &block)
+        return cache if cache.fault_tolerant?
+
+        new(cache, **options, &block)
+      end
+
       # Read from the cache safely
       #
       # If the backend raises a `StandardError`, this will return `nil`.
@@ -58,7 +69,7 @@ module Faulty
       # @return [void]
       def write(key, value, expires_in: nil)
         @cache.write(key, value, expires_in: expires_in)
-      rescue StandardError
+      rescue StandardError => e
         options.notifier.notify(:cache_failure, key: key, action: :write, error: e)
         nil
       end

data/lib/faulty/cache/interface.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # The interface required for a cache backend implementation
     #

data/lib/faulty/cache/mock.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A mock cache for testing
     #

data/lib/faulty/cache/null.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A cache backend that does nothing
     #

data/lib/faulty/cache/rails.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A wrapper for a Rails or ActiveSupport cache
     #
     class Rails
+      extend Forwardable
+
       # @param cache The Rails cache to wrap
       # @param fault_tolerant [Boolean] Whether the Rails cache is
       #   fault_tolerant. See {#fault_tolerant?} for more details
@@ -13,15 +15,12 @@ module Faulty
         @fault_tolerant = fault_tolerant
       end
 
-      # (see Interface#read)
-      def read(key)
-        @cache.read(key)
-      end
-
-      # (see Interface#read)
-      def write(key, value, expires_in: nil)
-        @cache.write(key, value, expires_in: expires_in)
-      end
+      # @!method read(key)
+      #   (see Faulty::Cache::Interface#read)
+      #
+      # @!method write(key, value, expires_in: expires_in)
+      #   (see Faulty::Cache::Interface#write)
+      def_delegators :@cache, :read, :write
 
       # Although ActiveSupport cache implementations are fault-tolerant,
       # Rails.cache is not guranteed to be fault tolerant. For this reason,

data/lib/faulty/circuit.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # Runs code protected by a circuit breaker
   #
   # https://www.martinfowler.com/bliki/CircuitBreaker.html
@@ -50,6 +50,9 @@ module 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.
@@ -66,14 +69,19 @@ module Faulty
     #   @return [Error, Array<Error>] An array of errors that are considered circuit
     #     failures. Default `[StandardError]`.
     # @!attribute [r] exclude
-    #   @return [Error, Array<Error>] An array of errors that will be captured and
-    #     considered circuit failures. Default `[]`.
+    #   @return [Error, Array<Error>] An array of errors that will not be
+    #     captured by Faulty. These errors will not be considered circuit
+    #     failures. Default `[]`.
     # @!attribute [r] cache
-    #   @return [Cache::Interface] The cache backend. Default `Cache::Null.new`
+    #   @return [Cache::Interface] The cache backend. Default
+    #   `Cache::Null.new`. Unlike {Faulty#initialize}, this is not wrapped in
+    #   {Cache::AutoWire} by default.
     # @!attribute [r] notifier
     #   @return [Events::Notifier] A Faulty notifier. Default `Events::Notifier.new`
     # @!attribute [r] storage
-    #   @return [Storage::Interface] The storage backend. Default `Storage::Memory.new`
+    #   @return [Storage::Interface] The storage backend. Default
+    #   `Storage::Memory.new`. Unlike {Faulty#initialize}, this is not wrapped
+    #    in {Storage::AutoWire} by default.
     Options = Struct.new(
       :cache_expires_in,
       :cache_refreshes_after,
@@ -83,6 +91,7 @@ module Faulty
       :rate_threshold,
       :sample_threshold,
       :errors,
+      :error_module,
       :exclude,
       :cache,
       :notifier,
@@ -98,6 +107,7 @@ module Faulty
           cache_refreshes_after: 900,
           cool_down: 300,
           errors: [StandardError],
+          error_module: Faulty,
           exclude: [],
           evaluation_window: 60,
           rate_threshold: 0.5,
@@ -110,6 +120,7 @@ module Faulty
           cache
           cool_down
           errors
+          error_module
           exclude
           evaluation_window
           rate_threshold
@@ -208,9 +219,11 @@ module 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
@@ -277,7 +290,7 @@ module 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
@@ -287,26 +300,27 @@ module 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)
 
@@ -315,8 +329,9 @@ module 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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The base error for all Faulty errors
   class FaultyError < StandardError; end
 
@@ -20,19 +20,21 @@ module Faulty
     end
   end
 
-  # Raised if getting the default scope without initializing one
-  class MissingDefaultScopeError < FaultyError
+  # Raised if getting the default instance without initializing one
+  class MissingDefaultInstanceError < FaultyError
     def initialize(message = nil)
-      message ||= 'No default scope. Create one with init or get your scope with Faulty[:scope_name]'
+      message ||= 'No default instance. Create one with init or get your instance with Faulty[:name]'
       super(message)
     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 @@ module 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
 
@@ -59,8 +67,22 @@ module Faulty
   # Raised if calling get or error on a result without checking it
   class UncheckedResultError < FaultyError; end
 
+  # An error that wraps multiple other errors
+  class FaultyMultiError < FaultyError
+    def initialize(message, errors)
+      message = "#{message}: #{errors.map(&:message).join(', ')}"
+      super(message)
+    end
+  end
+
   # Raised if getting the wrong result type.
   #
   # For example, calling get on an error result will raise this
   class WrongResultError < FaultyError; end
+
+  # Raised if a FallbackChain partially fails
+  class PartialFailureError < FaultyMultiError; end
+
+  # Raised if all FallbackChain backends fail
+  class AllFailedError < FaultyMultiError; end
 end

data/lib/faulty/events.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The namespace for Faulty events and event listeners
   module Events
     # All possible events that can be raised by Faulty

data/lib/faulty/events/callback_listener.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # A simple listener implementation that uses callback blocks as handlers
     #

data/lib/faulty/events/honeybadger_listener.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # Reports circuit errors to Honeybadger
     #

data/lib/faulty/events/listener_interface.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # The interface required to implement a event listener
     #

data/lib/faulty/events/log_listener.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # A default listener that logs Faulty events
     class LogListener
@@ -72,11 +72,10 @@ module Faulty
       end
 
       def storage_failure(payload)
-        log(
-          :error, 'Storage failure', payload[:action],
-          circuit: payload[:circuit]&.name,
-          error: payload[:error].message
-        )
+        extra = {}
+        extra[:circuit] = payload[:circuit].name if payload.key?(:circuit)
+        extra[:error] = payload[:error].message
+        log(:error, 'Storage failure', payload[:action], extra)
       end
 
       def log(level, msg, action, extra = {})

data/lib/faulty/events/notifier.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # The default event dispatcher for Faulty
     class Notifier

data/lib/faulty/immutable_options.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # A struct that cannot be modified after initialization
   module ImmutableOptions
     # @param hash [Hash] A hash of attributes to initialize with

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