faulty 0.1.0

data/lib/faulty/error.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Faulty
+  # The base error for all Faulty errors
+  class FaultyError < StandardError; end
+
+  # Raised if using the global Faulty object without initializing it
+  class UninitializedError < FaultyError
+    def initialize(message = nil)
+      message ||= 'Faulty is not initialized'
+      super(message)
+    end
+  end
+
+  # Raised if {Faulty.init} is called multiple times
+  class AlreadyInitializedError < FaultyError
+    def initialize(message = nil)
+      message ||= 'Faulty is already initialized'
+      super(message)
+    end
+  end
+
+  # Raised if getting the default scope without initializing one
+  class MissingDefaultScopeError < FaultyError
+    def initialize(message = nil)
+      message ||= 'No default scope. Create one with init or get your scope with Faulty[:scope_name]'
+      super(message)
+    end
+  end
+
+  # The base error for all errors raised during circuit runs
+  #
+  class CircuitError < FaultyError
+    attr_reader :circuit
+
+    def initialize(message, circuit)
+      message ||= %(circuit error for "#{circuit.name}")
+      @circuit = circuit
+
+      super(message)
+    end
+  end
+
+  # Raised when running a circuit that is already open
+  class OpenCircuitError < CircuitError; end
+
+  # Raised when an error occurred while running a circuit
+  #
+  # The `cause` will always be set and will be the internal error
+  #
+  # @see CircuitTrippedError For when the circuit is tripped
+  class CircuitFailureError < CircuitError; end
+
+  # Raised when an error occurred causing a circuit to close
+  #
+  # The `cause` will always be set and will be the internal error
+  class CircuitTrippedError < CircuitError; end
+
+  # Raised if calling get or error on a result without checking it
+  class UncheckedResultError < FaultyError; end
+
+  # Raised if getting the wrong result type.
+  #
+  # For example, calling get on an error result will raise this
+  class WrongResultError < FaultyError; end
+end

data/lib/faulty/events.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Faulty
+  # The namespace for Faulty events and event listeners
+  module Events
+    # All possible events that can be raised by Faulty
+    EVENTS = %i[
+      cache_failure
+      circuit_cache_hit
+      circuit_cache_miss
+      circuit_cache_write
+      circuit_closed
+      circuit_failure
+      circuit_opened
+      circuit_reopened
+      circuit_skipped
+      circuit_success
+      storage_failure
+    ].freeze
+  end
+end
+
+require 'faulty/events/callback_listener'
+require 'faulty/events/notifier'
+require 'faulty/events/log_listener'

data/lib/faulty/events/callback_listener.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Faulty
+  module Events
+    # A simple listener implementation that uses callback blocks as handlers
+    #
+    # Each event in {EVENTS} has a method on this class that can be used
+    # to register a callback for that event.
+    #
+    # @example
+    #   listener = CallbackListener.new
+    #   listener.circuit_opened do |payload|
+    #     logger.error(
+    #       "Circuit #{payload[:circuit].name} opened: #{payload[:error].message}"
+    #     )
+    #   end
+    class CallbackListener
+      def initialize
+        @handlers = {}
+        yield self if block_given?
+      end
+
+      # @param (see ListenerInterface#handle)
+      # @return [void]
+      def handle(event, payload)
+        return unless EVENTS.include?(event)
+        return unless @handlers.key?(event)
+
+        @handlers[event].each do |handler|
+          handler.call(payload)
+        end
+      end
+
+      EVENTS.each do |event|
+        define_method(event) do |&block|
+          @handlers[event] ||= []
+          @handlers[event] << block
+        end
+      end
+    end
+  end
+end

data/lib/faulty/events/listener_interface.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Faulty
+  module Events
+    # The interface required to implement a event listener
+    #
+    # This is for documentation only and is not loaded
+    class ListenerInterface
+      # Handle an event raised by Faulty
+      #
+      # @param event [Symbol] The event name. Will be a member of {EVENTS}.
+      # @param payload [Hash] A hash with keys based on the event type
+      # @return [void]
+      def handle(event, payload)
+      end
+    end
+  end
+end

