hearth 1.0.0.pre1

data/lib/hearth/http.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require_relative 'http/api_error'
+require_relative 'http/client'
+require_relative 'http/error_parser'
+require_relative 'http/headers'
+require_relative 'http/middleware/content_length'
+require_relative 'http/networking_error'
+require_relative 'http/request'
+require_relative 'http/response'
+
+module Hearth
+  # HTTP namespace for HTTP specific functionality. Also includes utility
+  # methods for URI escaping.
+  # @api private
+  module HTTP
+    # TODO: - do these belong here?
+    class << self
+      # URI escapes the given value.
+      #
+      #   Hearth::_escape("a b/c")
+      #   #=> "a%20b%2Fc"
+      #
+      # @param [String] value
+      # @return [String] URI encoded value except for '+' and '~'.
+      def uri_escape(value)
+        CGI.escape(value.encode('UTF-8')).gsub('+', '%20').gsub('%7E', '~')
+      end
+
+      def uri_escape_path(path)
+        path.gsub(%r{[^/]+}) { |part| uri_escape(part) }
+      end
+    end
+  end
+end

data/lib/hearth/json/parse_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hearth
+  module JSON
+    # An error class encountered when parsing JSON.
+    class ParseError < StandardError
+      MSG = 'Encountered an error while parsing the response: %<message>s'
+
+      def initialize(original_error)
+        @original_error = original_error
+        super(format(MSG, message: original_error.message))
+      end
+
+      # @return [StandardError]
+      attr_reader :original_error
+    end
+  end
+end

data/lib/hearth/json.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'json/parse_error'
+require 'json'
+
+module Hearth
+  # Hearth::JSON is a purpose-built set of utilities for working with
+  # JSON. It does not support many/most features of generic JSON
+  # parsing and serialization.
+  # @api private
+  module JSON
+    class << self
+      # @param [String] json
+      # @return [Hash]
+      def load(json)
+        # rubocop:disable Security/JSONLoad
+        ::JSON.load(json)
+        # rubocop:enable Security/JSONLoad
+      rescue ::JSON::ParserError => e
+        raise ParseError, e
+      end
+
+      # @param [Hash] value
+      # @return [String] json
+      def dump(value)
+        ::JSON.dump(value)
+      end
+    end
+  end
+end

data/lib/hearth/middleware/around_handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A class used to register middleware around a request.
+    # @api private
+    class AroundHandler
+      # @param [Class] app The next middleware in the stack.
+      # @param [Proc] handler A proc object that is called around the request.
+      #   The proc must return the next middleware.
+      def initialize(app, handler:)
+        @app = app
+        @handler = handler
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        @handler.call(@app, input, context)
+      end
+    end
+  end
+end

data/lib/hearth/middleware/build.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that builds a request object.
+    # @api private
+    class Build
+      # @param [Class] app The next middleware in the stack.
+      # @param [Class] builder A builder object responsible for building the
+      #  request. It must respond to #build and take the request and input as
+      #  arguments.
+      def initialize(app, builder:)
+        @app = app
+        @builder = builder
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        @builder.build(context.request, input: input)
+        @app.call(input, context)
+      end
+    end
+  end
+end

data/lib/hearth/middleware/host_prefix.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that prefixes the host.
+    # @api private
+    class HostPrefix
+      # @param [Class] app The next middleware in the stack.
+      # @param [Boolean] disable_host_prefix If true, this option will not
+      #  modify the host url.
+      # @param [String] host_prefix The prefix for the host. It may contain
+      #  labels populated by input (i.e. \\{foo.} would be populated by
+      #  input[:foo]).
+      def initialize(app, disable_host_prefix:, host_prefix:)
+        @app = app
+        @disable_host_prefix = disable_host_prefix
+        @host_prefix = host_prefix
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        unless @disable_host_prefix
+          prefix = apply_labels(@host_prefix, input)
+          context.request.prefix_host(prefix)
+        end
+        @app.call(input, context)
+      end
+
+      private
+
+      def apply_labels(host_prefix, input)
+        host_prefix.gsub(/\{.+?\}/) do |host_label|
+          key = host_label.delete('{}')
+          value = input[key.to_sym]
+
+          if value.nil? || value.empty?
+            raise ArgumentError,
+                  "Host label #{key} cannot be nil or empty."
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/hearth/middleware/parse.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that parses a response object.
+    # @api private
+    class Parse
+      # @param [Class] app The next middleware in the stack.
+      # @param [Class] error_parser A parser object responsible for parsing the
+      #  response if there is an error. It must respond to #parse and take the
+      #  response as an argument.
+      # @param [Class] data_parser A parser object responsible for parsing the
+      #  response if there is data. It must respond to #parse and take the
+      #  response as an argument.
+      def initialize(app, error_parser:, data_parser:)
+        @app = app
+        @error_parser = error_parser
+        @data_parser = data_parser
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        output = @app.call(input, context)
+        parse_error(context.response, output) unless output.error
+        parse_data(context.response, output) unless output.error
+        output
+      end
+
+      private
+
+      def parse_error(response, output)
+        output.error = @error_parser.parse(response)
+      end
+
+      def parse_data(response, output)
+        output.data = @data_parser.parse(response)
+      end
+    end
+  end
+end

