faulty 0.1.1 → 0.3.0

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/bin/console

@@ -3,7 +3,7 @@
 
 require 'bundler/setup'
 require 'faulty'
-require 'byebug'
+require 'byebug' if Gem.loaded_specs['byebug']
 require 'irb'
 
 # For default cache support

data/faulty.gemspec

@@ -23,21 +23,14 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'concurrent-ruby', '~> 1.0'
 
-  spec.add_development_dependency 'activesupport', '>= 4.2'
-  spec.add_development_dependency 'bundler', '>= 1.17', '< 3'
-  spec.add_development_dependency 'byebug', '~> 11.0'
+  # 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 'irb', '~> 1.0'
-  spec.add_development_dependency 'redcarpet', '~> 3.5'
+  spec.add_development_dependency 'honeybadger', '>= 2.0'
   spec.add_development_dependency 'redis', '~> 3.0'
   spec.add_development_dependency 'rspec', '~> 3.8'
-  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.4'
   # 0.81 is the last rubocop version with Ruby 2.3 support
   spec.add_development_dependency 'rubocop', '0.81.0'
   spec.add_development_dependency 'rubocop-rspec', '1.38.1'
-  # For now, code climate doesn't support simplecov 0.18
-  # https://github.com/codeclimate/test-reporter/issues/413
-  spec.add_development_dependency 'simplecov', '>= 0.17.1', '< 0.18'
   spec.add_development_dependency 'timecop', '>= 0.9'
-  spec.add_development_dependency 'yard', '~> 0.9.25'
 end

data/lib/faulty.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'forwardable'
 require 'concurrent-ruby'
 
 require 'faulty/immutable_options'
@@ -9,14 +10,16 @@ require 'faulty/circuit'
 require 'faulty/error'
 require 'faulty/events'
 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 +30,79 @@ 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]
     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
+    # @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)
+      raise UninitializedError unless @instances
 
-      @scopes.put_if_absent(name, scope)
+      @instances.put_if_absent(name, 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 +119,106 @@ 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] 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,
+    :storage,
+    :listeners,
+    :notifier
+  ) do
+    include ImmutableOptions
+
+    private
+
+    def finalize
+      self.notifier ||= Events::Notifier.new(listeners || [])
+      self.storage = Storage::AutoWire.new(storage, notifier: notifier)
+      self.cache = Cache::AutoWire.new(cache, notifier: notifier)
+    end
+
+    def required
+      %i[cache storage notifier]
+    end
+
+    def 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
+    options = options.merge(circuit_options)
+    @circuits.compute_if_absent(name) do
+      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) }
+  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,65 @@
+# frozen_string_literal: true
+
+class Faulty
+  module Cache
+    # Automatically configure a cache backend
+    #
+    # Used by {Faulty#initialize} to setup sensible cache defaults
+    class AutoWire
+      extend Forwardable
+
+      # Options for {AutoWire}
+      Options = Struct.new(
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def required
+          %i[notifier]
+        end
+      end
+
+      # 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 initialize(cache, **options, &block)
+        @options = Options.new(options, &block)
+        @cache = if cache.nil?
+          Cache::Default.new
+        elsif cache.fault_tolerant?
+          cache
+        else
+          Cache::FaultTolerantProxy.new(
+            Cache::CircuitProxy.new(cache, notifier: @options.notifier),
+            notifier: @options.notifier
+          )
+        end
+
+        freeze
+      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
+
+      # Auto-wired caches are always fault tolerant
+      #
+      # @return [true]
+      def fault_tolerant?
+        true
+      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