faulty 0.1.4 → 0.5.1

data/bin/check-version

@@ -3,8 +3,12 @@
 set -e
 
 tag="$(git describe --abbrev=0 2>/dev/null || echo)"
+echo "Tag: ${tag}"
 tag="${tag#v}"
+echo "Git Version: ${tag}"
 [ "$tag" = '' ] && exit 0
+gem_version="$(ruby -r ./lib/faulty/version -e "puts Faulty.version" | tail -n1)"
+echo "Gem Version: ${gem_version}"
 
-tag_gt_version=$(ruby -r ./lib/faulty/version -e "puts Faulty.version >= Gem::Version.new('${tag}')")
+tag_gt_version="$(ruby -r ./lib/faulty/version -e "puts Faulty.version >= Gem::Version.new('${tag}')" | tail -n1)"
 test "$tag_gt_version" = true

data/faulty.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   # Other non-essential development dependencies go in the Gemfile.
   spec.add_development_dependency 'connection_pool', '~> 2.0'
   spec.add_development_dependency 'honeybadger', '>= 2.0'
-  spec.add_development_dependency 'redis', '~> 3.0'
+  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
   spec.add_development_dependency 'rubocop', '0.81.0'

data/lib/faulty.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'forwardable'
 require 'concurrent-ruby'
 
 require 'faulty/immutable_options'
@@ -8,15 +9,18 @@ require 'faulty/cache'
 require 'faulty/circuit'
 require 'faulty/error'
 require 'faulty/events'
+require 'faulty/patch'
 require 'faulty/result'
-require 'faulty/scope'
 require 'faulty/status'
 require 'faulty/storage'
 
-# The top-level namespace for Faulty
+# The {Faulty} class has class-level methods for global state or can be
+# instantiated to create an independent configuration.
 #
-# Fault-tolerance tools for ruby based on circuit-breakers
-module Faulty
+# If you are using global state, call {Faulty#init} during your application's
+# initialization. This is the simplest way to use {Faulty}. If you prefer, you
+# can also call {Faulty.new} to create independent {Faulty} instances.
+class Faulty
   class << self
     # Start the Faulty environment
     #
@@ -27,78 +31,88 @@ module Faulty
     # are spawned.
     #
     # If you prefer dependency-injection instead of global state, you can skip
-    # init and pass a {Scope} directly to your dependencies.
+    # `init` and use {Faulty.new} to pass an instance directoy to your
+    # dependencies.
     #
-    # @param scope_name [Symbol] The name of the default scope. Can be set to
-    #   `nil` to skip creating a default scope.
-    # @param config [Hash] Attributes for {Scope::Options}
-    # @yield [Scope::Options] For setting options in a block
+    # @param default_name [Symbol] The name of the default instance. Can be set
+    # to `nil` to skip creating a default instance.
+    # @param config [Hash] Attributes for {Faulty::Options}
+    # @yield [Faulty::Options] For setting options in a block
     # @return [self]
-    def init(scope_name = :default, **config, &block)
-      raise AlreadyInitializedError if @scopes
+    def init(default_name = :default, **config, &block)
+      raise AlreadyInitializedError if @instances
 
-      @default_scope = scope_name
-      @scopes = Concurrent::Map.new
-      register(scope_name, Scope.new(**config, &block)) unless scope_name.nil?
+      @default_instance = default_name
+      @instances = Concurrent::Map.new
+      register(default_name, new(**config, &block)) unless default_name.nil?
       self
     rescue StandardError
-      @scopes = nil
+      @instances = nil
       raise
     end
 
-    # Get the default scope given during {.init}
+    # Get the default instance given during {.init}
     #
-    # @return [Scope, nil] The default scope if it is registered
+    # @return [Faulty, nil] The default instance if it is registered
     def default
-      raise UninitializedError unless @scopes
-      raise MissingDefaultScopeError unless @default_scope
+      raise UninitializedError unless @instances
+      raise MissingDefaultInstanceError unless @default_instance
 
-      self[@default_scope]
+      self[@default_instance]
     end
 
-    # Get a scope by name
+    # Get an instance by name
     #
-    # @return [Scope, nil] The named scope if it is registered
-    def [](scope_name)
-      raise UninitializedError unless @scopes
+    # @return [Faulty, nil] The named instance if it is registered
+    def [](name)
+      raise UninitializedError unless @instances
 
-      @scopes[scope_name]
+      @instances[name.to_s]
     end
 
-    # Register a scope to the global Faulty state
+    # Register an instance to the global Faulty state
     #
