faulty 0.1.0

data/lib/faulty/scope.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Faulty
+  # A {Scope} is a group of options and circuits
+  #
+  # For most use-cases the default scope should be used, however, it's possible
+  # to create any number of scopes for applications that require a more complex
+  # configuration or for testing.
+  #
+  # For the most part, scopes 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 scopes. For example, if using the Redis storage
+  # backend, you should specify different key prefixes for each scope.
+  class Scope
+    attr_reader :options
+
+    # Options for {Scope}
+    #
+    # @!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 Scope
+    #
+    # Note, the process of creating a new scope is not thread safe,
+    # so make sure scopes are setup before spawning threads.
+    #
+    # @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 a scope, 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 scope options
+    #
+    # @return [Hash] The circuit options
+    def circuit_options
+      options = @options.to_h
+      options.delete(:listeners)
+      options
+    end
+  end
+end

data/lib/faulty/status.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Faulty
+  # The status of a circuit
+  #
+  # Includes information like the state and locks. Also calculates
+  # whether a circuit can be run, or if it has failed a threshold.
+  #
+  # @!attribute [r] state
+  #   @return [:open, :closed] The stored circuit state. This is always open
+  #     or closed. Half-open is calculated from the current time. For that
+  #     reason, calling state directly should be avoided. Instead use the
+  #     status methods {#open?}, {#closed?}, and {#half_open?}.
+  #     Default `:closed`
+  # @!attribute [r] lock
+  #   @return [:open, :closed, nil] If the circuit is locked, the state that
+  #     it is locked in. Default `nil`.
+  # @!attribute [r] opened_at
+  #   @return [Integer, nil] If the circuit is open, the timestamp that it was
+  #     opened. This is not necessarily reset when the circuit is closed.
+  #     Default `nil`.
+  # @!attribute [r] failure_rate
+  #   @return [Float] A number from 0 to 1 representing the percentage of
+  #     failures for the circuit. For exmaple 0.5 represents a 50% failure rate.
+  # @!attribute [r] sample_size
+  #   @return [Integer] The number of samples used to calculate the failure rate.
+  # @!attribute [r] options
+  #   @return [Circuit::Options] The options for the circuit
+  # @!attribute [r] stub
+  #   @return [Boolean] True if this status is a stub and not calculated from
+  #     the storage backend. Used by {Storage::FaultTolerantProxy} when
+  #     returning the status for an offline storage backend. Default `false`.
+  Status = Struct.new(
+    :state,
+    :lock,
+    :opened_at,
+    :failure_rate,
+    :sample_size,
+    :options,
+    :stub
+  ) do
+    include ImmutableOptions
+
+    # The allowed state values
+    STATES = %i[
+      open
+      closed
+    ].freeze
+
+    # The allowed lock values
+    LOCKS = %i[
+      open
+      closed
+    ].freeze
+
+    # Create a new `Status` from a list of circuit runs
+    #
+    # For storage backends that store entries, this automatically calculates
+    # failure_rate and sample size.
+    #
+    # @param entries [Array<Array>] An array of entry tuples. See
+    #   {Circuit#history} for details
+    # @param hash [Hash] The status attributes minus failure_rate and
+    #   sample_size
+    # @return [Status]
+    def self.from_entries(entries, **hash)
+      failures = 0
+      sample_size = 0
+      entries.each do |(time, success)|
+        next unless time > Faulty.current_time - hash[:options].evaluation_window
+
+        sample_size += 1
+        failures += 1 unless success
+      end
+
+      new(hash.merge(
+        sample_size: sample_size,
+        failure_rate: sample_size.zero? ? 0.0 : failures.to_f / sample_size
+      ))
+    end
+
+    # Whether the circuit is open
+    #
+    # This is mutually exclusive with {#closed?} and {#half_open?}
+    #
+    # @return [Boolean] True if open
+    def open?
+      state == :open && opened_at + options.cool_down > Faulty.current_time
+    end
+
+    # Whether the circuit is closed
+    #
+    # This is mutually exclusive with {#open?} and {#half_open?}
+    #
+    # @return [Boolean] True if closed
+    def closed?
+      state == :closed
+    end
+
+    # Whether the circuit is half-open
+    #
+    # This is mutually exclusive with {#open?} and {#closed?}
+    #
+    # @return [Boolean] True if half-open
+    def half_open?
+      state == :open && opened_at + options.cool_down <= Faulty.current_time
+    end
+
+    # Whether the circuit is locked open
+    #
+    # @return [Boolean] True if locked open
+    def locked_open?
+      lock == :open
+    end
+
+    # Whether the circuit is locked closed
+    #
+    # @return [Boolean] True if locked closed
+    def locked_closed?
+      lock == :closed
+    end
+
+    # Whether the circuit can be run
+    #
+    # Takes the circuit state, locks and cooldown into account
+    #
+    # @return [Boolean] True if the circuit can be run
+    def can_run?
+      return false if locked_open?
+
+      closed? || locked_closed? || half_open?
+    end
+
+    # Whether the circuit fails the sample size and rate thresholds
+    #
+    # @return [Boolean] True if the circuit fails the thresholds
+    def fails_threshold?
+      return false if sample_size < options.sample_threshold
+
+      failure_rate >= options.rate_threshold
+    end
+
+    private
+
+    def finalize
+      raise ArgumentError, "state must be a symbol in #{self.class}::STATES" unless STATES.include?(state)
+      unless lock.nil? || LOCKS.include?(state)
+        raise ArgumentError, "lock must be a symbol in #{self.class}::LOCKS or nil"
+      end
+    end
+
+    def required
+      %i[state failure_rate sample_size options stub]
+    end
+
+    def defaults
+      {
+        state: :closed,
+        failure_rate: 0.0,
+        sample_size: 0,
+        stub: false
+      }
+    end
+  end
+end

