cuprum 0.9.1 → 0.11.0

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

data/lib/cuprum/matching/match_clause.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'cuprum/matching'
+
+module Cuprum::Matching
+  # @private
+  #
+  # Value object that represents a potential result match for a Matcher.
+  #
+  # Should not be instantiated directly; instead, instantiate a Cuprum::Matcher
+  # or include Cuprum::Matching in a custom class.
+  MatchClause = Struct.new(:block, :error, :status, :value) do
+    include Comparable
+
+    # @param other [Cuprum::Matching::MatchClause] The other result to compare.
+    #
+    # @return [Integer] the comparison result.
+    def <=>(other)
+      return nil unless other.is_a?(Cuprum::Matching::MatchClause)
+
+      cmp = compare(value, other.value)
+
+      return cmp unless cmp.zero?
+
+      compare(error, other.error)
+    end
+
+    # Checks if the match clause matches the specified error and value.
+    #
+    # @return [Boolean] true if the error and value match, otherwise false.
+    def matches_details?(error:, value:)
+      return false unless matches_detail?(error, self.error)
+      return false unless matches_detail?(value, self.value)
+
+      true
+    end
+
+    # Checks if the match clause matches the given result.
+    #
+    # @return [Boolean] true if the result matches, otherwise false.
+    def matches_result?(result:)
+      return false unless error.nil? || result.error.is_a?(error)
+      return false unless value.nil? || result.value.is_a?(value)
+
+      true
+    end
+
+    private
+
+    def compare(left, right)
+      return  0 if left.nil? && right.nil?
+      return  1 if left.nil?
+      return -1 if right.nil?
+
+      left <=> right || 0
+    end
+
+    def matches_detail?(actual, expected)
+      return true  if actual.nil? && expected.nil?
+      return false if actual.nil? || expected.nil?
+
+      actual <= expected
+    end
+  end
+end

