faulty 0.1.1 → 0.3.0

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

data/lib/faulty/storage/fault_tolerant_proxy.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Storage
     # A wrapper for storage backends that may raise errors
     #
-    # {Scope} automatically wraps all non-fault-tolerant storage backends with
+    # {Faulty#initialize} automatically wraps all non-fault-tolerant storage backends with
     # this class.
     #
     # If the storage backend raises a `StandardError`, it will be captured and
     # sent to the notifier.
     class FaultTolerantProxy
+      extend Forwardable
+
       attr_reader :options
 
       # Options for {FaultTolerantProxy}
@@ -36,6 +38,53 @@ module Faulty
         @options = Options.new(options, &block)
       end
 
+      # Wrap a storage backend in a FaultTolerantProxy unless it's already
+      # fault tolerant
+      #
+      # @param storage [Storage::Interface] The storage to maybe wrap
+      # @return [Storage::Interface] The original storage or a {FaultTolerantProxy}
+      def self.wrap(storage, **options, &block)
+        return storage if storage.fault_tolerant?
+
+        new(storage, **options, &block)
+      end
+
+      # @!method lock(circuit, state)
+      #   Lock is not called in normal operation, so it doesn't capture errors
+      #
+      #   @see Interface#lock
+      #   @param (see Interface#lock)
+      #   @return (see Interface#lock)
+      #
+      # @!method unlock(circuit)
+      #   Unlock is not called in normal operation, so it doesn't capture errors
+      #
+      #   @see Interface#unlock
+      #   @param (see Interface#unlock)
+      #   @return (see Interface#unlock)
+      #
+      # @!method reset(circuit)
+      #   Reset is not called in normal operation, so it doesn't capture errors
+      #
+      #   @see Interface#reset
+      #   @param (see Interface#reset)
+      #   @return (see Interface#reset)
+      #
+      # @!method history(circuit)
+      #   History is not called in normal operation, so it doesn't capture errors
+      #
+      #   @see Interface#history
+      #   @param (see Interface#history)
+      #   @return (see Interface#history)
+      #
+      # @!method list
+      #   List is not called in normal operation, so it doesn't capture errors
+      #
+      #   @see Interface#list
+      #   @param (see Interface#list)
+      #   @return (see Interface#list)
+      def_delegators :@storage, :lock, :unlock, :reset, :history, :list
+
       # Add a history entry safely
       #
       # @see Interface#entry
@@ -53,8 +102,8 @@ module Faulty
       # @see Interface#open
       # @param (see Interface#open)
       # @return (see Interface#open)
-      def open(circuit)
-        @storage.open(circuit)
+      def open(circuit, opened_at)
+        @storage.open(circuit, opened_at)
       rescue StandardError => e
         options.notifier.notify(:storage_failure, circuit: circuit, action: :open, error: e)
         false
@@ -65,8 +114,8 @@ module Faulty
       # @see Interface#reopen
       # @param (see Interface#reopen)
       # @return (see Interface#reopen)
-      def reopen(circuit)
-        @storage.reopen(circuit)
+      def reopen(circuit, opened_at, previous_opened_at)
+        @storage.reopen(circuit, opened_at, previous_opened_at)
       rescue StandardError => e
         options.notifier.notify(:storage_failure, circuit: circuit, action: :reopen, error: e)
         false
@@ -84,36 +133,6 @@ module Faulty
         false
       end
 
-      # Since lock is not called in normal operation, it does not capture
-      # errors
-      #
-      # @see Interface#lock
-      # @param (see Interface#lock)
-      # @return (see Interface#lock)
-      def lock(circuit, state)
-        @storage.lock(circuit, state)
-      end
-
-      # Since unlock is not called in normal operation, it does not capture
-      # errors
-      #
-      # @see Interface#unlock
-      # @param (see Interface#unlock)
-      # @return (see Interface#unlock)
-      def unlock(circuit)
-        @storage.unlock(circuit)
-      end
-
-      # Since reset is not called in normal operation, it does not capture
-      # errors
-      #
-      # @see Interface#reset
-      # @param (see Interface#reset)
-      # @return (see Interface#reset)
-      def reset(circuit)
-        @storage.reset(circuit)
-      end
-
       # Safely get the status of a circuit
       #
       # If the backend is unavailable, this returns a stub status that
@@ -129,30 +148,6 @@ module Faulty
         stub_status(circuit)
       end
 
-      # Since history is not called in normal operation, it does not capture
-      # errors
-      #
-      # @see Interface#history
-      # @param (see Interface#history)
-      # @return (see Interface#history)
-      def history(circuit)
-        @storage.history(circuit)
-      end
-
-      # Safely get the list of circuit names
-      #
-      # If the backend is unavailable, this returns an empty array
-      #
-      # @see Interface#list
-      # @param (see Interface#list)
-      # @return (see Interface#list)
-      def list
-        @storage.list
-      rescue StandardError => e
-        options.notifier.notify(:storage_failure, action: :list, error: e)
-        []
-      end
-
       # This cache makes any storage fault tolerant, so this is always `true`
       #
       # @return [true]

data/lib/faulty/storage/interface.rb

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

data/lib/faulty/storage/memory.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Storage
     # The default in-memory storage for circuits
     #
-    # This implementation is most suitable to single-process, low volume
-    # usage. It is thread-safe and circuit state is shared across threads.
+    # This implementation is thread-safe and circuit state is shared across
+    # threads. Since state is stored in-memory, this state is not shared across
+    # processes, or persisted across application restarts.
     #
     # Circuit state and runs are stored in memory. Although runs have a maximum
     # size within a circuit, there is no limit on the number of circuits that
@@ -18,6 +19,9 @@ module Faulty
     #
     # This can be used as a reference implementation for storage backends that
     # store a list of circuit run entries.
+    #
+    # @todo Add a more sophsticated implmentation that can limit the number of
+    #   circuits stored.
     class Memory
       attr_reader :options
 
@@ -83,7 +87,7 @@ module Faulty
         memory = fetch(circuit)
         memory.runs.borrow do |runs|
           runs.push([time, success])
-          runs.pop if runs.size > options.max_sample_size
+          runs.shift if runs.size > options.max_sample_size
         end
         memory.status(circuit.options)
       end