hearth 1.0.0.pre1

data/lib/hearth/middleware_stack.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Hearth
+  # @api private
+  class MiddlewareStack
+    def initialize
+      @middleware = []
+    end
+
+    def use(middleware, **middleware_kwargs)
+      @middleware.push([middleware, middleware_kwargs])
+    end
+
+    def use_before(before, middleware, **middleware_kwargs)
+      new_middleware = []
+      @middleware.each do |klass, args|
+        new_middleware << [middleware, middleware_kwargs] if before == klass
+        new_middleware << [klass, args]
+      end
+      unless new_middleware.size == @middleware.size + 1
+        raise ArgumentError,
+              "Failed to insert #{middleware} before #{before}"
+      end
+
+      @middleware = new_middleware
+    end
+
+    def use_after(after, middleware, **middleware_kwargs)
+      new_middleware = []
+      @middleware.each do |klass, args|
+        new_middleware << [klass, args]
+        new_middleware << [middleware, middleware_kwargs] if after == klass
+      end
+      unless new_middleware.size == @middleware.size + 1
+        raise ArgumentError,
+              "Failed to insert #{middleware} after #{after}"
+      end
+
+      @middleware = new_middleware
+    end
+
+    def remove(remove)
+      new_middleware = []
+      @middleware.each do |klass, args|
+        new_middleware << [klass, args] unless klass == remove
+      end
+
+      unless new_middleware.size == @middleware.size - 1
+        raise ArgumentError,
+              "Failed to remove #{remove}"
+      end
+
+      @middleware = new_middleware
+    end
+
+    # @param input
+    # @param context
+    # @return [Output]
+    def run(input:, context:)
+      stack.call(input, context)
+    end
+
+    private
+
+    def stack
+      app = nil
+      @middleware.reverse_each do |(middleware, middleware_args)|
+        app = middleware.new(app, **middleware_args)
+      end
+      app
+    end
+  end
+end

data/lib/hearth/number_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A module that provides helper methods to convert Numeric objects to
+  # protocol specific serializable formats.
+  # @api private
+  module NumberHelper
+    class << self
+      # @param [Number,String] input
+      # @return [String] The serialized number
+      def serialize(input)
+        if input == ::Float::INFINITY then 'Infinity'
+        elsif input == -::Float::INFINITY then '-Infinity'
+        elsif input&.nan? then 'NaN'
+        else
+          input
+        end
+      end
+
+      # @param [String] str
+      # @return [Number] The input as a number
+      def deserialize(str)
+        case str
+        when 'Infinity' then ::Float::INFINITY
+        when '-Infinity' then -::Float::INFINITY
+        when 'NaN' then ::Float::NAN
+        when nil then nil
+        else str.to_f
+        end
+      end
+    end
+  end
+end

data/lib/hearth/output.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A wrapper class that contains an error or data from the response.
+  # @api private
+  class Output
+    # @param [StandardError] error The error class to be raised.
+    # @param [Struct] data The data returned by a client.
+    def initialize(error: nil, data: nil)
+      @error = error
+      @data = data
+    end
+
+    # @return [StandardError, nil]
+    attr_accessor :error
+
+    # @return [Struct, nil]
+    attr_accessor :data
+  end
+end

data/lib/hearth/structure.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A module mixed into Structs that provides utility methods.
+  module Structure
+    # Deeply converts the Struct into a hash. Structure members that
+    # are `nil` are omitted from the resultant hash.
+    #
+    # @return [Hash]
+    def to_h(obj = self)
+      case obj
+      when Struct
+        _to_h_struct(obj)
+      when Hash
+        _to_h_hash(obj)
+      when Array, Set
+        obj.collect { |value| to_hash(value) }
+      when Union
+        obj.to_h
+      else
+        obj
+      end
+    end
+    alias to_hash to_h
+
+    private
+
+    def _to_h_struct(obj)
+      obj.each_pair.with_object({}) do |(member, value), hash|
+        hash[member] = to_hash(value) unless value.nil?
+      end
+    end
+
+    def _to_h_hash(obj)
+      obj.each.with_object({}) do |(key, value), hash|
+        hash[key] = to_hash(value)
+      end
+    end
+  end
+end

