faulty 0.1.4 → 0.5.1

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] = false
+      end
+    end
+  end
+end

data/lib/faulty/patch/redis.rb

@@ -0,0 +1,60 @@
+# 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 redis connection options to enable
+    # circuit protection. This hash is a hash of circuit options for the
+    # internal circuit. The hash may also have a `:instance` key, which is the
+    # faulty instance to create the circuit from. `Faulty.default` will be
+    # used if no instance is given. The `:instance` key can also reference a
+    # registered Faulty instance or a global constantso that it can be set
+    # from config files. See {Patch.circuit_from_hash}.
+    #
+    # @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)
+
+      # Patches Redis to add the `:faulty` key
+      def initialize(options = {})
+        @faulty_circuit = Patch.circuit_from_hash(
+          'redis',
+          options[:faulty],
+          errors: [::Redis::BaseConnectionError],
+          patched_error_module: Faulty::Patch::Redis
+        )
+
+        super
+      end
+
+      # The initial connection is protected by a circuit
+      def connect
+        faulty_run { super }
+      end
+
+      # Reads/writes to redis are protected
+      def io(&block)
+        faulty_run { super }
+      end
+    end
+  end
+end
+
+::Redis::Client.prepend(Faulty::Patch::Redis)

data/lib/faulty/result.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # An approximation of the `Result` type from some strongly-typed languages.
   #
   # F#: https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/results
@@ -53,7 +53,7 @@ module Faulty
     #
     # @param ok An ok value
     # @param error [Error] An error instance
-    def initialize(ok: NOTHING, error: NOTHING) # rubocop:disable Naming/MethodParameterName
+    def initialize(ok: NOTHING, error: NOTHING)
       if ok.equal?(NOTHING) && error.equal?(NOTHING)
         raise ArgumentError, 'Result must have an ok or error value'
       end

data/lib/faulty/status.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The status of a circuit
   #
   # Includes information like the state and locks. Also calculates
@@ -144,9 +144,10 @@ module Faulty
 
     def finalize
       raise ArgumentError, "state must be a symbol in #{self.class}::STATES" unless STATES.include?(state)
-      unless lock.nil? || LOCKS.include?(state)
+      unless lock.nil? || LOCKS.include?(lock)
         raise ArgumentError, "lock must be a symbol in #{self.class}::LOCKS or nil"
       end
+      raise ArgumentError, 'opened_at is required if state is open' if state == :open && opened_at.nil?
     end
 
     def required

data/lib/faulty/storage.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The namespace for Faulty storage
   module Storage
   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,107 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Storage
+    # Automatically configure a storage backend
+    #
+    # Used by {Faulty#initialize} to setup sensible storage 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 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 wrap(storage, **options, &block)
+          options = Options.new(options, &block)
+          if storage.nil?
+            Memory.new
+          elsif storage.is_a?(Array)
+            wrap_array(storage, options)
+          elsif !storage.fault_tolerant?
+            wrap_one(storage, options)
+          else
+            storage
+          end
+        end
+
+        private
+
+        # Wrap an array of storage backends in a fault-tolerant FallbackChain
+        #
+        # @param [Array<Storage::Interface>] The array to wrap
+        # @param options [Options]
+        # @return [Storage::Interface] A fault-tolerant fallback chain
+        def wrap_array(array, options)
+          FaultTolerantProxy.wrap(FallbackChain.new(
+            array.map { |s| s.fault_tolerant? ? s : circuit_proxy(s, options) },
+            notifier: options.notifier
+          ), notifier: options.notifier)
+        end
+
+        # Wrap one storage backend in fault-tolerant backends
+        #
+        # @param [Storage::Interface] The storage to wrap
+        # @param options [Options]
+        # @return [Storage::Interface] A fault-tolerant storage backend
+        def wrap_one(storage, options)
+          FaultTolerantProxy.new(
+            circuit_proxy(storage, options),
+            notifier: options.notifier
+          )
+        end
+
+        # Wrap storage in a CircuitProxy
+        #
+        # @param [Storage::Interface] The storage to wrap
+        # @param options [Options]
+        # @return [CircuitProxy]
+        def circuit_proxy(storage, options)
+          CircuitProxy.new(storage, circuit: options.circuit, notifier: options.notifier)
+        end
+      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