-    # Will not replace an existing scope with the same name. Check the
-    # return value if you need to know whether the scope already existed.
+    # Will not replace an existing instance with the same name. Check the
+    # return value if you need to know whether the instance already existed.
     #
-    # @param name [Symbol] The name of the scope to register
-    # @param scope [Scope] The scope to register
-    # @return [Scope, nil] The previously-registered scope of that name if
+    # @param name [Symbol] The name of the instance to register
+    # @param instance [Faulty] The instance to register. If nil, a new instance
+    #   will be created from the given options or block.
+    # @param config [Hash] Attributes for {Faulty::Options}
+    # @yield [Faulty::Options] For setting options in a block
+    # @return [Faulty, nil] The previously-registered instance of that name if
     #   it already existed, otherwise nil.
-    def register(name, scope)
-      raise UninitializedError unless @scopes
+    def register(name, instance = nil, **config, &block)
+      raise UninitializedError unless @instances
 
-      @scopes.put_if_absent(name, scope)
+      if instance
+        raise ArgumentError, 'Do not give config options if an instance is given' if !config.empty? || block
+      else
+        instance = new(**config, &block)
+      end
+
+      @instances.put_if_absent(name.to_s, instance)
     end
 
-    # Get the options for the default scope
+    # Get the options for the default instance
     #
-    # @raise MissingDefaultScopeError If the default scope has not been created
-    # @return [Scope::Options]
+    # @raise MissingDefaultInstanceError If the default instance has not been created
+    # @return [Faulty::Options]
     def options
       default.options
     end
 
-    # Get or create a circuit for the default scope
+    # Get or create a circuit for the default instance
     #
-    # @raise UninitializedError If the default scope has not been created
-    # @param (see Scope#circuit)
-    # @yield (see Scope#circuit)
-    # @return (see Scope#circuit)
+    # @raise UninitializedError If the default instance has not been created
+    # @param (see Faulty#circuit)
+    # @yield (see Faulty#circuit)
+    # @return (see Faulty#circuit)
     def circuit(name, **config, &block)
       default.circuit(name, **config, &block)
     end
 
-    # Get a list of all circuit names for the default scope
+    # Get a list of all circuit names for the default instance
     #
     # @return [Array<String>] The circuit names
     def list_circuits
@@ -115,4 +129,114 @@ module Faulty
       Time.now.to_i
     end
   end
+
+  attr_reader :options
+
+  # Options for {Faulty}
+  #
+  # @!attribute [r] cache
+  #   @see Cache::AutoWire
+  #   @return [Cache::Interface] A cache backend if you want
+  #     to use Faulty's cache support. Automatically wrapped in a
+  #     {Cache::AutoWire}. Default `Cache::AutoWire.new`.
+  # @!attribute [r] circuit_defaults
+  #   @see Circuit::Options
+  #   @return [Hash] A hash of default options to be used when creating
+  #     new circuits. See {Circuit::Options} for a full list.
+  # @!attribute [r] storage
+  #   @see Storage::AutoWire
+  #   @return [Storage::Interface, Array<Storage::Interface>] The storage
+  #   backend. Automatically wrapped in a {Storage::AutoWire}, so this can also
+  #   be given an array of prioritized backends. Default `Storage::AutoWire.new`.
+  # @!attribute [r] listeners
+  #   @see Events::ListenerInterface
+  #   @return [Array] listeners Faulty event listeners
+  # @!attribute [r] notifier
+  #   @return [Events::Notifier] A Faulty notifier. If given, listeners are
+  #     ignored.
+  Options = Struct.new(
+    :cache,
+    :circuit_defaults,
+    :storage,
+    :listeners,
+    :notifier
+  ) do
+    include ImmutableOptions
+
+    private
+
+    def finalize
+      self.notifier ||= Events::Notifier.new(listeners || [])
+      self.storage = Storage::AutoWire.wrap(storage, notifier: notifier)
+      self.cache = Cache::AutoWire.wrap(cache, notifier: notifier)
+    end
+
+    def required
+      %i[cache circuit_defaults storage notifier]
+    end
+
+    def defaults
+      {
+        circuit_defaults: {},
+        listeners: [Events::LogListener.new]
+      }
+    end
+  end
+
+  # Create a new {Faulty} instance
+  #
+  # Note, the process of creating a new instance is not thread safe,
+  # so make sure instances are setup during your application's initialization
+  # phase.
+  #
+  # For the most part, {Faulty} instances are independent, however for some
+  # cache and storage backends, you will need to ensure that the cache keys
+  # and circuit names don't overlap between instances. For example, if using the
+  # {Storage::Redis} storage backend, you should specify different key
+  # prefixes for each instance.
+  #
+  # @see Options
+  # @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)
+  end
+
+  # Create or retrieve a circuit
+  #
+  # Within an instance, circuit instances have unique names, so if the given circuit
+  # name already exists, then the existing circuit will be returned, otherwise
+  # a new circuit will be created. If an existing circuit is returned, then
+  # the {options} param and block are ignored.
+  #
+  # @param name [String] The name of the circuit
+  # @param options [Hash] Attributes for {Circuit::Options}
+  # @yield [Circuit::Options] For setting options in a block
+  # @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
+  end
+
+  # Get a list of all circuit names
+  #
+  # @return [Array<String>] The circuit names
+  def list_circuits
+    options.storage.list
+  end
+
+  private
+
+  # Get circuit options from the {Faulty} options
+  #
+  # @return [Hash] The circuit options
+  def circuit_options
+    @options.to_h
+      .select { |k, _v| %i[cache storage notifier].include?(k) }
+      .merge(options.circuit_defaults)
+  end
 end

