faulty 0.2.0 → 0.6.0

data/bin/check-version

@@ -3,8 +3,12 @@
 set -e
 
 tag="$(git describe --abbrev=0 2>/dev/null || echo)"
+echo "Tag: ${tag}"
 tag="${tag#v}"
+echo "Git Version: ${tag}"
 [ "$tag" = '' ] && exit 0
+gem_version="$(ruby -r ./lib/faulty/version -e "puts Faulty.version" | tail -n1)"
+echo "Gem Version: ${gem_version}"
 
-tag_gt_version=$(ruby -r ./lib/faulty/version -e "puts Faulty.version >= Gem::Version.new('${tag}')")
+tag_gt_version="$(ruby -r ./lib/faulty/version -e "puts Faulty.version >= Gem::Version.new('${tag}')" | tail -n1)"
 test "$tag_gt_version" = true

data/faulty.gemspec

@@ -26,8 +26,7 @@ Gem::Specification.new do |spec|
   # Only essential development tools and dependencies go here.
   # Other non-essential development dependencies go in the Gemfile.
   spec.add_development_dependency 'connection_pool', '~> 2.0'
-  spec.add_development_dependency 'honeybadger', '>= 2.0'
-  spec.add_development_dependency 'redis', '~> 3.0'
+  spec.add_development_dependency 'redis', '>= 3.0'
   spec.add_development_dependency 'rspec', '~> 3.8'
   # 0.81 is the last rubocop version with Ruby 2.3 support
   spec.add_development_dependency 'rubocop', '0.81.0'

data/lib/faulty.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'forwardable'
 require 'concurrent-ruby'
 
 require 'faulty/immutable_options'
@@ -8,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'
@@ -65,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
@@ -74,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
@@ -124,20 +135,28 @@ class Faulty
   # Options for {Faulty}
   #
   # @!attribute [r] cache
+  #   @see Cache::AutoWire
   #   @return [Cache::Interface] A cache backend if you want
   #     to use Faulty's cache support. Automatically wrapped in a
-  #     {Cache::FaultTolerantProxy}. Default `Cache::Default.new`.
+  #     {Cache::AutoWire}. Default `Cache::AutoWire.new`.
+  # @!attribute [r] circuit_defaults
+  #   @see Circuit::Options
+  #   @return [Hash] A hash of default options to be used when creating
+  #     new circuits. See {Circuit::Options} for a full list.
   # @!attribute [r] storage
-  #   @return [Storage::Interface] The storage backend.
-  #     Automatically wrapped in a {Storage::FaultTolerantProxy}.
-  #     Default `Storage::Memory.new`.
+  #   @see Storage::AutoWire
+  #   @return [Storage::Interface, Array<Storage::Interface>] The storage
+  #   backend. Automatically wrapped in a {Storage::AutoWire}, so this can also
+  #   be given an array of prioritized backends. Default `Storage::AutoWire.new`.
   # @!attribute [r] listeners