data/lib/faulty/storage.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Faulty
+  # The namespace for Faulty storage
+  module Storage
+  end
+end
+
+require 'faulty/storage/fault_tolerant_proxy'
+require 'faulty/storage/memory'
+require 'faulty/storage/redis'

data/lib/faulty/storage/fault_tolerant_proxy.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Faulty
+  module Storage
+    # A wrapper for storage backends that may raise errors
+    #
+    # {Scope} automatically wraps all non-fault-tolerant storage backends with
+    # this class.
+    #
+    # If the storage backend raises a `StandardError`, it will be captured and
+    # sent to the notifier.
+    class FaultTolerantProxy
+      attr_reader :options
+
+      # Options for {FaultTolerantProxy}
+      #
+      # @!attribute [r] notifier
+      #   @return [Events::Notifier] A Faulty notifier
+      Options = Struct.new(
+        :notifier
+      ) do
+        include ImmutableOptions
+
+        private
+
+        def required
+          %i[notifier]
+        end
+      end
+
+      # @param storage [Storage::Interface] The storage backend to wrap
+      # @param options [Hash] Attributes for {Options}
+      # @yield [Options] For setting options in a block
+      def initialize(storage, **options, &block)
+        @storage = storage
+        @options = Options.new(options, &block)
+      end
+
+      # Add a history entry safely
+      #
+      # @see Interface#entry
+      # @param (see Interface#entry)
+      # @return (see Interface#entry)
+      def entry(circuit, time, success)
+        @storage.entry(circuit, time, success)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :entry, error: e)
+        stub_status(circuit)
+      end
+
+      # Safely mark a circuit as open
+      #
+      # @see Interface#open
+      # @param (see Interface#open)
+      # @return (see Interface#open)
+      def open(circuit)
+        @storage.open(circuit)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :open, error: e)
+        false
+      end
+
+      # Safely mark a circuit as reopened
+      #
+      # @see Interface#reopen
+      # @param (see Interface#reopen)
+      # @return (see Interface#reopen)
+      def reopen(circuit)
+        @storage.reopen(circuit)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :reopen, error: e)
+        false
+      end
+
+      # Safely mark a circuit as closed
+      #
+      # @see Interface#close
+      # @param (see Interface#close)
+      # @return (see Interface#close)
+      def close(circuit)
+        @storage.close(circuit)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :close, error: e)
+        false
+      end
+
+      # Since lock is not called in normal operation, it does not capture
+      # errors
+      #
+      # @see Interface#lock
+      # @param (see Interface#lock)
+      # @return (see Interface#lock)
+      def lock(circuit, state)
+        @storage.lock(circuit, state)
+      end
+
+      # Since unlock is not called in normal operation, it does not capture
+      # errors
+      #
+      # @see Interface#unlock
+      # @param (see Interface#unlock)
+      # @return (see Interface#unlock)
+      def unlock(circuit)
+        @storage.unlock(circuit)
+      end
+
+      # Since reset is not called in normal operation, it does not capture
+      # errors
+      #
+      # @see Interface#reset
+      # @param (see Interface#reset)
+      # @return (see Interface#reset)
+      def reset(circuit)
+        @storage.reset(circuit)
+      end
+
+      # Safely get the status of a circuit
+      #
+      # If the backend is unavailable, this returns a stub status that
+      # indicates that the circuit is closed.
+      #
+      # @see Interface#status
+      # @param (see Interface#status)
+      # @return (see Interface#status)
+      def status(circuit)
+        @storage.status(circuit)
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, circuit: circuit, action: :status, error: e)
+        stub_status(circuit)
+      end
+
+      # Since history is not called in normal operation, it does not capture
+      # errors
+      #
+      # @see Interface#history
+      # @param (see Interface#history)
+      # @return (see Interface#history)
+      def history(circuit)
+        @storage.history(circuit)
+      end
+
+      # Safely get the list of circuit names
+      #
+      # If the backend is unavailable, this returns an empty array
+      #
+      # @see Interface#list
+      # @param (see Interface#list)
+      # @return (see Interface#list)
+      def list
+        @storage.list
+      rescue StandardError => e
+        options.notifier.notify(:storage_failure, action: :list, error: e)
+        []
+      end
+
+      # This cache makes any storage fault tolerant, so this is always `true`
+      #
+      # @return [true]
+      def fault_tolerant?
+        true
+      end
+
+      private
+
+      # Create a stub status object to close the circuit by default
+      #
+      # @return [Status] The stub status
+      def stub_status(circuit)
+        Faulty::Status.new(
+          cool_down: circuit.options.cool_down,
+          stub: true,
+          sample_threshold: circuit.options.sample_threshold,
+          rate_threshold: circuit.options.rate_threshold
+        )
+      end
+    end
+  end
+end