data/lib/faulty/cache.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The namespace for Faulty caching
   module Cache
   end
 end
 
+require 'faulty/cache/auto_wire'
 require 'faulty/cache/default'
+require 'faulty/cache/circuit_proxy'
 require 'faulty/cache/fault_tolerant_proxy'
 require 'faulty/cache/mock'
 require 'faulty/cache/null'

data/lib/faulty/cache/auto_wire.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Cache
+    # Automatically configure a cache backend
+    #
+    # Used by {Faulty#initialize} to setup sensible cache defaults
+    class AutoWire
+      # Options for {AutoWire}
+      #
+      # @!attribute [r] circuit
+      #   @return [Circuit] A circuit for {CircuitProxy} if one is created.
+      #     When modifying this, be careful to use only a reliable circuit
+      #     storage backend so that you don't introduce cascading failures.
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier. If given, listeners are
+      #     ignored.
+      Options = Struct.new(
+        :circuit,
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def required
+          %i[notifier]
+        end
+      end
+
+      class << self
+        # Wrap a cache backend with sensible defaults
+        #
+        # If the cache is `nil`, create a new {Default}.
+        #
+        # If the backend is not fault tolerant, wrap it in {CircuitProxy} and
+        # {FaultTolerantProxy}.
+        #
+        # @param cache [Interface] A cache backend
+        # @param options [Hash] Attributes for {Options}
+        # @yield [Options] For setting options in a block
+        def wrap(cache, **options, &block)
+          options = Options.new(options, &block)
+          if cache.nil?
+            Cache::Default.new
+          elsif cache.fault_tolerant?
+            cache
+          else
+            Cache::FaultTolerantProxy.new(
+              Cache::CircuitProxy.new(cache, circuit: options.circuit, notifier: options.notifier),
+              notifier: options.notifier
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faulty/cache/circuit_proxy.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Cache
+    # A circuit wrapper for cache backends
+    #
+    # This class uses an internal {Circuit} to prevent the cache backend from
+    # causing application issues. If the backend fails continuously, this
+    # circuit will trip to prevent cascading failures. This internal circuit
+    # uses an independent in-memory backend by default.
+    class CircuitProxy
+      attr_reader :options
+
+      # Options for {CircuitProxy}
+      #
+      # @!attribute [r] circuit
+      #   @return [Circuit] A replacement for the internal circuit. When
+      #     modifying this, be careful to use only a reliable circuit storage
+      #     backend so that you don't introduce cascading failures.
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier to use for failure
+      #     notifications. If `circuit` is given, this is ignored.
+      Options = Struct.new(
+        :circuit,
+        :notifier
+      ) 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,
+            cache: Cache::Null.new
+          )
+        end
+      end
+
+      # @param cache [Cache::Interface] The cache backend to wrap
+      # @param options [Hash] Attributes for {Options}
+      # @yield [Options] For setting options in a block
+      def initialize(cache, **options, &block)
+        @cache = cache
+        @options = Options.new(options, &block)
+      end
+
+      %i[read write].each do |method|
+        define_method(method) do |*args|
+          options.circuit.run { @cache.public_send(method, *args) }
+        end
+      end
+
+      def fault_tolerant?
+        @cache.fault_tolerant?
+      end
+    end
+  end
+end

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