faulty 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d963d5c58861cc9e39c3222b5dc78a2a537c15fc10e0ed76d9d5b41a6704356b
-  data.tar.gz: e31811fc1b5be36975982e966106ea7f323b4e334b87cfaca85667f550245584
+  metadata.gz: 815cc1b7ac571e9dc69546efd1b3892795a5ef284cc43448b8a6c1feadcf49c3
+  data.tar.gz: 575c2e0e7abb413f8866a0e159129a6f1ecc76149e8d8cb97c65c7ffd9913ba9
 SHA512:
-  metadata.gz: 52aae6a3997fca7d38aebd124399747ee21a687114076e5d73c135d86ab147360e71a9f7a95ee4a5f548b6709089697e77fa472730c3fc18cb9c1d412bdac4ca
-  data.tar.gz: 56b02cad8fe96373c916746bfc7c6f83665a74e7a3771d7b761244373b1d4b79aeb44d94fbe9401f82f8671b4e21c625a079b4845a42565dfbfbdfd37a07d2bf
+  metadata.gz: 6effebfa578717256dc4ef7ec1c59a5f694eff2c78b21edb1649375a3f7ab62bbad597e3e4a0dc63cd729b4e66b4079ea9cbfd72795a1bfd34a9fab489415847
+  data.tar.gz: 2ba730eaa396ce24cb9d4eaf3a35db84180eb5c8ba4e3f3bc803d389436870480bd542aa57c93089ef33b77afe3f9b0c8614f972d232b971d8310f2dd067eb39

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## Release v0.8.0
+
+* Store circuit options in the backend when run #34 justinhoward
+
+### Breaking Changes
+
+* Added #get_options and #set_options to Faulty::Storage::Interface.
+  These will need to be added to any custom backends
+* Faulty::Storage::Interface#reset now requires removing options in
+  addition to other stored values
+* Circuit options will now be supplemented by stored options until they
+  are run. This is technically a breaking change in behavior, although
+  in most cases this should cause the expected result.
+* Circuits are not memoized until they are run. Subsequent calls
+  to Faulty#circuit can return different instances if the circuit is
+  not run. However, once run, options are synchronized between
+  instances, so likely this will not be a breaking change for most
+  cases.
+
 ## Release v0.7.2
 
 * Add Faulty.disable! for disabling globally #38 justinhoward

data/README.md

@@ -608,7 +608,7 @@ faulty.circuit('standalone_circuit')
 ```
 
 Calling `#circuit` on the instance still has the same memoization behavior that
-`Faulty.circuit` has, so subsequent calls to the same circuit will return a
+`Faulty.circuit` has, so subsequent runs for the same circuit will use a
 memoized circuit object.
 
 
@@ -733,7 +733,7 @@ Both options can even be specified together.
 ```ruby
 Faulty.circuit(
   'api',
-  errors: [ActiveRecord::ActiveRecordError]
+  errors: [ActiveRecord::ActiveRecordError],
   exclude: [ActiveRecord::RecordNotFound, ActiveRecord::RecordNotUnique]
 ).run do
   # This only captures ActiveRecord::ActiveRecordError errors, but not
@@ -813,7 +813,7 @@ the options are retained within the context of each instance. All options given
 after the first call to `Faulty.circuit` (or `Faulty#circuit`) are ignored.
 
 ```ruby
-Faulty.circuit('api', rate_threshold: 0.7)
+Faulty.circuit('api', rate_threshold: 0.7).run { api.call }
 
 # These options are ignored since with already initialized the circuit
 circuit = Faulty.circuit('api', rate_threshold: 0.3)
@@ -821,7 +821,7 @@ circuit.options.rate_threshold # => 0.7
 ```
 
 This is because the circuit objects themselves are internally memoized, and are
-read-only once created.
+read-only once they are run.
 
 The following example represents the defaults for a new circuit:
 

data/faulty.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
   # Only essential development tools and dependencies go here.
   # Other non-essential development dependencies go in the Gemfile.
   spec.add_development_dependency 'connection_pool', '~> 2.0'
+  spec.add_development_dependency 'json'
   spec.add_development_dependency 'redis', '>= 3.0'
   spec.add_development_dependency 'rspec', '~> 3.8'
   # 0.81 is the last rubocop version with Ruby 2.3 support

data/lib/faulty/cache/auto_wire.rb

@@ -21,8 +21,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def required
           %i[notifier]
         end

data/lib/faulty/cache/circuit_proxy.rb

@@ -26,8 +26,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def finalize
           raise ArgumentError, 'The circuit or notifier option must be given' unless notifier || circuit
 

