faulty 0.1.0 → 0.2.0

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

@@ -9,14 +9,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 +29,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 +118,113 @@ module Faulty
       Time.now.to_i
     end
   end
+
+  attr_reader :options
+
+  # Options for {Faulty}
+  #
+  # @!attribute [r] cache
+  #   @return [Cache::Interface] A cache backend if you want
+  #     to use Faulty's cache support. Automatically wrapped in a
+  #     {Cache::FaultTolerantProxy}. Default `Cache::Default.new`.
+  # @!attribute [r] storage
+  #   @return [Storage::Interface] The storage backend.
+  #     Automatically wrapped in a {Storage::FaultTolerantProxy}.
+  #     Default `Storage::Memory.new`.
+  # @!attribute [r] listeners
+  #   @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::Memory.new
+      unless storage.fault_tolerant?
+        self.storage = Storage::FaultTolerantProxy.new(storage, notifier: notifier)
+      end
+
+      self.cache ||= Cache::Default.new
+      unless cache.fault_tolerant?
+        self.cache = Cache::FaultTolerantProxy.new(cache, notifier: notifier)
+      end
+    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 = @options.to_h
+    options.delete(:listeners)
+    options
+  end
 end

data/lib/faulty/cache.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   # The namespace for Faulty caching
   module Cache
   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
     #

data/lib/faulty/cache/fault_tolerant_proxy.rb

@@ -1,10 +1,10 @@
 # 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

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,6 +1,6 @@
 # frozen_string_literal: true
 
-module Faulty
+class Faulty
   module Cache
     # A wrapper for a Rails or ActiveSupport cache
     #

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

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

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