faulty 0.2.0 → 0.3.0

data/lib/faulty/storage/fault_tolerant_proxy.rb

@@ -10,6 +10,8 @@ class Faulty
     # 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 @@ class 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
@@ -84,36 +133,6 @@ class 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 @@ class 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/memory.rb

@@ -4,8 +4,9 @@ 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 @@ class 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
 

data/lib/faulty/storage/redis.rb

@@ -2,6 +2,13 @@
 
 class Faulty
   module Storage
+    # A storage backend for storing circuit state in Redis.
+    #
+    # When using this or any networked backend, be sure to evaluate the risk,
+    # and set conservative timeouts so that the circuit storage does not cause
+    # cascading failures in your application when evaluating circuits. Always
+    # wrap this backend with a {FaultTolerantProxy} to limit the effect of
+    # these types of events.
     class Redis # rubocop:disable Metrics/ClassLength
       # Separates the time/status for history entry strings
       ENTRY_SEPARATOR = ':'
@@ -27,12 +34,17 @@ class Faulty
       #     circuit run history entry. Default `100`.
       # @!attribute [r] circuit_ttl
       #   @return [Integer] The maximum number of seconds to keep a circuit.
-      #     A value of `nil` disables circuit expiration.
+      #     A value of `nil` disables circuit expiration. This does not apply to
+      #     locks, which have an indefinite storage time.
       #     Default `604_800` (1 week).
       # @!attribute [r] list_granularity
       #   @return [Integer] The number of seconds after which a new set is
       #     created to store circuit names. The old set is kept until
       #     circuit_ttl expires. Default `3600` (1 hour).
+      # @!attribute [r] disable_warnings
+      #   @return [Boolean] By default, this class warns if the client options
+      #     are outside the recommended values. Set to true to disable these
+      #     warnings.
       Options = Struct.new(
         :client,
         :key_prefix,
@@ -40,7 +52,8 @@ class Faulty
         :max_sample_size,
         :sample_ttl,
         :circuit_ttl,
-        :list_granularity
+        :list_granularity,
+        :disable_warnings
       ) do
         include ImmutableOptions
 
@@ -53,7 +66,8 @@ class Faulty
             max_sample_size: 100,
             sample_ttl: 1800,
             circuit_ttl: 604_800,
-            list_granularity: 3600
+            list_granularity: 3600,
+            disable_warnings: false
           }
         end
 
@@ -62,7 +76,7 @@ class Faulty
         end
 
         def finalize
-          self.client = ::Redis.new unless client
+          self.client = ::Redis.new(timeout: 1) unless client
         end
       end
 
@@ -70,6 +84,8 @@ class Faulty
       # @yield [Options] For setting options in a block
       def initialize(**options, &block)
         @options = Options.new(options, &block)
+
+        check_client_options!
       end
 
       # Add an entry to storage
@@ -196,6 +212,9 @@ class Faulty
         map_entries(entries).reverse
       end
 
+      # List all unexpired circuits
+      #
+      # @return (see Interface#list)
       def list
         redis { |r| r.sunion(*all_list_keys) }
       end
@@ -330,6 +349,49 @@ class Faulty
           [time.to_i, state == '1']
         end
       end
+
+      def check_client_options!
+        return if options.disable_warnings
+
+        check_redis_options!
+        check_pool_options!
+      rescue StandardError => e
+        warn "Faulty error while checking client options: #{e.message}"
+      end
+
+      def check_redis_options!
+        ropts = redis { |r| r.client.options }
+
+        bad_timeouts = {}
+        %i[connect_timeout read_timeout write_timeout].each do |time_opt|
+          bad_timeouts[time_opt] = ropts[time_opt] if ropts[time_opt] > 2
+        end
+
+        unless bad_timeouts.empty?
+          warn <<~MSG
+            Faulty recommends setting Redis timeouts <= 2 to prevent cascading
+            failures when evaluating circuits. Your options are:
+            #{bad_timeouts}
+          MSG
+        end
+
+        if ropts[:reconnect_attempts] > 1
+          warn <<~MSG
+            Faulty recommends setting Redis reconnect_attempts to <= 1 to
+            prevent cascading failures. Your setting is #{ropts[:reconnect_attempts]}
+          MSG
+        end
+      end
+
+      def check_pool_options!
+        if options.client.is_a?(ConnectionPool)
+          timeout = options.client.instance_variable_get(:@timeout)
+          warn(<<~MSG) if timeout > 2
+            Faulty recommends setting ConnectionPool timeouts <= 2 to prevent
+            cascading failures when evaluating circuits. Your setting is #{timeout}
+          MSG
+        end
+      end
     end
   end
 end

data/lib/faulty/version.rb

@@ -3,6 +3,6 @@
 class Faulty
   # The current Faulty version
   def self.version
-    Gem::Version.new('0.2.0')
+    Gem::Version.new('0.3.0')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-18 00:00:00.000000000 Z
+date: 2020-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -148,6 +148,8 @@ files:
 - faulty.gemspec
 - lib/faulty.rb
 - lib/faulty/cache.rb
+- lib/faulty/cache/auto_wire.rb
+- lib/faulty/cache/circuit_proxy.rb
 - lib/faulty/cache/default.rb
 - lib/faulty/cache/fault_tolerant_proxy.rb
 - lib/faulty/cache/interface.rb
@@ -166,6 +168,9 @@ files:
 - lib/faulty/result.rb
 - lib/faulty/status.rb
 - lib/faulty/storage.rb
+- lib/faulty/storage/auto_wire.rb
+- lib/faulty/storage/circuit_proxy.rb
+- lib/faulty/storage/fallback_chain.rb
 - lib/faulty/storage/fault_tolerant_proxy.rb
 - lib/faulty/storage/interface.rb
 - lib/faulty/storage/memory.rb