data/lib/faulty/cache/fault_tolerant_proxy.rb

@@ -22,8 +22,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def required
           %i[notifier]
         end

data/lib/faulty/circuit.rb

@@ -27,7 +27,6 @@ class Faulty
     CACHE_REFRESH_SUFFIX = '.faulty_refresh'
 
     attr_reader :name
-    attr_reader :options
 
     # Options for {Circuit}
     #
@@ -82,6 +81,9 @@ class Faulty
     #   @return [Storage::Interface] The storage backend. Default
     #   `Storage::Memory.new`. Unlike {Faulty#initialize}, this is not wrapped
     #    in {Storage::AutoWire} by default.
+    # @!attribute [r] registry
+    #   @return [CircuitRegistry] For use by {Faulty} instances to facilitate
+    #   memoization of circuits.
     Options = Struct.new(
       :cache_expires_in,
       :cache_refreshes_after,
@@ -95,11 +97,22 @@ class Faulty
       :exclude,
       :cache,
       :notifier,
-      :storage
+      :storage,
+      :registry
     ) do
       include ImmutableOptions
 
-      private
+      # Get the options stored in the storage backend
+      #
+      # @return [Hash] A hash of stored options
+      def for_storage
+        {
+          cool_down: cool_down,
+          evaluation_window: evaluation_window,
+          rate_threshold: rate_threshold,
+          sample_threshold: sample_threshold
+        }
+      end
 
       def defaults
         {
@@ -150,7 +163,59 @@ class Faulty
       raise ArgumentError, 'name must be a String' unless name.is_a?(String)
 
       @name = name
-      @options = Options.new(options, &block)
+      @given_options = Options.new(options, &block)
+      @pulled_options = nil
+      @options_pushed = false
+    end
+
+    # Get the options for this circuit
+    #
+    # If this circuit has been run, these will the options exactly as given
+    # to {.new}. However, if this circuit has not yet been run, these options
+    # will be supplemented by the last-known options from the circuit storage.
+    #
+    # Once a circuit is run, the given options are pushed to circuit storage to
+    # be persisted.
+    #
+    # This is to allow circuit objects to behave as expected in contexts where
+    # the exact options for a circuit are not known such as an admin dashboard
+    # or in a debug console.
+    #
+    # Note that this distinction isn't usually important unless using
+    # distributed circuit storage like the Redis storage backend.
+    #
+    # @example
+    #   Faulty.circuit('api', cool_down: 5).run { api.users }
+    #   # This status will be calculated using the cool_down of 5 because
+    #   # the circuit was already run
+    #   Faulty.circuit('api').status
+    #
+    # @example
+    #   # This status will be calculated using the cool_down in circuit storage
+    #   # if it is available instead of using the default value.
+    #   Faulty.circuit('api').status
+    #
+    # @example
+    #   # For typical usage, this behaves as expected, but note that it's
+    #   # possible to run into some unexpected behavior when creating circuits
+    #   # in unusual ways.
+    #
+    #   # For example, this status will be calculated using the cool_down in
+    #   # circuit storage if it is available despite the given value of 5.
+    #   Faulty.circuit('api', cool_down: 5).status
+    #   Faulty.circuit('api').run { api.users }
+    #   # However now, after the circuit is run, status will be calculated
+    #   # using the given cool_down of 5 and the value of 5 will be pushed
+    #   # permanently to circuit storage
+    #   Faulty.circuit('api').status
+    #
+    # @return [Options] The resolved options
+    def options
+      return @given_options if @options_pushed
+      return @pulled_options if @pulled_options
+
+      stored = @given_options.storage.get_options(self)
+      @pulled_options = stored ? @given_options.dup_with(stored) : @given_options
     end
 
     # Run the circuit as with {#run}, but return a {Result}
@@ -204,6 +269,8 @@ class Faulty
     # a second cool down period. However, if the circuit completes successfully,
     # the circuit will be closed and reset to its initial state.
     #
+    # When this is run, the given options are persisted to the storage backend.
+    #
     # @param cache [String, nil] A cache key, or nil if caching is not desired
     # @yield The block to protect with this circuit
     # @raise If the block raises an error not in the error list, or if the error
@@ -216,6 +283,7 @@ class Faulty
     #   circuit to trip
     # @return The return value of the block
     def run(cache: nil, &block)
+      push_options
       cached_value = cache_read(cache)
       # return cached unless cached.nil?
       return cached_value if !cached_value.nil? && !cache_should_refresh?(cache)
@@ -256,6 +324,8 @@ class Faulty
     #
     # @return [self]
     def reset!
+      @options_pushed = false
+      @pulled_options = nil
       storage.reset(self)
       self
     end
@@ -284,6 +354,25 @@ class Faulty
 
     private
 
+    # Push the given options to circuit storage and set those as the current
+    # options
+    #
+    # @return [void]
+    def push_options
+      return if @options_pushed
+
+      @pulled_options = nil
+      @options_pushed = true
+      resolved = options.registry&.resolve(self)
+      if resolved
+        # If another circuit instance was resolved, don't store these options
+        # Instead, copy the options from that circuit as if we were given those
+        @given_options = resolved.options
+      else
+        storage.set_options(self, @given_options.for_storage)
+      end
+    end
+
     # Process a skipped run
     #
     # @param cached_value The cached value if one is available
@@ -431,11 +520,13 @@ class Faulty
 
     # Alias to the storage engine from options
     #
+    # Always returns the value from the given options
+    #
     # @return [Storage::Interface]
     def storage
       return Faulty::Storage::Null.new if Faulty.disabled?
 
-      options.storage
+      @given_options.storage
     end
   end
 end

data/lib/faulty/circuit_registry.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Faulty
+  # Used by Faulty instances to track and memoize Circuits
+  #
+  # Whenever a circuit is requested by `Faulty#circuit`, it calls
+  # `#retrieve`. That will return a resolved circuit if there is one, or
+  # otherwise, it will create a new circuit instance.
+  #
+  # Once any circuit is run, the circuit calls `#resolve`. That saves
+  # the instance into the registry. Any calls to `#retrieve` after
+  # the circuit is resolved will result in the same instance being returned.
+  #
+  # However, before a circuit is resolved, calling `Faulty#circuit` will result
+  # in a new Circuit instance being created for every call. If multiples of
+  # these call `resolve`, only the first one will "win" and be memoized.
+  class CircuitRegistry
+    def initialize(circuit_options)
+      @circuit_options = circuit_options
+      @circuit_options[:registry] = self
+      @circuits = Concurrent::Map.new
+    end
+
+    # Retrieve a memoized circuit with the same name, or if none is yet
+    # resolved, create a new one.
+    #
+    # @param name [String] The name of the circuit
+    # @param options [Hash] Options for {Circuit::Options}
+    # @yield [Circuit::Options] For setting options in a block
+    # @return [Circuit] The new or memoized circuit
+    def retrieve(name, options, &block)
+      @circuits.fetch(name) do
+        options = @circuit_options.merge(options)
+        Circuit.new(name, **options, &block)
+      end
+    end
+
+    # Save and memoize the given circuit as the "canonical" instance for
+    # the circuit name
+    #
+    # If the name is already resolved, this will be ignored
+    #
+    # @return [Circuit, nil] If this circuit name is already resolved, the
+    #   already-resolved circuit
+    def resolve(circuit)
+      @circuits.put_if_absent(circuit.name, circuit)
+    end
+  end
+end

data/lib/faulty/immutable_options.rb

@@ -5,18 +5,23 @@ class Faulty
   module ImmutableOptions
     # @param hash [Hash] A hash of attributes to initialize with
     # @yield [self] Yields itself to the block to set options before freezing
-    def initialize(hash)
-      defaults.merge(hash).each { |key, value| self[key] = value }
+    def initialize(hash, &block)
+      setup(defaults.merge(hash), &block)
+    end
+
+    def dup_with(hash, &block)
+      dup.setup(hash, &block)
+    end
+
+    def setup(hash)
+      hash&.each { |key, value| self[key] = value }
       yield self if block_given?
       finalize
-      required.each do |key|
-        raise ArgumentError, "Missing required attribute #{key}" if self[key].nil?
-      end
+      guard_required!
       freeze
+      self
     end
 
-    private
-
     # A hash of default values to set before yielding to the block
     #
     # @return [Hash<Symbol, Object>]
@@ -36,5 +41,14 @@ class Faulty
     # @return [void]
     def finalize
     end
+
+    private
+
+    # Raise an error if required options are missing
+    def guard_required!
+      required.each do |key|
+        raise ArgumentError, "Missing required attribute #{key}" if self[key].nil?
+      end
+    end
   end
 end

data/lib/faulty/status.rb

@@ -147,8 +147,6 @@ class Faulty
       failure_rate >= options.rate_threshold
     end
 
-    private
-
     def finalize
       raise ArgumentError, "state must be a symbol in #{self.class}::STATES" unless STATES.include?(state)
       unless lock.nil? || LOCKS.include?(lock)

data/lib/faulty/storage/auto_wire.rb

@@ -21,8 +21,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def required
           %i[notifier]
         end

data/lib/faulty/storage/circuit_proxy.rb

@@ -26,8 +26,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def finalize
           raise ArgumentError, 'The circuit or notifier option must be given' unless notifier || circuit
 
@@ -47,7 +45,20 @@ class Faulty
         @options = Options.new(options, &block)
       end
 
-      %i[entry open reopen close lock unlock reset status history list].each do |method|
+      %i[
+        get_options
+        set_options
+        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

data/lib/faulty/storage/fallback_chain.rb

@@ -30,8 +30,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def required
           %i[notifier]
         end
@@ -49,6 +47,24 @@ class Faulty
         @options = Options.new(options, &block)
       end
 
+      # Get options from the first available storage backend
+      #
+      # @param (see Interface#get_options)
+      # @return (see Interface#get_options)
+      def get_options(circuit)
+        send_chain(:get_options, circuit) do |e|
+          options.notifier.notify(:storage_failure, circuit: circuit, action: :get_options, error: e)
+        end
+      end
+
+      # Try to set circuit options on all backends
+      #
+      # @param (see Interface#set_options)
+      # @return (see Interface#set_options)
+      def set_options(circuit, stored_options)
+        send_all(:set_options, circuit, stored_options)
+      end
+
       # Create a circuit entry in the first available storage backend
       #
       # @param (see Interface#entry)

data/lib/faulty/storage/fault_tolerant_proxy.rb

@@ -23,8 +23,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def required
           %i[notifier]
         end
@@ -85,6 +83,30 @@ class Faulty
       #   @return (see Interface#list)
       def_delegators :@storage, :lock, :unlock, :reset, :history, :list
 
+      # Get circuit options safely
+      #
+      # @see Interface#get_options
+      # @param (see Interface#get_options)
+      # @return (see Interface#get_options)
+      def get_options(circuit)
+        @storage.get_options(circuit)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :get_options, error: e)
+        nil
+      end
+
+      # Set circuit options safely
+      #
+      # @see Interface#get_options
+      # @param (see Interface#set_options)
+      # @return (see Interface#set_options)
+      def set_options(circuit, stored_options)
+        @storage.set_options(circuit, stored_options)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :set_options, error: e)
+        nil
+      end
+
       # Add a history entry safely
       #
       # @see Interface#entry