data/lib/hearth/stubbing/client_stubs.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative 'stubs'
+
+module Hearth
+  # This module provides the ability to specify the data and/or errors to
+  # return when a client is using stubbed responses.
+  # This module should be included in generated service clients.
+  #
+  # Pass `stub_responses: true` to a client constructor to enable this
+  # behavior.
+  module ClientStubs
+    # Configures what data / errors should be returned from the named operation
+    # when response stubbing is enabled.
+    #
+    # ## Basic usage
+    #
+    # When you enable response stubbing, the client will generate fake
+    # responses and will not make any HTTP requests.
+    #
+    #     client = Service::Client.new(stub_responses: true)
+    #     client.operation
+    #     #=> #<struct Service:Types::Operation param1=[], param2=nil>
+    #
+    # You can specify the stub data using {#stub_responses}
+    #
+    #     client = Service::Client.new(stub_responses: true)
+    #     client.stub_responses(:operation, {
+    #       param1: [{ name: 'value1' }]
+    #     })
+    #
+    #     client.operation.param1.map(&:name)
+    #     #=> ['value1']
+    #
+    # ## Stubbing Errors
+    #
+    # When stubbing is enabled, the SDK will default to generate
+    # fake responses with placeholder values. You can override the data
+    # returned. You can also specify errors it should raise.
+    #
+    #     # to simulate errors, give the error class, you must
+    #     # be able to construct an instance with `.new`
+    #     client.stub_responses(:operation, Timeout::Error)
+    #     client.operation(param1: 'value')
+    #     #=> raises new Timeout::Error
+    #
+    #     # or you can give an instance of an error class
+    #     client.stub_responses(:operation, RuntimeError.new('custom message'))
+    #     client.operation(param1: 'value')
+    #     #=> raises the given runtime error object
+    #
+    # ## Dynamic Stubbing
+    #
+    # In addition to creating static stubs, it's also possible to generate
+    # stubs dynamically based on the parameters with which operations were
+    # called, by passing a `Proc` object:
+    #
+    #     client.stub_responses(:operation, -> (context) {
+    #       if context.params[:param] == 'foo'
+    #         # return a stub
+    #         { param1: [{ name: 'value1'}]}
+    #       else
+    #         # return an error
+    #         Services::Errors::NotFound
+    #       end
+    #     })
+    #
+    # ## Stubbing Raw Protocol Responses
+    #
+    # As an alternative to providing the response data, you can modify the
+    # response object provided by the `Proc` object and then
+    # return nil.
+    #
+    #     client.stub_responses(:operation, -> (context) {
+    #       context.response.status = 404 # simulate an error
+    #       nil
+    #     })
+    #
+    # ## Stubbing Multiple Responses
+    #
+    # Calling an operation multiple times will return similar responses.
+    # You can configure multiple stubs and they will be returned in sequence.
+    #
+    #     client.stub_responses(:operation, [
+    #       Errors::NotFound,
+    #       { content_length: 150 },
+    #     ])
+    #
+    #     client.operation(param1: 'value1')
+    #     #=> raises Errors::NotFound
+    #
+    #     resp = client.operation(param1: 'value2')
+    #     resp.content_length #=> 150
+    #
+    # @param [Symbol] operation_name
+    #
+    # @param [Mixed] stubs One or more responses to return from the named
+    #   operation.
+    #
+    # @return [void]
+    #
+    # @raise [RuntimeError] Raises a runtime error when called
+    #   on a client that has not enabled response stubbing via
+    #   `:stub_responses => true`.
+    def stub_responses(operation_name, *stubs)
+      if @stub_responses
+        @stubs.add_stubs(operation_name, stubs.flatten)
+      else
+        msg = 'Stubbing is not enabled. Enable stubbing in the constructor '\
+              'with `stub_responses: true`'
+        raise ArgumentError, msg
+      end
+    end
+  end
+end

data/lib/hearth/stubbing/stubs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Hearth
+  # @api private
+  module Stubbing
+    # Provides a thread safe data structure for adding and getting stubs
+    # per operation.
+    class Stubs
+      def initialize
+        @stubs = {}
+        @stub_mutex = Mutex.new
+      end
+
+      def add_stubs(operation_name, stubs)
+        @stub_mutex.synchronize do
+          @stubs[operation_name.to_sym] = stubs
+        end
+      end
+
+      def next(operation_name)
+        @stub_mutex.synchronize do
+          stubs = @stubs[operation_name] || []
+          case stubs.length
+          when 0 then nil
+          when 1 then stubs.first
+          else stubs.shift
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hearth/time_helper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Hearth
+  # A module that provides helper methods to convert from Time objects to
+  # protocol specific serializable formats.
+  # @api private
+  module TimeHelper
+    class << self
+      # @param [Time] time
+      # @return [String<Date Time>] The time as an ISO8601 string.
+      def to_date_time(time)
+        time.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+      end
+
+      # @param [Time] time
+      # @return [Float<Epoch Seconds>] Returns float value of
+      #   epoch seconds with millisecond precision.
+      def to_epoch_seconds(time)
+        time = time.utc
+        epoch_seconds = time.to_i
+        epoch_seconds += (time.nsec / 1_000_000) / 1000.0
+        epoch_seconds
+      end
+
+      # @param [Time] time
+      # @return [String<Http Date>] Returns the time formatted
+      #   as an HTTP header date.
+      def to_http_date(time)
+        time.utc.httpdate
+      end
+    end
+  end
+end

