faulty 0.1.2 → 0.4.0

data/lib/faulty/cache/default.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # The default cache implementation
     #
@@ -11,6 +11,8 @@ module Faulty
     # - If ActiveSupport is available, it will use an `ActiveSupport::Cache::MemoryStore`
     # - Otherwise it will use a {Faulty::Cache::Null}
     class Default
+      extend Forwardable
+
       def initialize
         @cache = if defined?(::Rails)
           Cache::Rails.new(::Rails.cache)
@@ -21,28 +23,15 @@ module Faulty
         end
       end
 
-      # Read from the internal cache by key
+      # @!method read(key)
+      #   (see Faulty::Cache::Interface#read)
       #
-      # @param (see Cache::Interface#read)
-      # @return (see Cache::Interface#read)
-      def read(key)
-        @cache.read(key)
-      end
-
-      # Write to the internal cache
+      # @!method write(key, value, expires_in: expires_in)
+      #   (see Faulty::Cache::Interface#write)
       #
-      # @param (see Cache::Interface#read)
-      # @return (see Cache::Interface#read)
-      def write(key, value, expires_in: nil)
-        @cache.write(key, value, expires_in: expires_in)
-      end
-
-      # This cache is fault tolerant if the internal one is
-      #
-      # @return [Boolean]
-      def fault_tolerant?
-        @cache.fault_tolerant?
-      end
+      # @!method fault_tolerant
+      #   (see Faulty::Cache::Interface#fault_tolerant?)
+      def_delegators :@cache, :read, :write, :fault_tolerant?
     end
   end
 end

data/lib/faulty/cache/fault_tolerant_proxy.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A wrapper for cache backends that may raise errors
     #
-    # {Scope} automatically wraps all non-fault-tolerant cache backends with
+    # {Faulty#initialize} automatically wraps all non-fault-tolerant cache backends with
     # this class.
     #
     # If the cache backend raises a `StandardError`, it will be captured and
-    # sent to the notifier.
+    # sent to the notifier. Reads errors will return `nil`, and writes will be
+    # a no-op.
     class FaultTolerantProxy
       attr_reader :options
 
@@ -36,6 +37,16 @@ module Faulty
         @options = Options.new(options, &block)
       end
 
+      # Wrap a cache in a FaultTolerantProxy unless it's already fault tolerant
+      #
+      # @param cache [Cache::Interface] The cache to maybe wrap
+      # @return [Cache::Interface] The original cache or a {FaultTolerantProxy}
+      def self.wrap(cache, **options, &block)
+        return cache if cache.fault_tolerant?
+
+        new(cache, **options, &block)
+      end
+
       # Read from the cache safely
       #
       # If the backend raises a `StandardError`, this will return `nil`.
@@ -58,7 +69,7 @@ module Faulty
       # @return [void]
       def write(key, value, expires_in: nil)
         @cache.write(key, value, expires_in: expires_in)
-      rescue StandardError
+      rescue StandardError => e
         options.notifier.notify(:cache_failure, key: key, action: :write, error: e)
         nil
       end

data/lib/faulty/cache/interface.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # The interface required for a cache backend implementation
     #

data/lib/faulty/cache/mock.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A mock cache for testing
     #

data/lib/faulty/cache/null.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A cache backend that does nothing
     #

data/lib/faulty/cache/rails.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A wrapper for a Rails or ActiveSupport cache
     #
     class Rails
+      extend Forwardable
+
       # @param cache The Rails cache to wrap
       # @param fault_tolerant [Boolean] Whether the Rails cache is
       #   fault_tolerant. See {#fault_tolerant?} for more details
@@ -13,15 +15,12 @@ module Faulty
         @fault_tolerant = fault_tolerant
       end
 
-      # (see Interface#read)
-      def read(key)
-        @cache.read(key)
-      end
-
-      # (see Interface#read)
-      def write(key, value, expires_in: nil)
-        @cache.write(key, value, expires_in: expires_in)
-      end
+      # @!method read(key)
+      #   (see Faulty::Cache::Interface#read)
+      #
+      # @!method write(key, value, expires_in: expires_in)
+      #   (see Faulty::Cache::Interface#write)
+      def_delegators :@cache, :read, :write
 
       # Although ActiveSupport cache implementations are fault-tolerant,
       # Rails.cache is not guranteed to be fault tolerant. For this reason,

data/lib/faulty/circuit.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # Runs code protected by a circuit breaker
   #
   # https://www.martinfowler.com/bliki/CircuitBreaker.html
@@ -66,14 +66,19 @@ module Faulty
     #   @return [Error, Array<Error>] An array of errors that are considered circuit
     #     failures. Default `[StandardError]`.
     # @!attribute [r] exclude
-    #   @return [Error, Array<Error>] An array of errors that will be captured and
-    #     considered circuit failures. Default `[]`.
+    #   @return [Error, Array<Error>] An array of errors that will not be
+    #     captured by Faulty. These errors will not be considered circuit
+    #     failures. Default `[]`.
     # @!attribute [r] cache
-    #   @return [Cache::Interface] The cache backend. Default `Cache::Null.new`
+    #   @return [Cache::Interface] The cache backend. Default
+    #   `Cache::Null.new`. Unlike {Faulty#initialize}, this is not wrapped in
+    #   {Cache::AutoWire} by default.
     # @!attribute [r] notifier
     #   @return [Events::Notifier] A Faulty notifier. Default `Events::Notifier.new`
     # @!attribute [r] storage