data/lib/hearth/middleware/request_handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A class used to register middleware before a request is sent.
+    # @api private
+    class RequestHandler
+      # @param [Class] app The next middleware in the stack.
+      # @param [Proc] handler A proc object that is called before the request.
+      def initialize(app, handler:)
+        @app = app
+        @handler = handler
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        @handler.call(input, context)
+        @app.call(input, context)
+      end
+    end
+  end
+end

data/lib/hearth/middleware/response_handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A class used to register middleware after a request is sent.
+    # @api private
+    class ResponseHandler
+      # @param [Class] app The next middleware in the stack.
+      # @param [Proc] handler A proc object that is called after the request.
+      def initialize(app, handler:)
+        @app = app
+        @handler = handler
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        output = @app.call(input, context)
+        @handler.call(output, context)
+        output
+      end
+    end
+  end
+end

data/lib/hearth/middleware/retry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that retries the request.
+    # @api private
+    class Retry
+      # @param [Class] app The next middleware in the stack.
+      # @param [Integer] max_attempts The maximum number of attempts to make
+      #  before giving up.
+      # @param [Integer] max_delay The maximum delay between attempts.
+      def initialize(app, max_attempts:, max_delay:)
+        @app = app
+        @max_attempts = max_attempts
+        @max_delay = max_delay
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        attempt = 1
+        begin
+          @app.call(input, context)
+        rescue Hearth::HTTP::NetworkingError => e
+          raise e if attempt >= @max_attempts
+
+          Kernel.sleep(backoff_with_jitter(attempt))
+          attempt += 1
+          retry
+        end
+      end
+
+      private
+
+      # https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+      def backoff_with_jitter(attempt)
+        # scales like 1,2,4,8
+        Kernel.rand * [@max_delay, 2**(attempt - 1)].min
+      end
+    end
+  end
+end

data/lib/hearth/middleware/send.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware used to send the request.
+    # @api private
+    class Send
+      # @param [Class] _app The next middleware in the stack.
+      # @param [Boolean] stub_responses If true, a request is not sent and a
+      #   stubbed response is returned.
+      # @param [Class] stub_class A stub object that is responsible for creating
+      #   a stubbed response. It must respond to #stub and take the response
+      #   and stub data as arguments.
+      # @param [Stubs] stubs A {Hearth::Stubbing:Stubs} object containing
+      #   stubbed data for any given operation.
+      def initialize(_app, client:, stub_responses:, stub_class:, stubs:)
+        @client = client
+        @stub_responses = stub_responses
+        @stub_class = stub_class
+        @stubs = stubs
+      end
+
+      # @param _input
+      # @param context
+      # @return [Output]
+      def call(_input, context)
+        if @stub_responses
+          stub = @stubs.next(context.operation_name)
+          output = Output.new
+          apply_stub(stub, context, output)
+          output
+        else
+          @client.transmit(
+            request: context.request,
+            response: context.response
+          )
+          Output.new
+        end
+      end
+
+      private
+
+      def apply_stub(stub, context, output)
+        case stub
+        when Proc
+          stub = stub.call(context)
+          apply_stub(stub, context, output) if stub
+        when Exception
+          output.error = stub
+        when Class
+          output.error = stub.new
+        when Hash
+          @stub_class.stub(context.response, stub: stub)
+        when NilClass
+          @stub_class.stub(context.response, stub: @stub_class.default)
+        else
+          raise ArgumentError, 'Unsupported stub type'
+        end
+      end
+    end
+  end
+end