data/lib/faulty/events/log_listener.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Faulty
+  module Events
+    # A default listener that logs Faulty events
+    class LogListener
+      attr_reader :logger
+
+      # @param logger A logger similar to stdlib `Logger`. Uses the Rails logger
+      #   by default if available, otherwise it creates a new `Logger` to
+      #   stderr.
+      def initialize(logger = nil)
+        logger ||= defined?(Rails) ? Rails.logger : ::Logger.new($stderr)
+        @logger = logger
+      end
+
+      # (see ListenerInterface#handle)
+      def handle(event, payload)
+        return unless EVENTS.include?(event)
+
+        send(event, payload) if respond_to?(event, true)
+      end
+
+      private
+
+      def circuit_cache_hit(payload)
+        log(:debug, 'Circuit cache hit', payload[:circuit].name, key: payload[:key])
+      end
+
+      def circuit_cache_miss(payload)
+        log(:debug, 'Circuit cache miss', payload[:circuit].name, key: payload[:key])
+      end
+
+      def circuit_cache_write(payload)
+        log(:debug, 'Circuit cache write', payload[:circuit].name, key: payload[:key])
+      end
+
+      def circuit_success(payload)
+        log(:debug, 'Circuit succeeded', payload[:circuit].name, state: payload[:status].state)
+      end
+
+      def circuit_failure(payload)
+        log(
+          :error, 'Circuit failed', payload[:circuit].name,
+          state: payload[:status].state,
+          error: payload[:error].message
+        )
+      end
+
+      def circuit_skipped(payload)
+        log(:warn, 'Circuit skipped', payload[:circuit].name)
+      end
+
+      def circuit_opened(payload)
+        log(:error, 'Circuit opened', payload[:circuit].name, error: payload[:error].message)
+      end
+
+      def circuit_reopened(payload)
+        log(:error, 'Circuit reopened', payload[:circuit].name, error: payload[:error].message)
+      end
+
+      def circuit_closed(payload)
+        log(:info, 'Circuit closed', payload[:circuit].name)
+      end
+
+      def cache_failure(payload)
+        log(
+          :error, 'Cache failure', payload[:action],
+          key: payload[:key],
+          error: payload[:error].message
+        )
+      end
+
+      def storage_failure(payload)
+        log(
+          :error, 'Storage failure', payload[:action],
+          circuit: payload[:circuit]&.name,
+          error: payload[:error].message
+        )
+      end
+
+      def log(level, msg, action, extra = {})
+        extra_str = extra.map { |k, v| "#{k}=#{v}" }.join(' ')
+        logger.public_send(level, "#{msg}: #{action} #{extra_str}")
+      end
+    end
+  end
+end

data/lib/faulty/events/notifier.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Faulty
+  module Events
+    # The default event dispatcher for Faulty
+    class Notifier
+      # @param listeners [Array<ListenerInterface>] An array of event listeners
+      def initialize(listeners = [])
+        @listeners = listeners.freeze
+      end
+
+      # Notify all listeners of an event
+      #
+      # @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
+      #   single event
+      def notify(event, payload)
+        raise ArgumentError, "Unknown event #{event}" unless EVENTS.include?(event)
+
+        @listeners.each { |l| l.handle(event, payload) }
+      end
+    end
+  end
+end

data/lib/faulty/immutable_options.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Faulty
+  # A struct that cannot be modified after initialization
+  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 }
+      yield self if block_given?
+      finalize
+      required.each do |key|
+        raise ArgumentError, "Missing required attribute #{key}" if self[key].nil?
+      end
+      freeze
+    end
+
+    private
+
+    # A hash of default values to set before yielding to the block
+    #
+    # @return [Hash<Symbol, Object>]
+    def defaults
+      {}
+    end
+
+    # An array of required attributes
+    #
+    # @return [Array<Symbol>]
+    def required
+      []
+    end
+
+    # Runs before freezing to finalize attribute initialization
+    #
+    # @return [void]
+    def finalize
+    end
+  end
+end

