faulty 0.2.0 → 0.3.0

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

@@ -66,14 +66,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,

data/lib/faulty/error.rb

@@ -59,8 +59,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/storage.rb

@@ -6,6 +6,9 @@ class Faulty
   end
 end
 
+require 'faulty/storage/auto_wire'
+require 'faulty/storage/circuit_proxy'
+require 'faulty/storage/fallback_chain'
 require 'faulty/storage/fault_tolerant_proxy'
 require 'faulty/storage/memory'
 require 'faulty/storage/redis'

data/lib/faulty/storage/auto_wire.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Storage
+    # Automatically configure a storage backend
+    #
+    # Used by {Faulty#initialize} to setup sensible storage defaults
+    class AutoWire
+      extend Forwardable
+
+      # Options for {AutoWire}
+      Options = Struct.new(
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def required
+          %i[notifier]
+        end
+      end
+
+      # Wrap storage backends with sensible defaults
+      #
+      # If the cache is `nil`, create a new {Memory} storage.
+      #
+      # If a single storage backend is given and is fault tolerant, leave it
+      # unmodified.
+      #
+      # If a single storage backend is given and is not fault tolerant, wrap it
+      # in a {CircuitProxy} and a {FaultTolerantProxy}.
+      #
+      # If an array of storage backends is given, wrap each non-fault-tolerant
+      # entry in a {CircuitProxy} and create a {FallbackChain}. If none of the
+      # backends in the array are fault tolerant, also wrap the {FallbackChain}
+      # in a {FaultTolerantProxy}.
+      #
+      # @todo Consider using a {FallbackChain} for non-fault-tolerant storages
+      #   by default. This would fallback to a {Memory} storage. It would
+      #   require a more conservative implementation of {Memory} that could
+      #   limit the number of circuits stored. For now, users need to manually
+      #   configure fallbacks.
+      #
+      # @param storage [Interface, Array<Interface>] A storage backed or array
+      #   of storage backends to setup.
+      # @param options [Hash] Attributes for {Options}
+      # @yield [Options] For setting options in a block
+      def initialize(storage, **options, &block)
+        @options = Options.new(options, &block)
+        @storage = if storage.nil?
+          Memory.new
+        elsif storage.is_a?(Array)
+          wrap_array(storage)
+        elsif !storage.fault_tolerant?
+          wrap_one(storage)
+        else
+          storage
+        end
+
+        freeze
+      end
+
+      # @!method entry(circuit, time, success)
+      #   (see Faulty::Storage::Interface#entry)
+      #
+      # @!method open(circuit, opened_at)
+      #   (see Faulty::Storage::Interface#open)
+      #
+      # @!method reopen(circuit, opened_at, previous_opened_at)
+      #   (see Faulty::Storage::Interface#reopen)
+      #
+      # @!method close(circuit)
+      #   (see Faulty::Storage::Interface#close)
+      #
+      # @!method lock(circuit, state)
+      #   (see Faulty::Storage::Interface#lock)
+      #
+      # @!method unlock(circuit)
+      #   (see Faulty::Storage::Interface#unlock)
+      #
+      # @!method reset(circuit)
+      #   (see Faulty::Storage::Interface#reset)
+      #
+      # @!method status(circuit)
+      #   (see Faulty::Storage::Interface#status)
+      #
+      # @!method history(circuit)
+      #   (see Faulty::Storage::Interface#history)
+      #
+      # @!method list
+      #   (see Faulty::Storage::Interface#list)
+      #
+      def_delegators :@storage,
+        :entry, :open, :reopen, :close, :lock,
+        :unlock, :reset, :status, :history, :list
+
+      def fault_tolerant?
+        true
+      end
+
+      private
+
+      # Wrap an array of storage backends in a fault-tolerant FallbackChain
+      #
+      # @return [Storage::Interface] A fault-tolerant fallback chain
+      def wrap_array(array)
+        FaultTolerantProxy.wrap(FallbackChain.new(
+          array.map { |s| s.fault_tolerant? ? s : CircuitProxy.new(s, notifier: @options.notifier) },
+          notifier: @options.notifier
+        ), notifier: @options.notifier)
+      end
+
+      def wrap_one(storage)
+        FaultTolerantProxy.new(
+          CircuitProxy.new(storage, notifier: @options.notifier),
+          notifier: @options.notifier
+        )
+      end
+    end
+  end
+end

data/lib/faulty/storage/circuit_proxy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Storage
+    # A circuit wrapper for storage backends
+    #
+    # This class uses an internal {Circuit} to prevent the storage 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 storage backend
+      #     so that you don't introduce cascading failures.
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier to use for circuit
+      #     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 storage [Storage::Interface] The storage backend to wrap
+      # @param options [Hash] Attributes for {Options}
+      # @yield [Options] For setting options in a block
+      def initialize(storage, **options, &block)
+        @storage = storage
+        @options = Options.new(options, &block)
+      end
+
+      %i[entry open reopen close lock unlock reset status history list].each do |method|
+        define_method(method) do |*args|
+          options.circuit.run { @storage.public_send(method, *args) }
+        end
+      end
+
+      # This cache makes any storage fault tolerant, so this is always `true`
+      #
+      # @return [true]
+      def fault_tolerant?
+        @storage.fault_tolerant?
+      end
+    end
+  end
+end

data/lib/faulty/storage/fallback_chain.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Storage
+    # An prioritized list of storage backends
+    #
+    # If any backend fails, the next will be tried until one succeeds. This
+    # should typically be used when using a fault-prone backend such as
+    # {Storage::Redis}.
+    #
+    # This is used by {Faulty#initialize} if the `storage` option is set to an
+    # array.
+    #
+    # @example
+    #   # This storage will try Redis first, then fallback to memory storage
+    #   # if Redis is unavailable.
+    #   storage = Faulty::Storage::FallbackChain.new([
+    #     Faulty::Storage::Redis.new,
+    #     Faulty::Storage::Memory.new
+    #   ])
+    class FallbackChain
+      attr_reader :options
+
+      # Options for {FallbackChain}
+      #
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier
+      Options = Struct.new(
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def required
+          %i[notifier]
+        end
+      end
+
+      # Create a new {FallbackChain} to automatically fallback to reliable storage
+      #
+      # @param storages [Array<Storage::Interface>] An array of storage backends.
+      #   The primary storage should be specified first. If that one fails,
+      #   additional entries will be tried in sequence until one succeeds.
+      # @param options [Hash] Attributes for {Options}
+      # @yield [Options] For setting options in a block
+      def initialize(storages, **options, &block)
+        @storages = storages
+        @options = Options.new(options, &block)
+      end
+
+      # Create a circuit entry in the first available storage backend
+      #
+      # @param (see Interface#entry)
+      # @return (see Interface#entry)
+      def entry(circuit, time, success)
+        send_chain(:entry, circuit, time, success) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :entry, error: e)
+        end
+      end
+
+      # Open a circuit in the first available storage backend
+      #
+      # @param (see Interface#open)
+      # @return (see Interface#open)
+      def open(circuit, opened_at)
+        send_chain(:open, circuit, opened_at) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :open, error: e)
+        end
+      end
+
+      # Reopen a circuit in the first available storage backend
+      #
+      # @param (see Interface#reopen)
+      # @return (see Interface#reopen)
+      def reopen(circuit, opened_at, previous_opened_at)
+        send_chain(:reopen, circuit, opened_at, previous_opened_at) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :reopen, error: e)
+        end
+      end
+
+      # Close a circuit in the first available storage backend
+      #
+      # @param (see Interface#close)
+      # @return (see Interface#close)
+      def close(circuit)
+        send_chain(:close, circuit) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :close, error: e)
+        end
+      end
+
+      # Lock a circuit in all storage backends
+      #
+      # @param (see Interface#lock)
+      # @return (see Interface#lock)
+      def lock(circuit, state)
+        send_all(:lock, circuit, state)
+      end
+
+      # Unlock a circuit in all storage backends
+      #
+      # @param (see Interface#unlock)
+      # @return (see Interface#unlock)
+      def unlock(circuit)
+        send_all(:unlock, circuit)
+      end
+
+      # Reset a circuit in all storage backends
+      #
+      # @param (see Interface#reset)
+      # @return (see Interface#reset)
+      def reset(circuit)
+        send_all(:reset, circuit)
+      end
+
+      # Get the status of a circuit from the first available storage backend
+      #
+      # @param (see Interface#status)
+      # @return (see Interface#status)
+      def status(circuit)
+        send_chain(:status, circuit) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :status, error: e)
+        end
+      end
+
+      # Get the history of a circuit from the first available storage backend
+      #
+      # @param (see Interface#history)
+      # @return (see Interface#history)
+      def history(circuit)
+        send_chain(:history, circuit) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :history, error: e)
+        end
+      end
+
+      # Get the list of circuits from the first available storage backend
+      #
+      # @param (see Interface#list)
+      # @return (see Interface#list)
+      def list
+        send_chain(:list) do |e|
+          options.notifier.notify(:storage_failure, action: :list, error: e)
+        end
+      end
+
+      # This is fault tolerant if any of the available backends are fault tolerant
+      #
+      # @param (see Interface#fault_tolerant?)
+      # @return (see Interface#fault_tolerant?)
+      def fault_tolerant?
+        @storages.any?(&:fault_tolerant?)
+      end
+
+      private
+
+      # Call a method on the backend and return the first successful result
+      #
+      # Short-circuits, so that if a call succeeds, no additional backends are
+      # called.
+      #
+      # @param method [Symbol] The method to call
+      # @param args [Array] The arguments to send
+      # @raise [AllFailedError] AllFailedError if all backends fail
+      # @return The return value from the first successful call
+      def send_chain(method, *args)
+        errors = []
+        @storages.each do |s|
+          begin
+            return s.public_send(method, *args)
+          rescue StandardError => e
+            errors << e
+            yield e
+          end
+        end
+
+        raise AllFailedError.new("#{self.class}##{method} failed for all storage backends", errors)
+      end
+
+      # Call a method on every backend
+      #
+      # @param method [Symbol] The method to call
+      # @param args [Array] The arguments to send
+      # @raise [AllFailedError] AllFailedError if all backends fail
+      # @raise [PartialFailureError] PartialFailureError if some but not all
+      #   backends fail
+      # @return [nil]
+      def send_all(method, *args)
+        errors = []
+        @storages.each do |s|
+          begin
+            s.public_send(method, *args)
+          rescue StandardError => e
+            errors << e
+          end
+        end
+
+        if errors.empty?
+          nil
+        elsif errors.size < @storages.size
+          raise PartialFailureError.new("#{self.class}##{method} failed for some storage backends", errors)
+        else
+          raise AllFailedError.new("#{self.class}##{method} failed for all storage backends", errors)
+        end
+      end
+    end
+  end
+end