data/lib/hearth/middleware/validate.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware used to validate input.
+    # @api private
+    class Validate
+      # @param [Class] app The next middleware in the stack.
+      # @param [Boolean] validate_input If true, the input is validated against
+      #   the model and an error is raised for unexpected types.
+      # @param [Class] validator A validator object responsible for validating
+      #  the input. It must respond to #validate! and take input and a context
+      #  as arguments.
+      def initialize(app, validate_input:, validator:)
+        @app = app
+        @validate_input = validate_input
+        @validator = validator
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        @validator.validate!(input, context: 'input') if @validate_input
+        @app.call(input, context)
+      end
+    end
+  end
+end

data/lib/hearth/middleware.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'middleware/around_handler'
+require_relative 'middleware/build'
+require_relative 'middleware/host_prefix'
+require_relative 'middleware/parse'
+require_relative 'middleware/request_handler'
+require_relative 'middleware/response_handler'
+require_relative 'middleware/retry'
+require_relative 'middleware/send'
+require_relative 'middleware/validate'
+
+module Hearth
+  # @api private
+  module Middleware; end
+end

data/lib/hearth/middleware_builder.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A utility class for registering middleware for a request.
+  # You register middleware handlers to execute relative to
+  # Middleware classes.  You can register middleware
+  # before/after/around any middleware class in the stack.
+  # You may also remove middleware from the stack.
+  # There are also convenience methods
+  # (eg: before_build, after_parse, ect)
+  # defined for all of the key request lifecycle events:
+  #
+  # * validate
+  # * host_prefix
+  # * build
+  # * send
+  # * parse
+  # * retry
+  #
+  # You can register request handlers that invoke before, after,
+  # or around each lifecycle events. These handlers are
+  # request, response, or around handlers.
+  #
+  # All before/after/around methods are defined on the class
+  # and instance and are chainable:
+  #
+  #    MiddlewareBuilder.before_send(my_request_handler)
+  #       .after_parse(my_response_handler)
+  #
+  # ## Request Handlers
+  #
+  # A request handler is invoked before the request is sent.
+  #
+  #    # invoked after a request has been built, but before it has
+  #    # been signed/authorized
+  #    middleware.before_build do |input, context|
+  #      # use input, inspect or modify the request
+  #      # context.request
+  #    end
+  #
+  # ## Response Handlers
+  #
+  # A response handler is invoked after the HTTP request has been sent
+  # and a HTTP response has been received.
+  #
+  #    # invoked after the HTTP response has been parsed
+  #    middleware.after_parse do |output, context|
+  #      # inspect or modify the output or context
+  #      # output.data
+  #      # output.error
+  #      # context.response
+  #    end
+  #
+  # ## Around Handlers
+  #
+  # Around handlers see a request before it has been sent along
+  # with the response returned. Around handlers must invoke `#call`
+  # method of the next middleware in the stack. Around handlers
+  # must also return the response returned from the next middleware.
+  #
+  #     # invoke before the request  has been sent, receives the
+  #     # response from the send middleware
+  #     middleware.around_send do |app, input, context|
+  #
+  #       # this code is invoked before the request is sent
+  #       # ...
+  #
+  #       # around handlers MUST call the next middleware in the stack
+  #       output = app.call(input, context)
+  #
+  #       # this code is invoked after the response has been received
+  #       # ...
+  #
+  #       # around handlers must return the response down the stack
+  #       output
+  #     end
+  #
+  # ## Removing Middleware
+  # You may remove existing middleware from the stack using either the class
+  # or instance `remove` methods and providing the middleware class to
+  # be removed.  The remove methods are chainable and convenience methods are
+  # defined for the same set of lifecycle events as the `before`, `after`
+  # and `around` methods:
+  #
+  #   # create a middleware builder that removes send and build middlewares
+  #   MiddlewareBuilder
+  #     .remove_send
+  #     .remove_build
+  #
+  class MiddlewareBuilder
+    # @private
+    BOTH = 'expected a handler or a Proc, got both'
+
+    # @private
+    NEITHER = 'expected a handler or a Proc, got neither'
+
+    # @private
+    TOO_MANY = 'wrong number of arguments (given %<count>d, expected 0 or 1)'
+
+    # @private
+    CALLABLE = 'expected handler to respond to #call'
+
+    # @param [Proc, MiddlewareBuilder] middleware
+    #
+    #   If `middleware` is another {MiddlewareBuilder} instance, then
+    #   the middleware handlers are copied.
+    #
+    def initialize(middleware = nil)
+      @middleware = []
+      case middleware
+      when MiddlewareBuilder then @middleware.concat(middleware.to_a)
+      when nil then nil
+      else
+        raise ArgumentError, 'expected :middleware to be a' \
+                             'Hearth::MiddlewareBuilder,' \
+                             " got #{middleware.class}"
+      end
+    end
+
+    # @param [MiddlewareStack] middleware_stack
+    def apply(middleware_stack)
+      @middleware.each do |handler|
+        method, relation, middleware, kwargs = handler
+        if method == :remove
+          middleware_stack.remove(relation)
+        else
+          middleware_stack.send(method, relation, middleware, **kwargs)
+        end
+      end
+    end
+
+    def before(klass, *args, &block)
+      @middleware << [
+        :use_before,
+        klass,
+        Middleware::RequestHandler,
+        { handler: handler_or_proc!(args, &block) }
+      ]
+      self
+    end
+
+    def after(klass, *args, &block)
+      @middleware << [
+        :use_before,
+        klass,
+        Middleware::ResponseHandler,
+        { handler: handler_or_proc!(args, &block) }
+      ]
+      self
+    end
+
+    def around(klass, *args, &block)
+      @middleware << [
+        :use_before,
+        klass,
+        Middleware::AroundHandler,
+        { handler: handler_or_proc!(args, &block) }
+      ]
+      self
+    end
+
+    def remove(klass)
+      @middleware << [
+        :remove,
+        klass,
+        nil,
+        nil
+      ]
+      self
+    end
+
+    # Define convenience methods for chaining
+    class << self
+      def before(klass, *args, &block)
+        MiddlewareBuilder.new.before(klass, *args, &block)
+      end
+
+      def after(klass, *args, &block)
+        MiddlewareBuilder.new.after(klass, *args, &block)
+      end
+
+      def around(klass, *args, &block)
+        MiddlewareBuilder.new.around(klass, *args, &block)
+      end
+
+      def remove(klass)
+        MiddlewareBuilder.new.remove(klass)
+      end
+    end
+
+    # define convenience methods for standard middleware classes
+    # these define methods and class methods for before,after,around
+    # eg: before_build, after_build, around_build.
+    STANDARD_MIDDLEWARE = [
+      Hearth::Middleware::Validate,
+      Hearth::Middleware::HostPrefix,
+      Hearth::Middleware::Build,
+      Hearth::Middleware::Send,
+      Hearth::Middleware::Retry,
+      Hearth::Middleware::Parse
+    ].freeze
+
+    STANDARD_MIDDLEWARE.each do |klass|
+      simple_step_name = klass.to_s.split('::').last.downcase
+      %w[before after around].each do |method|
+        method_name = "#{method}_#{simple_step_name}"
+        define_method(method_name) do |*args, &block|
+          return send(method, klass, *args, &block)
+        end
+
+        define_singleton_method(method_name) do |*args, &block|
+          return send(method, klass, *args, &block)
+        end
+      end
+
+      remove_method_name = "remove_#{simple_step_name}"
+      define_method(remove_method_name) do
+        return remove(klass)
+      end
+
+      define_singleton_method(remove_method_name) do
+        return remove(klass)
+      end
+    end
+
+    def to_a
+      @middleware
+    end
+
+    private
+
+    def handler_or_proc!(args, &block)
+      validate_args!(args, &block)
+      callable = args.first || Proc.new(&block)
+      raise ArgumentError, CALLABLE unless callable.respond_to?(:call)
+
+      callable
+    end
+
+    def validate_args!(args, &block)
+      raise ArgumentError, BOTH if args.size.positive? && block
+      raise ArgumentError, NEITHER if args.empty? && block.nil?
+      raise ArgumentError, format(TOO_MANY, count: args.size) if args.size > 1
+    end
+  end
+end