cuprum 0.10.0 → 0.11.0.rc.0

data/lib/cuprum/errors/operation_not_called.rb

@@ -7,12 +7,12 @@ module Cuprum::Errors
   # Error class to be used when trying to access the result of an uncalled
   # Operation.
   class OperationNotCalled < Cuprum::Error
-    COMPARABLE_PROPERTIES = %i[operation].freeze
-    private_constant :COMPARABLE_PROPERTIES
-
     # Format for generating error message.
     MESSAGE_FORMAT = '%s was not called and does not have a result'
 
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.errors.operation_not_called'
+
     # @param operation [Cuprum::Operation] The uncalled operation.
     def initialize(operation:)
       @operation = operation
@@ -20,7 +20,7 @@ module Cuprum::Errors
       class_name = operation&.class&.name || 'operation'
       message    = MESSAGE_FORMAT % class_name
 
-      super(message: message)
+      super(message: message, operation: operation)
     end
 
     # @return [Cuprum::Operation] The uncalled operation.
@@ -28,8 +28,8 @@ module Cuprum::Errors
 
     private
 
-    def comparable_properties
-      COMPARABLE_PROPERTIES
+    def as_json_data
+      operation ? { 'class_name' => operation.class.name } : {}
     end
   end
 end

data/lib/cuprum/errors/uncaught_exception.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'cuprum/errors'
+
+module Cuprum::Errors
+  # An error returned when a command encounters an unhandled exception.
+  class UncaughtException < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.uncaught_exception'
+
+    # @param exception [StandardError] The exception that was raised.
+    # @param message [String] A message to display. Will be annotated with
+    #   details on the exception and the exception's cause (if any).
+    def initialize(exception:, message: 'uncaught exception')
+      @exception = exception
+      @cause     = exception.cause
+
+      super(message: generate_message(message))
+    end
+
+    # @return [StandardError] the exception that was raised.
+    attr_reader :exception
+
+    private
+
+    attr_reader :cause
+
+    def as_json_data # rubocop:disable Metrics/MethodLength
+      data = {
+        'exception_backtrace' => exception.backtrace,
+        'exception_class'     => exception.class,
+        'exception_message'   => exception.message
+      }
+
+      return data unless cause
+
+      data.update(
+        {
+          'cause_backtrace' => cause.backtrace,
+          'cause_class'     => cause.class,
+          'cause_message'   => cause.message
+        }
+      )
+    end
+
+    def generate_message(message)
+      message = "#{message} #{exception.class}: #{exception.message}"
+
+      return message unless cause
+
+      message + " caused by #{cause.class}: #{cause.message}"
+    end
+  end
+end