data/lib/faulty/storage/interface.rb

@@ -6,6 +6,29 @@ class Faulty
     #
     # This is for documentation only and is not loaded
     class Interface
+      # Get the options stored for circuit
+      #
+      # They should be returned exactly as given by {#set_options}
+      #
+      # @return [Hash] A hash of the options stored by {#set_options}. The keys
+      #   must be symbols.
+      def get_options(circuit)
+        raise NotImplementedError
+      end
+
+      # Store the options for a circuit
+      #
+      # They should be returned exactly as given by {#set_options}
+      #
+      # @param circuit [Circuit] The circuit to set options for
+      # @param options [Hash<Symbol, Object>] A hash of symbol option names to
+      #   circuit options. These option values are guranteed to be primive
+      #   values.
+      # @return [void]
+      def set_options(circuit, stored_options)
+        raise NotImplementedError
+      end
+
       # Add a circuit run entry to storage
       #
       # The backend may choose to store this in whatever manner it chooses as
@@ -99,7 +122,7 @@ class Faulty
       # Reset the circuit to a fresh state
       #
       # Clears all circuit status including entries, state, locks,
-      # opened_at, and any other values that would affect Status.
+      # opened_at, options, and any other values that would affect Status.
       #
       # No concurrency gurantees are provided for resetting
       #