data/lib/cuprum/middleware.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Implements a wrapper around another command.
+  #
+  # A middleware command wraps the execution of another command, allowing the
+  # developer to compose functionality without an explicit wrapper command.
+  # Because the middleware is responsible for calling the wrapped command, it
+  # has control over when that command is called, with what parameters, and how
+  # the command result is handled.
+  #
+  # To use middleware, start by defining a middleware command. This can either
+  # be a class that includes Cuprum::Middleware, or a command instance that
+  # extends Cuprum::Middleware. Each middleware command's #process method takes
+  # as its first argument the wrapped command. By convention, any additional
+  # arguments and any keywords or a block are passed to the wrapped command, but
+  # some middleware will override ths behavior.
+  #
+  # When defining #process, make sure to either call super or call the wrapped
+  # command directly, unless the middleware is specifically intended not to call
+  # the wrapped command under those circumstances.
+  #
+  # Middleware is powerful because it allows the developer to manipulate the
+  # parameters passed to a command, add handling to a result, or even intercept
+  # or override the command execution. These are some of the possible use cases
+  # for middleware:
+  #
+  # - Injecting code before or after a command.
+  # - Changing the parameters passed to a command.
+  # - Adding behavior based on the command result.
+  # - Overriding the command behavior based on the parameters.
+  #
+  # Middleware is loosely coupled, meaning that one middleware command can wrap
+  # any number of other commands. One example would be logging middleware, which
+  # could record when a command is called and with what parameters. For a more
+  # involved example, consider authorization in a web application. If individual
+  # actions are defined as commands, then a single authorization middleware
+  # class could wrap each individual action, reducing both the testing burden
+  # and the amount of code that must be maintained.
+  #
+  # @example Basic Middleware
+  #   class ExampleCommand < Cuprum::Command
+  #     private def process(**options)
+  #       return failure(options[:error]) if options[:error]
+  #
+  #       "Options: #{options.inspect}"
+  #     end
+  #   end
+  #
+  #   class LoggingMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware injects a logging step before the wrapped command is
+  #     # called. Notice that this middleware is generic, and can be used with
+  #     # virtually any other command.
+  #     private def process(next_command, *args, **kwargs)
+  #       Logger.info("Calling command #{next_command.class}")
+  #
+  #       super
+  #     end
+  #   end
+  #
+  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   middleware = LoggingMiddleware.new
+  #   result     = middleware.call(command, { id: 0 })
+  #   #=> logs "Calling command ExampleCommand"
+  #   result.value
+  #   #=> "Options: { id: 0 }"
+  #
+  # @example Injecting Parameters
+  #   class ApiMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware adds the :api_key to the parameters passed to the
+  #     # command. If an :api_key keyword is passed, then the passed value will
+  #     # take precedence.
+  #     private def process(next_command, *args, **kwargs)
+  #       super(next_command, *args, api_key: '12345', **kwargs)
+  #     end
+  #   end
+  #
+  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   middleware = LoggingMiddleware.new
+  #   result     = middleware.call(command, { id: 0 })
+  #   result.value
+  #   #=> "Options: { id: 0, api_key: '12345' }"
+  #
+  # @example Handling Results
+  #   class IgnoreFailure < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware runs the command once. On a failing result, the
+  #     # middleware discards the failing result and returns a result with a
+  #     # value of nil.
+  #     private def process(next_command, *args, **kwargs)
+  #       result = super
+  #
+  #       return result if result.success?
+  #
+  #       success(nil)
+  #     end
+  #   end
+  #
+  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   middleware = LoggingMiddleware.new
+  #   result     = middleware.call(command, { id: 0 })
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> "Options: { id: 0, api_key: '12345' }"
+  #
+  #   error      = Cuprum::Error.new(message: 'Something went wrong.')
+  #   result     = middleware.call(command, error: error)
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> nil
+  #
+  # @example Flow Control
+  #   class AuthenticationMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware finds the current user based on the given keywords. If
+  #     # a valid user is found, the user is then passed on to the command.
+  #     # If a user is not found, then the middleware will immediately halt (due
+  #     # to #step) and return the failing result from the authentication
+  #     # command.
+  #     private def process(next_command, *args, **kwargs)
+  #       current_user = step { AuthenticateUser.new.call(**kwargs) }
+  #
+  #       super(next_command, *args, current_user: current_user, **kwargs)
+  #     end
+  #   end
+  #
+  # @example Advanced Command Wrapping
+  #   class RetryMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware runs the command up to three times. If a result is
+  #     # passing, that result is returned immediately; otherwise, the last
+  #     # failing result will be returned by the middleware.
+  #     private def process(next_command, *args, **kwargs)
+  #       result = nil
+  #
+  #       3.times do
+  #         result = super
+  #
+  #         return result if result.success?
+  #       end
+  #
+  #       result
+  #     end
+  #   end
+  module Middleware
+    # @!method call(next_command, *arguments, **keywords, &block)
+    #   Calls the next command with the given arguments, keywords, and block.
+    #
+    #   Subclasses can call super to easily call the next command with the given
+    #   parameters, or pass explicit parameters into super to call the next
+    #   command with those parameters.
+    #
+    #   @param next_command [Cuprum::Command] The command to call.
+    #   @param arguments [Array] The arguments to pass to the command.
+    #   @param keywords [Hash] The keywords to pass to the command.
+    #
+    #   @yield A block to pass to the command.
+    #
+    #   @return [Cuprum::Result] the result of calling the command.
+
+    # Helper method for wrapping a command with middleware.
+    #
+    # This method takes the given command and middleware and returns a command
+    # that will call the middleware in order, followed by the given command.
+    # This is done via partial application: the last item in the middleware is
+    # partially applied with the given command as the middleware's next command
+    # parameter. The next to last middleware is then partially applied with the
+    # last middleware as the next command and so on. This ensures that the
+    # middleware commands will be called in the given order, and that each
+    # middleware command wraps the next, down to the given command at the root.
+    #
+    # @param command [Cuprum::Command] The command to wrap with middleware.
+    # @param middleware [Cuprum::Middleware, Array<Cuprum::Middleware>] The
+    #   middleware to wrap around the command. Will be called in the order they
+    #   are given.
+    #
+    # @return [Cuprum::Command] the outermost middleware command, with the next
+    #   command parameter partially applied.
+    def self.apply(command:, middleware:)
+      middleware = Array(middleware)
+
+      return command if middleware.empty?
+
+      middleware.reverse_each.reduce(command) do |next_command, cmd|
+        cmd.curry(next_command)
+      end
+    end
+
+    private
+
+    def process(next_command, *args, **kwargs, &block)
+      if kwargs.empty?
+        step { next_command.call(*args, &block) }
+      else
+        step { next_command.call(*args, **kwargs, &block) }
+      end
+    end
+  end
+end