faulty 0.1.4 → 0.5.1

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
@@ -45,7 +94,7 @@ module Faulty
         @storage.entry(circuit, time, success)
       rescue StandardError => e
         options.notifier.notify(:storage_failure, circuit: circuit, action: :entry, error: e)
-        stub_status(circuit)
+        []
       end
 
       # Safely mark a circuit as open
@@ -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
     #
@@ -14,7 +14,8 @@ module Faulty
       # @param circuit [Circuit] The circuit that ran
       # @param time [Integer] The unix timestamp for the run
       # @param success [Boolean] True if the run succeeded
-      # @return [Status] The circuit status after the run is added
+      # @return [Array<Array>] An array of the new history tuples after adding
+      #   the new entry, see {#history}
       def entry(circuit, time, success)
         raise NotImplementedError
       end

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
 
@@ -85,7 +89,7 @@ module Faulty
           runs.push([time, success])
           runs.shift if runs.size > options.max_sample_size
         end
-        memory.status(circuit.options)
+        memory.runs.value
       end
 
       # Mark a circuit as open

data/lib/faulty/storage/redis.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
-module Faulty
+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 @@ module 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 @@ module Faulty
         :max_sample_size,
         :sample_ttl,
         :circuit_ttl,
-        :list_granularity
+        :list_granularity,
+        :disable_warnings
       ) do
         include ImmutableOptions
 
@@ -53,7 +66,8 @@ module 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 @@ module Faulty
         end
 
         def finalize
-          self.client = ::Redis.new unless client
+          self.client = ::Redis.new(timeout: 1) unless client
         end
       end
 
@@ -70,6 +84,8 @@ module 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
@@ -79,15 +95,15 @@ module Faulty
       # @return (see Interface#entry)
       def entry(circuit, time, success)
         key = entries_key(circuit)
-        pipe do |r|
+        result = pipe do |r|
           r.sadd(list_key, circuit.name)
           r.expire(list_key, options.circuit_ttl + options.list_granularity) if options.circuit_ttl
           r.lpush(key, "#{time}#{ENTRY_SEPARATOR}#{success ? 1 : 0}")
           r.ltrim(key, 0, options.max_sample_size - 1)
           r.expire(key, options.sample_ttl) if options.sample_ttl
+          r.lrange(key, 0, -1)
         end
-
-        status(circuit)
+        map_entries(result.last)
       end
 
       # Mark a circuit as open
@@ -97,7 +113,7 @@ module Faulty
       # @return (see Interface#open)
       def open(circuit, opened_at)
         redis do |r|
-          opened = compare_and_set(r, state_key(circuit), ['closed', nil], 'open')
+          opened = compare_and_set(r, state_key(circuit), ['closed', nil], 'open', ex: options.circuit_ttl)
           r.set(opened_at_key(circuit), opened_at, ex: options.circuit_ttl) if opened
           opened
         end
@@ -110,7 +126,7 @@ module Faulty
       # @return (see Interface#reopen)
       def reopen(circuit, opened_at, previous_opened_at)
         redis do |r|
-          compare_and_set(r, opened_at_key(circuit), [previous_opened_at.to_s], opened_at)
+          compare_and_set(r, opened_at_key(circuit), [previous_opened_at.to_s], opened_at, ex: options.circuit_ttl)
         end
       end
 
@@ -121,7 +137,7 @@ module Faulty
       # @return (see Interface#close)
       def close(circuit)
         redis do |r|
-          closed = compare_and_set(r, state_key(circuit), ['open'], 'closed')
+          closed = compare_and_set(r, state_key(circuit), ['open'], 'closed', ex: options.circuit_ttl)
           r.del(entries_key(circuit)) if closed
           closed
         end
@@ -196,6 +212,9 @@ module Faulty
         map_entries(entries).reverse
       end
 
+      # List all unexpired circuits
+      #
+      # @return (see Interface#list)
       def list
         redis { |r| r.sunion(*all_list_keys) }
       end
@@ -287,10 +306,10 @@ module Faulty
       # @param new [String] The new value to set if the compare passes
       # @return [Boolean] True if the value was set to `new`, false if the CAS
       #   failed
-      def compare_and_set(redis, key, old, new)
+      def compare_and_set(redis, key, old, new, ex:)
         redis.watch(key) do
           if old.include?(redis.get(key))
-            result = redis.multi { |m| m.set(key, new) }
+            result = redis.multi { |m| m.set(key, new, ex: ex) }
             result && result[0] == 'OK'
           else
             redis.unwatch
@@ -330,6 +349,49 @@ module 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.instance_variable_get(:@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.class.name == '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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The current Faulty version
   def self.version
-    Gem::Version.new('0.1.4')
+    Gem::Version.new('0.5.1')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.5.1
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-18 00:00:00.000000000 Z
+date: 2021-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -56,14 +56,14 @@ dependencies:
   name: redis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
@@ -129,10 +129,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -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
@@ -163,10 +165,15 @@ files:
 - lib/faulty/events/log_listener.rb
 - lib/faulty/events/notifier.rb
 - lib/faulty/immutable_options.rb
+- lib/faulty/patch.rb
+- lib/faulty/patch/base.rb
+- lib/faulty/patch/redis.rb
 - lib/faulty/result.rb
-- lib/faulty/scope.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
@@ -191,7 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Fault-tolerance tools for ruby based on circuit-breakers