+  #   @see Events::ListenerInterface
   #   @return [Array] listeners Faulty event listeners
   # @!attribute [r] notifier
   #   @return [Events::Notifier] A Faulty notifier. If given, listeners are
   #     ignored.
   Options = Struct.new(
     :cache,
+    :circuit_defaults,
     :storage,
     :listeners,
     :notifier
@@ -148,24 +167,17 @@ class Faulty
 
     def finalize
       self.notifier ||= Events::Notifier.new(listeners || [])
-
-      self.storage ||= Storage::Memory.new
-      unless storage.fault_tolerant?
-        self.storage = Storage::FaultTolerantProxy.new(storage, notifier: notifier)
-      end
-
-      self.cache ||= Cache::Default.new
-      unless cache.fault_tolerant?
-        self.cache = Cache::FaultTolerantProxy.new(cache, notifier: notifier)
-      end
+      self.storage = Storage::AutoWire.wrap(storage, notifier: notifier)
+      self.cache = Cache::AutoWire.wrap(cache, notifier: notifier)
     end
 
     def required
-      %i[cache storage notifier]
+      %i[cache circuit_defaults storage notifier]
     end
 
     def defaults
       {
+        circuit_defaults: {},
         listeners: [Events::LogListener.new]
       }
     end
@@ -204,8 +216,8 @@ class Faulty
   # @return [Circuit] The new circuit or the existing circuit if it already exists
   def circuit(name, **options, &block)
     name = name.to_s
-    options = options.merge(circuit_options)
     @circuits.compute_if_absent(name) do
+      options = circuit_options.merge(options)
       Circuit.new(name, **options, &block)
     end
   end
@@ -223,8 +235,8 @@ class Faulty
   #
   # @return [Hash] The circuit options
   def circuit_options
-    options = @options.to_h
-    options.delete(:listeners)
-    options
+    @options.to_h
+      .select { |k, _v| %i[cache storage notifier].include?(k) }
+      .merge(options.circuit_defaults)
   end
 end

data/lib/faulty/cache.rb

@@ -6,7 +6,9 @@ class Faulty
   end
 end
 
+require 'faulty/cache/auto_wire'
 require 'faulty/cache/default'
+require 'faulty/cache/circuit_proxy'
 require 'faulty/cache/fault_tolerant_proxy'
 require 'faulty/cache/mock'
 require 'faulty/cache/null'

data/lib/faulty/cache/auto_wire.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Cache
+    # Automatically configure a cache backend
+    #
+    # Used by {Faulty#initialize} to setup sensible cache defaults
+    class AutoWire
+      # Options for {AutoWire}
+      #
+      # @!attribute [r] circuit
+      #   @return [Circuit] A circuit for {CircuitProxy} if one is created.
+      #     When modifying this, be careful to use only a reliable circuit
+      #     storage backend so that you don't introduce cascading failures.
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier. If given, listeners are
+      #     ignored.
+      Options = Struct.new(
+        :circuit,
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def required
+          %i[notifier]
+        end
+      end
+
+      class << self
+        # Wrap a cache backend with sensible defaults
+        #
+        # If the cache is `nil`, create a new {Default}.
+        #
+        # If the backend is not fault tolerant, wrap it in {CircuitProxy} and
+        # {FaultTolerantProxy}.
+        #
+        # @param cache [Interface] A cache backend
+        # @param options [Hash] Attributes for {Options}
+        # @yield [Options] For setting options in a block
+        def wrap(cache, **options, &block)
+          options = Options.new(options, &block)
+          if cache.nil?
+            Cache::Default.new
+          elsif cache.fault_tolerant?
+            cache
+          else
+            Cache::FaultTolerantProxy.new(
+              Cache::CircuitProxy.new(cache, circuit: options.circuit, notifier: options.notifier),
+              notifier: options.notifier
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faulty/cache/circuit_proxy.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Cache
+    # A circuit wrapper for cache backends
+    #
+    # This class uses an internal {Circuit} to prevent the cache backend from
+    # causing application issues. If the backend fails continuously, this
+    # circuit will trip to prevent cascading failures. This internal circuit
+    # uses an independent in-memory backend by default.
+    class CircuitProxy
+      attr_reader :options
+
+      # Options for {CircuitProxy}
+      #
+      # @!attribute [r] circuit
+      #   @return [Circuit] A replacement for the internal circuit. When
+      #     modifying this, be careful to use only a reliable circuit storage
+      #     backend so that you don't introduce cascading failures.
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier to use for failure
+      #     notifications. If `circuit` is given, this is ignored.
+      Options = Struct.new(
+        :circuit,
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def finalize
+          raise ArgumentError, 'The circuit or notifier option must be given' unless notifier || circuit
+
+          self.circuit ||= Circuit.new(
+            Faulty::Storage::CircuitProxy.name,
+            notifier: notifier,
+            cache: Cache::Null.new
+          )
+        end
+      end
+
+      # @param cache [Cache::Interface] The cache backend to wrap
+      # @param options [Hash] Attributes for {Options}
+      # @yield [Options] For setting options in a block
+      def initialize(cache, **options, &block)
+        @cache = cache
+        @options = Options.new(options, &block)
+      end
+
+      %i[read write].each do |method|
+        define_method(method) do |*args|
+          options.circuit.run { @cache.public_send(method, *args) }
+        end
+      end
+
+      def fault_tolerant?
+        @cache.fault_tolerant?
+      end
+    end
+  end
+end

data/lib/faulty/cache/default.rb

@@ -11,6 +11,8 @@ class Faulty
     # - If ActiveSupport is available, it will use an `ActiveSupport::Cache::MemoryStore`
     # - Otherwise it will use a {Faulty::Cache::Null}
     class Default
+      extend Forwardable
+
       def initialize
         @cache = if defined?(::Rails)
           Cache::Rails.new(::Rails.cache)
@@ -21,28 +23,15 @@ class Faulty
         end
       end
 
-      # Read from the internal cache by key
+      # @!method read(key)
+      #   (see Faulty::Cache::Interface#read)
       #
-      # @param (see Cache::Interface#read)
-      # @return (see Cache::Interface#read)
-      def read(key)
-        @cache.read(key)
-      end
-
-      # Write to the internal cache
+      # @!method write(key, value, expires_in: expires_in)
+      #   (see Faulty::Cache::Interface#write)
       #
-      # @param (see Cache::Interface#read)
-      # @return (see Cache::Interface#read)
-      def write(key, value, expires_in: nil)
-        @cache.write(key, value, expires_in: expires_in)
-      end
-
-      # This cache is fault tolerant if the internal one is
-      #
-      # @return [Boolean]
-      def fault_tolerant?
-        @cache.fault_tolerant?
-      end
+      # @!method fault_tolerant
+      #   (see Faulty::Cache::Interface#fault_tolerant?)
+      def_delegators :@cache, :read, :write, :fault_tolerant?
     end
   end
 end

data/lib/faulty/cache/fault_tolerant_proxy.rb

@@ -8,7 +8,8 @@ class Faulty
     # 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 @@ class 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 @@ class 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/rails.rb

@@ -5,6 +5,8 @@ class Faulty
     # 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 @@ class 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

@@ -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.
@@ -66,14 +69,19 @@ class 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 @@ class Faulty
       :rate_threshold,
       :sample_threshold,
       :errors,
+      :error_module,
       :exclude,
       :cache,
       :notifier,
@@ -98,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,
@@ -110,6 +120,7 @@ class Faulty
           cache
           cool_down
           errors
+          error_module
           exclude
           evaluation_window
           rate_threshold
@@ -208,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
@@ -277,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
@@ -287,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)
 
@@ -315,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?