data/lib/faulty/storage/memory.rb

@@ -33,8 +33,6 @@ class Faulty
       Options = Struct.new(:max_sample_size) do
         include ImmutableOptions
 
-        private
-
         def defaults
           { max_sample_size: 100 }
         end
@@ -43,7 +41,7 @@ class Faulty
       # The internal object for storing a circuit
       #
       # @private
-      MemoryCircuit = Struct.new(:state, :runs, :opened_at, :lock) do
+      MemoryCircuit = Struct.new(:state, :runs, :opened_at, :lock, :options) do
         def initialize
           self.state = Concurrent::Atom.new(:closed)
           self.runs = Concurrent::MVar.new([], dup_on_deref: true)
@@ -78,6 +76,24 @@ class Faulty
         @options = Options.new(options, &block)
       end
 
+      # Get the options stored for circuit
+      #
+      # @see Interface#get_options
+      # @param (see Interface#get_options)
+      # @return (see Interface#get_options)
+      def get_options(circuit)
+        fetch(circuit).options
+      end
+
+      # Store the options for a circuit
+      #
+      # @see Interface#set_options
+      # @param (see Interface#set_options)
+      # @return (see Interface#set_options)
+      def set_options(circuit, stored_options)
+        fetch(circuit).options = stored_options
+      end
+
       # Add an entry to storage
       #
       # @see Interface#entry

