faulty 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fe02d7203e9d26a8f859d55efa9ffbe099ab6c2cf025fe7ca831c6ccdfd684f
-  data.tar.gz: bed9fe698b66b367dab9066ffec98567c60fd8dd57f9ea3ed7ea3a2a3a4a3b48
+  metadata.gz: 815cc1b7ac571e9dc69546efd1b3892795a5ef284cc43448b8a6c1feadcf49c3
+  data.tar.gz: 575c2e0e7abb413f8866a0e159129a6f1ecc76149e8d8cb97c65c7ffd9913ba9
 SHA512:
-  metadata.gz: c69668b5b99fc2dad979031bd3a61e61d608c8f1c8ba095924709f3cea1b653a4116edcc45a72fb4d3b72e367a3e8b56d7c3cd3d56ed03aadb0ae48be6f3d7bc
-  data.tar.gz: 97d9ff9d9f6bb368ca395b9338bc52b83ef545f67a1f412729b52aef997f6187d57f28fbfda989584e7d26e5e300127f075699f60b888746eaa0c48a2e3b3656
+  metadata.gz: 6effebfa578717256dc4ef7ec1c59a5f694eff2c78b21edb1649375a3f7ab62bbad597e3e4a0dc63cd729b4e66b4079ea9cbfd72795a1bfd34a9fab489415847
+  data.tar.gz: 2ba730eaa396ce24cb9d4eaf3a35db84180eb5c8ba4e3f3bc803d389436870480bd542aa57c93089ef33b77afe3f9b0c8614f972d232b971d8310f2dd067eb39

data/CHANGELOG.md

@@ -1,3 +1,40 @@
+## 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
+* Suppress circuit_success for proxy circuits #39 justinhoward
+
+## Release v0.7.1
+
+* Fix success event crash in log listener #37 justinhoward
+
+## Release v0.7.0
+
+* Add initial benchmarks and performance improvements #36 justinhoward
+
+### Breaking Changes
+
+The `circuit_success` event no longer contains the status value. Computing this
+value was causing performance problems.
+
 ## Release v0.6.0
 
 * docs, use correct state in description for skipped event #27 senny

data/README.md