data/lib/faulty/result.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Faulty
+  # An approximation of the `Result` type from some strongly-typed languages.
+  #
+  # F#: https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/results
+  #
+  # Rust: https://doc.rust-lang.org/std/result/enum.Result.html
+  #
+  # Since we can't enforce the type at compile-time, we use runtime errors to
+  # check the result for consistency as early as possible. This means we
+  # enforce runtime checks of the result type. This approach does not eliminate
+  # issues, but it does help remind the user to check the result in most cases.
+  #
+  # This is returned from {Circuit#try_run} to allow error handling without
+  # needing to rescue from errors.
+  #
+  # @example
+  #   result = Result.new(ok: 'foo')
+  #
+  #   # Check the result before calling get
+  #   if result.ok?
+  #     puts result.get
+  #   else
+  #     puts result.error.message
+  #   end
+  #
+  # @example
+  #   result = Result.new(error: StandardError.new)
+  #   puts result.or_default('fallback') # prints "fallback"
+  #
+  # @example
+  #   result = Result.new(ok: 'foo')
+  #   result.get # raises UncheckedResultError
+  #
+  # @example
+  #   result = Result.new(ok: 'foo')
+  #   if result.ok?
+  #     result.error.message # raises WrongResultError
+  #   end
+  class Result
+    # The constant used to designate that a value is empty
+    #
+    # This is needed to differentiate between an ok `nil` value and
+    # an empty value.
+    #
+    # @private
+    NOTHING = {}.freeze
+
+    # Create a new `Result` with either an ok or error value
+    #
+    # Exactly one parameter must be given, and not both.
+    #
+    # @param ok An ok value
+    # @param error [Error] An error instance
+    def initialize(ok: NOTHING, error: NOTHING) # rubocop:disable Naming/MethodParameterName
+      if ok.equal?(NOTHING) && error.equal?(NOTHING)
+        raise ArgumentError, 'Result must have an ok or error value'
+      end
+      if !ok.equal?(NOTHING) && !error.equal?(NOTHING)
+        raise ArgumentError, 'Result must not have both an ok and error value'
+      end
+
+      @ok = ok
+      @error = error
+      @checked = false
+    end
+
+    # Check if the value is an ok value
+    #
+    # @return [Boolean] True if this result is ok
+    def ok?
+      @checked = true
+      ok_unchecked?
+    end
+
+    # Check if the value is an error value
+    #
+    # @return [Boolean] True if this result is an error
+    def error?
+      !ok?
+    end
+
+    # Get the ok value
+    #
+    # @raise UncheckedResultError if this result was not checked using {#ok?} or {#error?}
+    # @raise WrongResultError if this result is an error
+    # @return The ok value
+    def get
+      validate_checked!('get')
+      unsafe_get
+    end
+
+    # Get the ok value without checking whether it's safe to do so
+    #
+    # @raise WrongResultError if this result is an error
+    # @return The ok value
+    def unsafe_get
+      raise WrongResultError, 'Tried to get value for error result' unless ok_unchecked?
+
+      @ok
+    end
+
+    # Get the error value
+    #
+    # @raise UncheckedResultError if this result was not checked using {#ok?} or {#error?}
+    # @raise WrongResultError if this result is ok
+    def error
+      validate_checked!('error')
+      unsafe_error
+    end
+
+    # Get the error value without checking whether it's safe to do so
+    #
+    # @raise WrongResultError if this result is ok
+    # @return [Error] The error
+    def unsafe_error
+      raise WrongResultError, 'Tried to get error for ok result' if ok_unchecked?
+
+      @error
+    end
+
+    # Get the ok value if this result is ok, otherwise return a default
+    #
+    # @param default The default value. Ignored if a block is given
+    # @yield A block returning the default value
+    # @return The ok value or the default if this result is an error
+    def or_default(default = nil)
+      if ok_unchecked?
+        @ok
+      elsif block_given?
+        yield @error
+      else
+        default
+      end
+    end
+
+    private
+
+    def ok_unchecked?
+      !@ok.equal?(NOTHING)
+    end
+
+    def validate_checked!(method)
+      unless @checked
+        raise UncheckedResultError, "Result: Called #{method} without checking ok? or error?"
+      end
+    end
+  end
+end