-    #   @return [Storage::Interface] The storage backend. Default `Storage::Memory.new`
+    #   @return [Storage::Interface] The storage backend. Default
+    #   `Storage::Memory.new`. Unlike {Faulty#initialize}, this is not wrapped
+    #    in {Storage::AutoWire} by default.
     Options = Struct.new(
       :cache_expires_in,
       :cache_refreshes_after,

data/lib/faulty/error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The base error for all Faulty errors
   class FaultyError < StandardError; end
 
@@ -20,10 +20,10 @@ module Faulty
     end
   end
 
-  # Raised if getting the default scope without initializing one
-  class MissingDefaultScopeError < FaultyError
+  # Raised if getting the default instance without initializing one
+  class MissingDefaultInstanceError < FaultyError
     def initialize(message = nil)
-      message ||= 'No default scope. Create one with init or get your scope with Faulty[:scope_name]'
+      message ||= 'No default instance. Create one with init or get your instance with Faulty[:name]'
       super(message)
     end
   end
@@ -59,8 +59,22 @@ module Faulty
   # Raised if calling get or error on a result without checking it
   class UncheckedResultError < FaultyError; end
 
+  # An error that wraps multiple other errors
+  class FaultyMultiError < FaultyError
+    def initialize(message, errors)
+      message = "#{message}: #{errors.map(&:message).join(', ')}"
+      super(message)
+    end
+  end
+
   # Raised if getting the wrong result type.
   #
   # For example, calling get on an error result will raise this
   class WrongResultError < FaultyError; end
+
+  # Raised if a FallbackChain partially fails
+  class PartialFailureError < FaultyMultiError; end
+
+  # Raised if all FallbackChain backends fail
+  class AllFailedError < FaultyMultiError; end
 end

data/lib/faulty/events.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The namespace for Faulty events and event listeners
   module Events
     # All possible events that can be raised by Faulty
@@ -21,5 +21,6 @@ module Faulty
 end
 
 require 'faulty/events/callback_listener'
-require 'faulty/events/notifier'
+require 'faulty/events/honeybadger_listener'
 require 'faulty/events/log_listener'
+require 'faulty/events/notifier'

data/lib/faulty/events/callback_listener.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # A simple listener implementation that uses callback blocks as handlers
     #

data/lib/faulty/events/honeybadger_listener.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Events
+    # Reports circuit errors to Honeybadger
+    #
+    # https://www.honeybadger.io/
+    #
+    # The honeybadger gem must be available.
+    class HoneybadgerListener
+      # (see ListenerInterface#handle)
+      def handle(event, payload)
+        return unless EVENTS.include?(event)
+
+        send(event, payload) if respond_to?(event, true)
+      end
+
+      private
+
+      def circuit_failure(payload)
+        _circuit_error(payload)
+      end
+
+      def circuit_opened(payload)
+        _circuit_error(payload)
+      end
+
+      def circuit_reopened(payload)
+        _circuit_error(payload)
+      end
+
+      def cache_failure(payload)
+        Honeybadger.notify(payload[:error], context: {
+          action: payload[:action],
+          key: payload[:key]
+        })
+      end
+
+      def storage_failure(payload)
+        Honeybadger.notify(payload[:error], context: {
+          action: payload[:action],
+          circuit: payload[:circuit]&.name
+        })
+      end
+
+      def _circuit_error(payload)
+        Honeybadger.notify(payload[:error], context: {
+          circuit: payload[:circuit].name
+        })
+      end
+    end
+  end
+end

data/lib/faulty/events/listener_interface.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # The interface required to implement a event listener
     #

data/lib/faulty/events/log_listener.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # A default listener that logs Faulty events
     class LogListener
@@ -72,11 +72,10 @@ module Faulty
       end
 
       def storage_failure(payload)
-        log(
-          :error, 'Storage failure', payload[:action],
-          circuit: payload[:circuit]&.name,
-          error: payload[:error].message
-        )
+        extra = {}
+        extra[:circuit] = payload[:circuit].name if payload.key?(:circuit)
+        extra[:error] = payload[:error].message
+        log(:error, 'Storage failure', payload[:action], extra)
       end
 
       def log(level, msg, action, extra = {})

data/lib/faulty/events/notifier.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Events
     # The default event dispatcher for Faulty
     class Notifier
@@ -11,6 +11,9 @@ module Faulty
 
       # 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 event [Symbol] The event name
       # @param payload [Hash] A hash of event payload data. The payload keys
       #   differ between events, but should be consistent across calls for a
@@ -18,7 +21,13 @@ module Faulty
       def notify(event, payload)
         raise ArgumentError, "Unknown event #{event}" unless EVENTS.include?(event)
 
-        @listeners.each { |l| l.handle(event, payload) }
+        @listeners.each do |listener|
+          begin
+            listener.handle(event, payload)
+          rescue StandardError => e
+            warn "Faulty listener #{listener.class.name} crashed: #{e.message}"
+          end
+        end
       end
     end
   end

data/lib/faulty/immutable_options.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # A struct that cannot be modified after initialization
   module ImmutableOptions
     # @param hash [Hash] A hash of attributes to initialize with

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'