@@ -88,6 +88,7 @@ Also see "Release It!: Design and Deploy Production-Ready Software" by
   + [CallbackListener](#callbacklistener)
   + [Other Built-in Listeners](#other-built-in-listeners)
   + [Custom Listeners](#custom-listeners)
+* [Disabling Faulty Globally](#disabling-faulty-globally)
 * [How it Works](#how-it-works)
   + [Caching](#caching)
   + [Fault Tolerance](#fault-tolerance)
@@ -607,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.
 
 
@@ -732,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
@@ -812,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)
@@ -820,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:
 
@@ -1064,8 +1065,7 @@ events. The full list of events is available from
   half-open. Payload: `circuit`, `error`.
 - `circuit_skipped` - A circuit execution was skipped because the circuit is
   open. Payload: `circuit`
-- `circuit_success` - A circuit execution was successful. Payload: `circuit`,
-  `status`
+- `circuit_success` - A circuit execution was successful. Payload: `circuit`
 - `storage_failure` - A storage backend raised an error. Payload `circuit` (can
   be nil), `action`, `error`
 
@@ -1125,6 +1125,21 @@ Faulty.init do |config|
 end
 ```
 
+## Disabling Faulty Globally
+
+For testing or for some environments, you may wish to disable Faulty circuits
+at a global level.
+
+```ruby
+Faulty.disable!
+```
+
+This only affects the process where you run the `#disable!` method and it does
+not affect the stored state of circuits.
+
+Faulty will **still use the cache** even when disabled. If you also want to
+disable the cache, configure Faulty to use a `Faulty::Cache::Null` cache.
+
 ## How it Works
 
 Faulty implements a version of circuit breakers inspired by "Release It!: Design

data/bin/benchmark

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'benchmark'
+require 'faulty'
+
+n = 100_000
+
+puts "Starting circuit benchmarks with #{n} iterations each\n\n"
+
+Benchmark.bm(25) do |b|
+  in_memory = Faulty.new(listeners: [])
+  b.report('memory storage') do
+    n.times { in_memory.circuit(:memory).run { true } }
+  end
+
+  b.report('memory storage failures') do
+    n.times do
+      begin
+        in_memory.circuit(:memory_fail, sample_threshold: n + 1).run { raise 'fail' }
+      rescue StandardError
+        # Expected to raise here
+      end
+    end
+  end
+
+  in_memory_large = Faulty.new(listeners: [], storage: Faulty::Storage::Memory.new(max_sample_size: 1000))
+  b.report('large memory storage') do
+    n.times { in_memory_large.circuit(:memory_large).run { true } }
+  end
+end
+
+n = 1_000_000
+
+puts "\n\nStarting extra benchmarks with #{n} iterations each\n\n"
+
+Benchmark.bm(25) do |b|
+  in_memory = Faulty.new(listeners: [])
+
+  log_listener = Faulty::Events::LogListener.new(Logger.new(File::NULL))
+  log_circuit = in_memory.circuit(:log_listener)
+  log_status = log_circuit.status
+  b.report('log listener success') do
+    n.times { log_listener.handle(:circuit_success, circuit: log_circuit, status: log_status) }
+  end
+
+  log_error = StandardError.new('test error')
+  b.report('log listener failure') do
+    n.times { log_listener.handle(:circuit_failure, error: log_error, circuit: log_circuit, status: log_status) }
+  end
+end

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,14 +26,12 @@ class Faulty
       ) 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,
+            notifier: Events::FilterNotifier.new(notifier, exclude: %i[circuit_success]),
             cache: Cache::Null.new
           )
         end

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
@@ -319,12 +408,10 @@ class Faulty
 
     # @return [Boolean] True if the circuit transitioned to closed
     def success!(status)
-      entries = storage.entry(self, Faulty.current_time, true)
-      status = Status.from_entries(entries, **status.to_h)
-      closed = false
-      closed = close! if should_close?(status)
+      storage.entry(self, Faulty.current_time, true)
+      closed = close! if status.half_open?
 
-      options.notifier.notify(:circuit_success, circuit: self, status: status)
+      options.notifier.notify(:circuit_success, circuit: self)
       closed
     end
 
@@ -370,16 +457,6 @@ class Faulty
       closed
     end
 
-    # Test whether we should close after a successful run
-    #
-    # Currently this is always true if the circuit is half-open, which is the
-    # traditional behavior for a circuit-breaker
-    #
-    # @return [Boolean] True if we should close the circuit from half-open
-    def should_close?(status)
-      status.half_open?
-    end
-
     # Read from the cache if it is configured
     #
     # @param key The key to read from the cache
@@ -443,9 +520,13 @@ class Faulty
 
     # Alias to the storage engine from options
     #
+    # Always returns the value from the given options
+    #
     # @return [Storage::Interface]
     def storage
-      options.storage
+      return Faulty::Storage::Null.new if Faulty.disabled?
+
+      @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/events/callback_listener.rb

@@ -23,7 +23,7 @@ class Faulty
       # @param (see ListenerInterface#handle)
       # @return [void]
       def handle(event, payload)
-        return unless EVENTS.include?(event)
+        return unless EVENT_SET.include?(event)
         return unless @handlers.key?(event)
 
         @handlers[event].each do |handler|

data/lib/faulty/events/filter_notifier.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Events
+    # Wraps a Notifier and filters events by name
+    class FilterNotifier
+      # @param notifier [Notifier] The internal notifier to filter events for
+      # @param events [Array, nil] An array of events to allow. If nil, all
+      #   {EVENTS} will be used
+      # @param exclude [Array, nil] An array of events to disallow. If nil,
+      #   no events will be disallowed. Takes priority over `events`.
+      def initialize(notifier, events: nil, exclude: nil)
+        @notifier = notifier
+        @events = Set.new(events || EVENTS)
+        exclude&.each { |e| @events.delete(e) }
+      end
+
+      # Notify all listeners of an event
+      #
+      # If a listener raises an error while handling an event, that error will
+      # be captured and written to STDERR.
+      #
+      # @param (see Notifier)
+      def notify(event, payload)
+        return unless @events.include?(event)
+
+        @notifier.notify(event, payload)
+      end
+    end
+  end
+end

data/lib/faulty/events/honeybadger_listener.rb

@@ -8,11 +8,19 @@ class Faulty
     #
     # The honeybadger gem must be available.
     class HoneybadgerListener
+      HONEYBADGER_EVENTS = Set[
+        :circuit_failure,
+        :circuit_opened,
+        :circuit_reopened,
+        :cache_failure,
+        :storage_failure
+      ].freeze
+
       # (see ListenerInterface#handle)
       def handle(event, payload)
-        return unless EVENTS.include?(event)
+        return unless HONEYBADGER_EVENTS.include?(event)
 
-        send(event, payload) if respond_to?(event, true)
+        send(event, payload)
       end
 
       private

data/lib/faulty/events/log_listener.rb

@@ -16,9 +16,9 @@ class Faulty
 
       # (see ListenerInterface#handle)
       def handle(event, payload)
-        return unless EVENTS.include?(event)
+        return unless EVENT_SET.include?(event)
 
-        send(event, payload) if respond_to?(event, true)
+        send(event, payload)
       end
 
       private
@@ -36,7 +36,7 @@ class Faulty
       end
 
       def circuit_success(payload)
-        log(:debug, 'Circuit succeeded', payload[:circuit].name, state: payload[:status].state)
+        log(:debug, 'Circuit succeeded', payload[:circuit].name)
       end
 
       def circuit_failure(payload)
@@ -79,8 +79,12 @@ class Faulty
       end
 
       def log(level, msg, action, extra = {})
-        extra_str = extra.map { |k, v| "#{k}=#{v}" }.join(' ')
-        logger.public_send(level, "#{msg}: #{action} #{extra_str}")
+        @logger.public_send(level) do
+          extra_str = extra.map { |k, v| "#{k}=#{v}" }.join(' ')
+          extra_str = " #{extra_str}" unless extra_str.empty?
+
+          "#{msg}: #{action}#{extra_str}"
+        end
       end
     end
   end

data/lib/faulty/events.rb

@@ -17,6 +17,8 @@ class Faulty
       circuit_success
       storage_failure
     ].freeze
+
+    EVENT_SET = Set.new(EVENTS)
   end
 end
 
@@ -24,3 +26,4 @@ require 'faulty/events/callback_listener'
 require 'faulty/events/honeybadger_listener'
 require 'faulty/events/log_listener'
 require 'faulty/events/notifier'
+require 'faulty/events/filter_notifier'

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

@@ -64,10 +64,17 @@ class Faulty
     #   sample_size
     # @return [Status]
     def self.from_entries(entries, **hash)
+      window_start = Faulty.current_time - hash[:options].evaluation_window
+      size = entries.size
+      i = 0
       failures = 0
       sample_size = 0
-      entries.each do |(time, success)|
-        next unless time > Faulty.current_time - hash[:options].evaluation_window
+
+      # This is a hot loop, and while is slightly faster than each
+      while i < size
+        time, success = entries[i]
+        i += 1
+        next unless time > window_start
 
         sample_size += 1
         failures += 1 unless success
@@ -140,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,14 +26,12 @@ class Faulty
       ) 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,
+            notifier: Events::FilterNotifier.new(notifier, exclude: %i[circuit_success]),
             cache: Cache::Null.new
           )
         end
@@ -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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Storage
+    # A no-op backend for disabling circuits
+    class Null
+      # Define a single global instance
+      @instance = new
+
+      def self.new
+        @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)
+        []
+      end
+
+      # @param (see Interface#open)
+      # @return (see Interface#open)
+      def open(_circuit, _opened_at)
+        true
+      end
+
+      # @param (see Interface#reopen)
+      # @return (see Interface#reopen)
+      def reopen(_circuit, _opened_at, _previous_opened_at)
+        true
+      end
+
+      # @param (see Interface#close)
+      # @return (see Interface#close)
+      def close(_circuit)
+        true
+      end
+
+      # @param (see Interface#lock)
+      # @return (see Interface#lock)
+      def lock(_circuit, _state)
+      end
+
+      # @param (see Interface#unlock)
+      # @return (see Interface#unlock)
+      def unlock(_circuit)
+      end
+
+      # @param (see Interface#reset)
+      # @return (see Interface#reset)
+      def reset(_circuit)
+      end
+
+      # @param (see Interface#status)
+      # @return (see Interface#status)
+      def status(circuit)
+        Faulty::Status.new(
+          options: circuit.options,
+          stub: true
+        )
+      end
+
+      # @param (see Interface#history)
+      # @return (see Interface#history)
+      def history(_circuit)
+        []
+      end
+
+      # @param (see Interface#list)
+      # @return (see Interface#list)
+      def list
+        []
+      end
+
+      # This backend is fault tolerant
+      #
+      # @param (see Interface#fault_tolerant?)
+      # @return (see Interface#fault_tolerant?)
+      def fault_tolerant?
+        true
+      end
+    end
+  end
+end

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/storage.rb