data/lib/hearth/union.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Hearth
+  # Top level class for all Union types
+  class Union < ::SimpleDelegator
+    include Hearth::Structure
+  end
+end

data/lib/hearth/validator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Utility module for working with request parameters.
+  #
+  # * Validate structure of parameters against the expected type.
+  # * Raise errors with context when validation fails.
+  # @api private
+  module Validator
+    # Validate the given values is of the given type(s).
+    # @raise [ArgumentError] Raises when the value is not one of given type(s).
+    def self.validate!(value, *types, context:)
+      return if !value || types.any? { |type| value.is_a?(type) }
+
+      raise ArgumentError,
+            "Expected #{context} to be in "\
+            "[#{types.map(&:to_s).join(', ')}], got #{value.class}."
+    end
+  end
+end

data/lib/hearth/waiters/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Waiters
+    module Errors
+      class WaiterFailed < StandardError; end
+
+      class FailureStateError < StandardError; end
+
+      class UnexpectedError < StandardError; end
+
+      class MaxWaitTimeExceeded < StandardError; end
+    end
+  end
+end

data/lib/hearth/waiters/poller.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'jmespath'
+
+module Hearth
+  module Waiters
+    # Abstract Poller used by generated service Waiters. This class handles
+    # sending the request and matching input or output.
+    class Poller
+      # @api private
+      def initialize(options = {})
+        @operation_name = options[:operation_name]
+        @acceptors = options[:acceptors]
+        @input = nil
+      end
+
+      # Makes an API call, returning the resultant state and the response.
+      #
+      # * `:success` - A success state has been matched.
+      # * `:failure` - A terminate failure state has been matched.
+      # * `:retry`   - The waiter may be retried.
+      # * `:error`   - The waiter encountered an un-expected error.
+      #
+      # @example A trival (bad) example of a waiter that polls indefinetly.
+      #
+      #   loop do
+      #
+      #     state, resp = poller.call(client, params, options)
+      #
+      #     case state
+      #     when :success then return true
+      #     when :failure then return false
+      #     when :retry   then next
+      #     when :error   then raise 'oops'
+      #     end
+      #
+      #   end
+      #
+      # @param [Client] client
+      # @param [Hash] params
+      # @param [Hash] options
+      # @return [Array<Symbol,Response>]
+      def call(client, params = {}, options = {})
+        begin
+          options = options.merge(input_output_middleware)
+          response = client.send(@operation_name, params, options)
+        rescue Hearth::ApiError => e
+          error = e
+        end
+        resp_or_error = error || response
+        @acceptors.each do |acceptor|
+          if acceptor_matches?(acceptor[:matcher], response, error)
+            return [acceptor[:state].to_sym, resp_or_error]
+          end
+        end
+        [error ? :error : :retry, resp_or_error]
+      end
+
+      private
+
+      def input_output_middleware
+        middleware = lambda do |input, _context|
+          @input = input # get internal details of middleware
+        end
+        { middleware: MiddlewareBuilder.before_send(middleware) }
+      end
+
+      def acceptor_matches?(matcher, response, error)
+        if (m = matcher[:success])
+          success_matcher?(m, response, error)
+        elsif (m = matcher[:errorType])
+          error_type_matcher?(m, error)
+        elsif (m = matcher[:inputOutput])
+          input_output_matcher?(m, response, error)
+        elsif (m = matcher[:output])
+          output_matcher?(m, response, error)
+        end
+      end
+
+      def success_matcher?(matcher, response, error)
+        (matcher == true && response) || (matcher == false && error)
+      end
+
+      def error_type_matcher?(matcher, error)
+        # handle shape ID cases
+        matcher = matcher.split('#').last.split('$').first
+        error.class.to_s.include?(matcher) || error.error_code == matcher
+      end
+
+      def input_output_matcher?(matcher, response, error)
+        return false if error
+
+        data = { input: @input, output: response }
+        send(
+          "matches_#{matcher[:comparator]}?",
+          JMESPath.search(matcher[:path], data),
+          matcher[:expected]
+        )
+      end
+
+      def output_matcher?(matcher, response, error)
+        return false if error
+
+        send(
+          "matches_#{matcher[:comparator]}?",
+          JMESPath.search(matcher[:path], response),
+          matcher[:expected]
+        )
+      end
+
+      # rubocop:disable Naming/MethodName
+      def matches_stringEquals?(value, expected)
+        value == expected
+      end
+
+      def matches_booleanEquals?(value, expected)
+        value.to_s == expected
+      end
+
+      def matches_allStringEquals?(values, expected)
+        values.is_a?(Array) && !values.empty? &&
+          values.all? { |v| v == expected }
+      end
+
+      def matches_anyStringEquals?(values, expected)
+        values.is_a?(Array) && !values.empty? &&
+          values.any? { |v| v == expected }
+      end
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end