data/lib/faulty/storage/null.rb

@@ -11,6 +11,17 @@ class Faulty
         @instance
       end
 
+      # @param (see Interface#get_options)
+      # @return (see Interface#get_options)
+      def get_options(_circuit)
+        {}
+      end
+
+      # @param (see Interface#set_options)
+      # @return (see Interface#set_options)
+      def set_options(_circuit, _stored_options)
+      end
+
       # @param (see Interface#entry)
       # @return (see Interface#entry)
       def entry(_circuit, _time, _success)

data/lib/faulty/storage/redis.rb

@@ -57,8 +57,6 @@ class Faulty
       ) do
         include ImmutableOptions
 
-        private
-
         def defaults
           {
             key_prefix: 'faulty',
@@ -85,9 +83,37 @@ class Faulty
       def initialize(**options, &block)
         @options = Options.new(options, &block)
 
+        # Ensure JSON is available since we don't explicitly require it
+        JSON # rubocop:disable Lint/Void
+
         check_client_options!
       end
 
+      # Get the options stored for circuit
+      #
+      # @see Interface#get_options
+      # @param (see Interface#get_options)
+      # @return (see Interface#get_options)
+      def get_options(circuit)
+        json = redis { |r| r.get(options_key(circuit)) }
+        return if json.nil?
+
+        JSON.parse(json, symbolize_names: true)
+      end
+
+      # Store the options for a circuit
+      #
+      # These will be serialized as JSON
+      #
+      # @see Interface#set_options
+      # @param (see Interface#set_options)
+      # @return (see Interface#set_options)
+      def set_options(circuit, stored_options)
+        redis do |r|
+          r.set(options_key(circuit), JSON.dump(stored_options), ex: options.circuit_ttl)
+        end
+      end
+
       # Add an entry to storage
       #
       # @see Interface#entry
@@ -173,7 +199,8 @@ class Faulty
           r.del(
             entries_key(circuit),
             opened_at_key(circuit),
-            lock_key(circuit)
+            lock_key(circuit),
+            options_key(circuit)
           )
           r.set(state_key(circuit), 'closed', ex: options.circuit_ttl)
         end
@@ -239,6 +266,11 @@ class Faulty
         key('circuit', circuit.name, *parts)
       end
 
+      # @return [String] The key for circuit options
+      def options_key(circuit)
+        ckey(circuit, 'options')
+      end
+
       # @return [String] The key for circuit state
       def state_key(circuit)
         ckey(circuit, 'state')

data/lib/faulty/version.rb

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

data/lib/faulty.rb

@@ -10,6 +10,7 @@ require 'faulty/circuit'
 require 'faulty/error'
 require 'faulty/events'
 require 'faulty/patch'
+require 'faulty/circuit_registry'
 require 'faulty/result'
 require 'faulty/status'
 require 'faulty/storage'
@@ -226,8 +227,8 @@ class Faulty
   # @param options [Hash] Attributes for {Options}
   # @yield [Options] For setting options in a block
   def initialize(**options, &block)
-    @circuits = Concurrent::Map.new
     @options = Options.new(options, &block)
+    @registry = CircuitRegistry.new(circuit_options)
   end
 
   # Create or retrieve a circuit
@@ -243,10 +244,7 @@ class Faulty
   # @return [Circuit] The new circuit or the existing circuit if it already exists
   def circuit(name, **options, &block)
     name = name.to_s
-    @circuits.compute_if_absent(name) do
-      options = circuit_options.merge(options)
-      Circuit.new(name, **options, &block)
-    end
+    @registry.retrieve(name, options, &block)
   end
 
   # Get a list of all circuit names

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: faulty
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-09-02 00:00:00.000000000 Z
+date: 2021-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -144,6 +158,7 @@ files:
 - lib/faulty/cache/null.rb
 - lib/faulty/cache/rails.rb
 - lib/faulty/circuit.rb
+- lib/faulty/circuit_registry.rb
 - lib/faulty/error.rb
 - lib/faulty/events.rb
 - lib/faulty/events/callback_listener.rb