@@ -10,5 +10,6 @@ require 'faulty/storage/auto_wire'
 require 'faulty/storage/circuit_proxy'
 require 'faulty/storage/fallback_chain'
 require 'faulty/storage/fault_tolerant_proxy'
+require 'faulty/storage/null'
 require 'faulty/storage/memory'
 require 'faulty/storage/redis'

data/lib/faulty/version.rb

@@ -3,6 +3,6 @@
 class Faulty
   # The current Faulty version
   def self.version
-    Gem::Version.new('0.6.0')
+    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'
@@ -128,6 +129,33 @@ class Faulty
     def current_time
       Time.now.to_i
     end
+
+    # Disable Faulty circuits
+    #
+    # This allows circuits to run as if they were always closed. Does
+    # not disable caching.
+    #
+    # Intended for use in tests, or to disable Faulty entirely for an
+    # environment.
+    #
+    # @return [void]
+    def disable!
+      @disabled = true
+    end
+
+    # Re-enable Faulty if disabled with {#disable!}
+    #
+    # @return [void]
+    def enable!
+      @disabled = false
+    end
+
+    # Check whether Faulty was disabled with {#disable!}
+    #
+    # @return [Boolean] True if disabled
+    def disabled?
+      @disabled == true
+    end
   end
 
   attr_reader :options
@@ -199,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
@@ -216,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.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Justin Howard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-10 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
@@ -124,6 +138,7 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
+- bin/benchmark
 - bin/check-version
 - bin/console
 - bin/rspec
@@ -143,9 +158,11 @@ 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
+- lib/faulty/events/filter_notifier.rb
 - lib/faulty/events/honeybadger_listener.rb
 - lib/faulty/events/listener_interface.rb
 - lib/faulty/events/log_listener.rb
@@ -164,6 +181,7 @@ files:
 - lib/faulty/storage/fault_tolerant_proxy.rb
 - lib/faulty/storage/interface.rb
 - lib/faulty/storage/memory.rb
+- lib/faulty/storage/null.rb
 - lib/faulty/storage/redis.rb
 - lib/faulty/version.rb
 homepage: https://github.com/ParentSquare/faulty