data/lib/hearth/waiters/waiter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Waiters
+    # Abstract waiter class with high level logic for polling and waiting.
+    class Waiter
+      # @api private
+      def initialize(options = {})
+        unless options[:max_wait_time].is_a?(Integer)
+          raise ArgumentError,
+                'Waiter must be initialized with `:max_wait_time`'
+        end
+
+        @max_wait_time = options[:max_wait_time]
+        @min_delay = options[:min_delay]
+        @max_delay = options[:max_delay]
+        @poller = options[:poller]
+
+        @remaining_time = @max_wait_time
+        @one_more_retry = false
+      end
+
+      attr_reader :max_wait_time, :min_delay, :max_delay
+
+      # @param [Client] client The client to poll with.
+      # @param [Hash] params The params for the operation.
+      # @param [Hash] options Any operation options.
+      def wait(client, params = {}, options = {})
+        poll(client, params, options)
+        true
+      end
+
+      private
+
+      # https://awslabs.github.io/smithy/1.0/spec/waiters.html#waiter-workflow
+      def poll(client, params, options)
+        n = 0
+        loop do
+          state, resp_or_error = @poller.call(client, params, options)
+          n += 1
+
+          case state
+          when :retry then nil
+          when :success then return
+          when :failure then raise Errors::FailureStateError, resp_or_error
+          when :error   then raise Errors::UnexpectedError, resp_or_error
+          end
+
+          raise Errors::MaxWaitTimeExceeded if @one_more_retry
+
+          delay = delay(n)
+          @remaining_time -= delay
+          Kernel.sleep(delay)
+        end
+      end
+
+      def delay(attempt)
+        delay = if attempt > attempt_ceiling
+                  max_delay
+                else
+                  min_delay * (2**(attempt - 1))
+                end
+
+        delay = Kernel.rand(min_delay..delay)
+
+        if @remaining_time - delay <= min_delay
+          delay = @remaining_time - min_delay
+          @one_more_retry = true
+        end
+
+        delay
+      end
+
+      def attempt_ceiling
+        (Math.log(max_delay.to_f / min_delay) / Math.log(2)) + 1
+      end
+    end
+  end
+end

data/lib/hearth/xml/formatter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Hearth
+  module XML
+    # A class used for formatting XML strings.
+    # @api private
+    class Formatter
+      NEGATIVE_INDENT = 'indent must be greater than or equal to zero'
+
+      # @param [String] indent
+      #   When `indent` is non-empty whitespace, then the XML will
+      #   be pretty-formatted with each level of nodes indented by
+      #   `indent`.
+      # @raise [ArgumentError] when indent is not a String.
+      def initialize(indent: '')
+        unless indent.is_a?(String)
+          raise ArgumentError, "expected a String, got #{indent.class}"
+        end
+
+        @indent = indent
+        @eol = indent.empty? ? '' : "\n"
+      end
+
+      # @param [Node] node
+      # @return [String<XML>]
+      def format(node)
+        buffer = StringIO.new
+        serialize(buffer, node, '')
+        buffer.string
+      end
+
+      private
+
+      def serialize(buffer, node, pad)
+        return buffer.write(self_close_node(node, pad)) if node.empty?
+        return buffer.write(text_node(node, pad)) if node.text
+
+        serialize_nested(buffer, node, pad)
+      end
+
+      def self_close_node(node, pad)
+        "#{pad}<#{node.name}#{attrs(node)}/>#{@eol}"
+      end
+
+      def text_node(node, pad)
+        text = node.text.encode(xml: :text)
+        "#{pad}<#{node.name}#{attrs(node)}>#{text}</#{node.name}>#{@eol}"
+      end
+
+      def serialize_nested(buffer, node, pad)
+        buffer.write("#{pad}<#{node.name}#{attrs(node)}>#{@eol}")
+        nested_pad = "#{pad}#{@indent}"
+        node.child_nodes.each do |child_node|
+          serialize(buffer, child_node, nested_pad)
+        end
+        buffer.write("#{pad}</#{node.name}>#{@eol}")
+      end
+
+      def attrs(node)
+        node.attributes.map do |key, value|
+          " #{key}=#{value.to_s.encode(xml: :attr)}"
+        end.join
+      end
+    end
+  end
+end