faulty 0.2.0 → 0.6.0

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
 
@@ -59,8 +67,22 @@ class 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/log_listener.rb

@@ -72,11 +72,10 @@ class 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/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] = nil
+      end
+    end
+  end
+end

data/lib/faulty/patch/mysql2.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'mysql2'
+
+if Gem::Version.new(Mysql2::VERSION) < Gem::Version.new('0.5.0')
+  raise NotImplementedError, 'The faulty mysql2 patch requires mysql2 0.5.0 or later'
+end
+
+class Faulty
+  module Patch
+    # Patch Mysql2 to run connections and queries in a circuit
+    #
+    # This module is not required by default
+    #
+    # Pass a `:faulty` key into your MySQL connection options to enable
+    # circuit protection. See {Patch.circuit_from_hash} for the available
+    # options.
+    #
+    # COMMIT, ROLLBACK, and RELEASE SAVEPOINT queries are intentionally not
+    # protected by the circuit. This is to allow open transactions to be closed
+    # if possible.
+    #
+    # @example
+    #   require 'faulty/patch/mysql2'
+    #
+    #   mysql = Mysql2::Client.new(host: '127.0.0.1', faulty: {})
+    #   mysql.query('SELECT * FROM users') # raises Faulty::CircuitError if connection fails
+    #
+    #   # If the faulty key is not given, no circuit is used
+    #   mysql = Mysql2::Client.new(host: '127.0.0.1')
+    #   mysql.query('SELECT * FROM users') # not protected by a circuit
+    #
+    # @see Patch.circuit_from_hash
+    module Mysql2
+      include Base
+
+      Patch.define_circuit_errors(self, ::Mysql2::Error::ConnectionError)
+
+      QUERY_WHITELIST = [
+        %r{\A(?:/\*.*?\*/)?\s*ROLLBACK}i,
+        %r{\A(?:/\*.*?\*/)?\s*COMMIT}i,
+        %r{\A(?:/\*.*?\*/)?\s*RELEASE\s+SAVEPOINT}i
+      ].freeze
+
+      def initialize(opts = {})
+        @faulty_circuit = Patch.circuit_from_hash(
+          'mysql2',
+          opts[:faulty],
+          errors: [
+            ::Mysql2::Error::ConnectionError,
+            ::Mysql2::Error::TimeoutError
+          ],
+          patched_error_module: Faulty::Patch::Mysql2
+        )
+
+        super
+      end
+
+      # Protect manual connection pings
+      def ping
+        faulty_run { super }
+      rescue Faulty::Patch::Mysql2::FaultyError
+        false
+      end
+
+      # Protect the initial connnection
+      def connect(*args)
+        faulty_run { super }
+      end
+
+      # Protect queries unless they are whitelisted
+      def query(*args)
+        return super if QUERY_WHITELIST.any? { |r| !r.match(args.first).nil? }
+
+        faulty_run { super }
+      end
+    end
+  end
+end
+
+::Mysql2::Client.prepend(Faulty::Patch::Mysql2)

data/lib/faulty/patch/redis.rb

@@ -0,0 +1,93 @@
+# 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 MySQL connection options to enable
+    # circuit protection. See {Patch.circuit_from_hash} for the available
+    # options.
+    #
+    # @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)
+
+      class BusyError < ::Redis::CommandError
+      end
+
+      # Patches Redis to add the `:faulty` key
+      def initialize(options = {})
+        @faulty_circuit = Patch.circuit_from_hash(
+          'redis',
+          options[:faulty],
+          errors: [
+            ::Redis::BaseConnectionError,
+            BusyError
+          ],
+          patched_error_module: Faulty::Patch::Redis
+        )
+
+        super
+      end
+
+      # The initial connection is protected by a circuit
+      def connect
+        faulty_run { super }
+      end
+
+      # Protect command calls
+      def call(command)
+        faulty_run { super }
+      end
+
+      # Protect command_loop calls
+      def call_loop(command, timeout = 0)
+        faulty_run { super }
+      end
+
+      # Protect pipelined commands
+      def call_pipelined(commands)
+        faulty_run { super }
+      end
+
+      # Inject specific error classes if client is patched
+      #
+      # This method does not raise errors, it returns them
+      # as exception objects, so we simply modify that error if necessary and
+      # return it.
+      #
+      # The call* methods above will then raise that error, so we are able to
+      # capture it with faulty_run.
+      def io(&block)
+        return super unless @faulty_circuit
+
+        reply = super
+        if reply.is_a?(::Redis::CommandError)
+          if reply.message.start_with?('BUSY')
+            reply = BusyError.new(reply.message)
+          end
+        end
+
+        reply
+      end
+    end
+  end
+end
+
+::Redis::Client.prepend(Faulty::Patch::Redis)