data/lib/cuprum/exception_handling.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'cuprum/errors/uncaught_exception'
+
+module Cuprum
+  # Utility class for handling uncaught exceptions in commands.
+  #
+  # @example
+  #   class UnsafeCommand < Cuprum::Command
+  #     private
+  #
+  #     def process
+  #       raise 'Something went wrong.'
+  #     end
+  #   end
+  #
+  #   class SafeCommand < UnsafeCommand
+  #     include Cuprum::ExceptionHandling
+  #   end
+  #
+  #   UnsafeCommand.new.call
+  #   #=> raises a StandardError
+  #
+  #   result = SafeCommand.new.call
+  #   #=> a Cuprum::Result
+  #   result.error
+  #   #=> a Cuprum::Errors::UncaughtException error.
+  #   result.error.message
+  #   #=> 'uncaught exception in SafeCommand -' \
+  #       ' StandardError: Something went wrong.'
+  module ExceptionHandling
+    # Wraps the #call method with a rescue clause matching any StandardError.
+    #
+    # If a StandardError or subclass thereof is raised and not caught by #call,
+    # then ExceptionHandling will rescue the exception and return a failing
+    # Cuprum::Result with a Cuprum::Errors::UncaughtException error.
+    #
+    # @return [Cuprum::Result] the result of calling the superclass method, or
+    #   a failing result if a StandardError is raised.
+    def call(*args, **kwargs, &block)
+      super
+    rescue StandardError => exception
+      error = Cuprum::Errors::UncaughtException.new(
+        exception: exception,
+        message:   "uncaught exception in #{self.class.name} - "
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/matcher.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+require 'cuprum/matching'
+
+module Cuprum
+  # Provides result matching based on result status, error, and value.
+  #
+  # First, define match clauses using the .match DSL. Each match clause has a
+  # status and optionally a value class and/or error class. A result will only
+  # match the clause if the result status is the same as the clause's status.
+  # If the clause sets a value class, then the result value must be an instance
+  # of that class (or an instance of a subclass). If the clause sets an error
+  # class, then the result error must be an instance of that class (or an
+  # instance of a subclass).
+  #
+  # Once the matcher defines one or more match clauses, call #call with a result
+  # to match the result. The matcher will determine the best match with the same
+  # status (value and error match the result, only value or error match, or just
+  # status matches) and then call the match clause with the result. If no match
+  # clauses match the result, the matcher will instead raise a
+  # Cuprum::Matching::NoMatchError.
+  #
+  # @example Matching A Status
+  #   matcher = Cuprum::Matcher.new do
+  #     match(:failure) { 'Something went wrong' }
+  #
+  #     match(:success) { 'Ok' }
+  #   end
+  #
+  #   matcher.call(Cuprum::Result.new(status: :failure))
+  #   #=> 'Something went wrong'
+  #
+  #   matcher.call(Cuprum::Result.new(status: :success))
+  #   #=> 'Ok'
+  #
+  # @example Matching An Error
+  #   matcher = Cuprum::Matcher.new do
+  #     match(:failure) { 'Something went wrong' }
+  #
+  #     match(:failure, error: CustomError) { |result| result.error.message }
+  #
+  #     match(:success) { 'Ok' }
+  #   end
+  #
+  #   matcher.call(Cuprum::Result.new(status: :failure))
+  #   #=> 'Something went wrong'
+  #
+  #   error = CustomError.new(message: 'The magic smoke is escaping.')
+  #   matcher.call(Cuprum::Result.new(error: error))
+  #   #=> 'The magic smoke is escaping.'
+  #
+  # @example Using A Match Context
+  #   context = Struct.new(:name).new('programs')
+  #   matcher = Cuprum::Matcher.new(context) do
+  #     match(:failure) { 'Something went wrong' }
+  #
+  #     match(:success) { "Greetings, #{name}!" }
+  #   end
+  #
+  #   matcher.call(Cuprum::Result.new(status: :success)
+  #   #=> 'Greetings, programs!'
+  class Matcher
+    include Cuprum::Matching
+
+    # @param match_context [Object] the execution context for a matching clause.
+    #
+    # @yield Executes the block in the context of the singleton class. This is
+    #   used to define match clauses when instantiating a Matcher instance.
+    def initialize(match_context = nil, &block)
+      @match_context = match_context
+
+      singleton_class.instance_exec(&block) if block_given?
+    end
+
+    # Returns a copy of the matcher with the given execution context.
+    #
+    # @param match_context [Object] the execution context for a matching clause.
+    #
+    # @return [Cuprum::Matcher] the copied matcher.
+    def with_context(match_context)
+      clone.tap { |copy| copy.match_context = match_context }
+    end
+    alias_method :using_context, :with_context
+
+    protected
+
+    attr_writer :match_context
+  end
+end

data/lib/cuprum/matcher_list.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Handles matching a result against an ordered list of matchers.
+  #
+  # A MatcherList should be used when you have a series of matchers with a
+  # defined priority ordering. Within that ordering, the list will check for the
+  # most specific matching clause in each of the matchers. A clause matching
+  # both the value and error will match first, followed by a clause matching
+  # only the result value or error, and finally a clause matching only the
+  # result status will match. If none of the matchers have a clause that matches
+  # the result, a Cuprum::Matching::NoMatchError will be raised.
+  #
+  # @example Using A MatcherList
+  #   generic_matcher = Cuprum::Matcher.new do
+  #     match(:failure) { 'generic failure' }
+  #
+  #     match(:failure, error: CustomError) { 'custom failure' }
+  #   end
+  #   specific_matcher = Cuprum::Matcher.new do
+  #     match(:failure, error: Cuprum::Error) { 'specific failure' }
+  #   end
+  #   matcher_list = Cuprum::MatcherList.new(
+  #     [
+  #       specific_matcher,
+  #       generic_matcher
+  #     ]
+  #   )
+  #
+  #   # A failure without an error does not match the first matcher, so the
+  #   # matcher list continues on to the next matcher in the list.
+  #   result = Cuprum::Result.new(status: :failure)
+  #   matcher_list.call(result)
+  #   #=> 'generic failure'
+  #
+  #   # A failure with an error matches the first matcher.
+  #   error  = Cuprum::Error.new(message: 'Something went wrong.')
+  #   result = Cuprum::Result.new(error: error)
+  #   matcher_list.call(result)
+  #   #=> 'specific failure'
+  #
+  #   # A failure with an error subclass still matches the first matcher, even
+  #   # though the second matcher has a more exact match.
+  #   error  = CustomError.new(message: 'The magic smoke is escaping.')
+  #   result = Cuprum::Result.new(error: error)
+  #   matcher_list.call(result)
+  #   #=> 'specific failure'
+  class MatcherList
+    # @param matchers [Array<Cuprum::Matching>] The matchers to match against a
+    #   result, in order of descending priority.
+    def initialize(matchers)
+      @matchers = matchers
+    end
+
+    # @return [Array<Cuprum::Matching>] the matchers to match against a result.
+    attr_reader :matchers
+
+    # Finds and executes the best matching clause from the ordered matchers.
+    #
+    # When given a result, the matcher list will check through each of the
+    # matchers in the order they were given for match clauses that match the
+    # result. Each matcher is checked for a clause that matches the status,
+    # error, and value of the result. If no matching clause is found, the
+    # matchers are then checked for a clause matching the status and either the
+    # error or value of the result. Finally, if there are still no matching
+    # clauses, the matchers are checked for a clause that matches the result
+    # status.
+    #
+    # Once a matching clause is found, that clause is then called with the
+    # given result.
+    #
+    # If none of the matchers have a clause that matches the result, a
+    # Cuprum::Matching::NoMatchError will be raised.
+    #
+    # @param result [Cuprum::Result] The result to match.
+    #
+    # @raise Cuprum::Matching::NoMatchError if none of the matchers match the
+    #   given result.
+    #
+    # @see Cuprum::Matcher#call.
+    def call(result)
+      unless result.respond_to?(:to_cuprum_result)
+        raise ArgumentError, 'result must be a Cuprum::Result'
+      end
+
+      result  = result.to_cuprum_result
+      matcher = matcher_for(result)
+
+      return matcher.call(result) if matcher
+
+      raise Cuprum::Matching::NoMatchError,
+        "no match found for #{result.inspect}"
+    end
+
+    private
+
+    def error_match?(matcher:, result:)
+      matcher.matches?(
+        result.status,
+        error: result.error&.class
+      )
+    end
+
+    def exact_match?(matcher:, result:)
+      matcher.matches?(
+        result.status,
+        error: result.error&.class,
+        value: result.value&.class
+      )
+    end
+
+    def find_exact_match(result)
+      matchers.find do |matcher|
+        exact_match?(matcher: matcher, result: result)
+      end
+    end
+
+    def find_generic_match(result)
+      matchers.find do |matcher|
+        generic_match?(matcher: matcher, result: result)
+      end
+    end
+
+    def find_partial_match(result)
+      matchers.find do |matcher|
+        error_match?(matcher: matcher, result: result) ||
+          value_match?(matcher: matcher, result: result)
+      end
+    end
+
+    def generic_match?(matcher:, result:)
+      matcher.matches?(result.status)
+    end
+
+    def matcher_for(result)
+      find_exact_match(result) ||
+        find_partial_match(result) ||
+        find_generic_match(result)
+    end
+
+    def value_match?(matcher:, result:)
+      matcher.matches?(
+        result.status,
+        value: result.value&.class
+      )
+    end
+  end
+end

data/lib/cuprum/matching.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Implements result matching based on result status, error, and value.
+  #
+  # @see Cuprum::Matcher.
+  module Matching
+    autoload :MatchClause, 'cuprum/matching/match_clause'
+
+    # Class methods extend-ed into a class when the module is included.
+    module ClassMethods
+      # Defines a match clause for the matcher.
+      #
+      # @param status [Symbol] The status to match. The clause will match a
+      #   result only if the result has the same status as the match clause.
+      # @param error [Class] The type of error to match. If given, the clause
+      #   will match a result only if the result error is an instance of the
+      #   given class, or an instance of a subclass.
+      # @param value [Class] The type of value to match. If given, the clause
+      #   will match a result only if the result value is an instance of the
+      #   given class, or an instance of a subclass.
+      #
+      # @yield The code to execute on a successful match.
+      # @yieldparam result [Cuprum::Result] The matched result.
+      def match(status, error: nil, value: nil, &block)
+        validate_status!(status)
+        validate_error!(error)
+        validate_value!(value)
+
+        clause  = MatchClause.new(block, error, status, value)
+        clauses = match_clauses[status]
+        index   = clauses.bsearch_index { |item| clause <= item } || -1
+
+        # Clauses are sorted from most specific to least specific.
+        clauses.insert(index, clause)
+      end
+
+      # @private
+      def match_result(result:)
+        status_clauses(result.status).find do |clause|
+          clause.matches_result?(result: result)
+        end
+      end
+
+      # @private
+      def matches_result?(result:)
+        status_clauses(result.status).reverse_each.any? do |clause|
+          clause.matches_result?(result: result)
+        end
+      end
+
+      # @private
+      def matches_status?(error:, status:, value:)
+        status_clauses(status).reverse_each.any? do |clause|
+          clause.matches_details?(error: error, value: value)
+        end
+      end
+
+      protected
+
+      def match_clauses
+        @match_clauses ||= Hash.new { |hsh, key| hsh[key] = [] }
+      end
+
+      private
+
+      def status_clauses(status)
+        ancestors
+          .select { |ancestor| ancestor < Cuprum::Matching }
+          .map { |ancestor| ancestor.match_clauses[status] }
+          .reduce([], &:concat)
+          .sort
+      end
+
+      def validate_error!(error)
+        return if error.nil? || error.is_a?(Module)
+
+        raise ArgumentError,
+          'error must be a Class or Module',
+          caller(1..-1)
+      end
+
+      def validate_status!(status)
+        if status.nil? || status.to_s.empty?
+          raise ArgumentError, "status can't be blank", caller(1..-1)
+        end
+
+        return if status.is_a?(Symbol)
+
+        raise ArgumentError, 'status must be a Symbol', caller(1..-1)
+      end
+
+      def validate_value!(value)
+        return if value.nil? || value.is_a?(Module)
+
+        raise ArgumentError,
+          'value must be a Class or Module',
+          caller(1..-1)
+      end
+    end
+
+    # Exception raised when the matcher does not match a result.
+    class NoMatchError < StandardError; end
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.extend(ClassMethods)
+      end
+    end
+
+    # @return [Object, nil] the execution context for a matching clause.
+    attr_reader :match_context
+
+    # Finds the match clause matching the result and calls the stored block.
+    #
+    # Match clauses are defined using the .match DSL. When a result is matched,
+    # the defined clauses matching the result status are checked in descending
+    # order of specificity:
+    #
+    # - Clauses that expect both a value and an error.
+    # - Clauses that expect a value.
+    # - Clauses that expect an error.
+    # - Clauses that do not expect a value or an error.
+    #
+    # If there are multiple clauses that expect a value or an error, they are
+    # sorted by inheritance - a clause with a subclass value or error is checked
+    # before the clause with the parent class.
+    #
+    # Using that ordering, each potential clause is checked for a match with the
+    # result. If the clause defines a value, then the result will match the
+    # clause only if the result value is an instance of the expected value (or
+    # an instance of a subclass). Likewise, if the clause defines an error, then
+    # the result will match the clause only if the result error is an instance
+    # of the expected error class (or an instance of a subclass). Clauses that
+    # do not define either a value nor an error will match with any result with
+    # the same status, but as the least specific are always matched last.
+    #
+    # Matchers can also inherit clauses from a parent class or from an included
+    # module. Inherited or included clauses are checked after clauses defined on
+    # the matcher itself, so the matcher can override generic matches with more
+    # specific functionality.
+    #
+    # Finally, once the most specific matching clause is found, #call will
+    # call the block used to define the clause. If the block takes at least one
+    # argument, the result will be passed to the block; otherwise, it will be
+    # called with no parameters. If there is no clause matching the result,
+    # #call will instead raise a Cuprum::Matching::NoMatchError.
+    #
+    # The match clause is executed in the context of the matcher object. This
+    # allows instance methods defined for the matcher to be called as part of
+    # the match clause block. If the matcher defines a non-nil
+    # #matching_context, the block is instead executed in the context of the
+    # matching_context using #instance_exec.
+    #
+    # @param result [Cuprum::Result] The result to match.
+    #
+    # @return [Object] the value returned by the stored block.
+    #
+    # @raise [NoMatchError] if there is no clause matching the result.
+    #
+    # @see ClassMethods::match
+    # @see #match_context
+    def call(result)
+      unless result.respond_to?(:to_cuprum_result)
+        raise ArgumentError, 'result must be a Cuprum::Result'
+      end
+
+      result = result.to_cuprum_result
+      clause = singleton_class.match_result(result: result)
+
+      raise NoMatchError, "no match found for #{result.inspect}" if clause.nil?
+
+      call_match(block: clause.block, result: result)
+    end
+
+    # @return [Boolean] true if an execution context is defined for a matching
+    #   clause; otherwise false.
+    def match_context?
+      !match_context.nil?
+    end
+
+    # @overload matches?(result)
+    #   Checks if the matcher has any match clauses that match the given result.
+    #
+    #   @param result [Cuprum::Result] The result to match.
+    #
+    #   @return [Boolean] true if the matcher has at least one match clause that
+    #     matches the result; otherwise false.
+    #
+    # @overload matches?(status, error: nil, value: nil)
+    #   Checks if the matcher has any clauses matching the status and details.
+    #
+    #   @param status [Symbol] The status to match.
+    #   @param error [Class, nil] The class of error to match, if any.
+    #   @param value [Class, nil] The class of value to match, if any.
+    #
+    #   @return [Boolean] true if the matcher has at least one match clause that
+    #     matches the status and details; otherwise false.
+    def matches?(result_or_status, error: nil, value: nil) # rubocop:disable Metrics/MethodLength
+      if result_or_status.respond_to?(:to_cuprum_result)
+        raise ArgumentError, 'error defined by result' unless error.nil?
+        raise ArgumentError, 'value defined by result' unless value.nil?
+
+        return singleton_class.matches_result?(
+          result: result_or_status.to_cuprum_result
+        )
+      elsif result_or_status.is_a?(Symbol)
+        return singleton_class.matches_status?(
+          error:  error,
+          status: result_or_status,
+          value:  value
+        )
+      end
+
+      raise ArgumentError, 'argument must be a result or a status'
+    end
+
+    private
+
+    def call_match(block:, result:)
+      args = block.arity.zero? ? [] : [result]
+
+      (match_context || self).instance_exec(*args, &block)
+    end
+  end
+end