hearth 1.0.0.pre1

data/lib/hearth/xml/node.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Hearth
+  module XML
+    # A class used to represent an XML node.
+    # @api private
+    class Node
+      # @api private
+      BOTH_TYPES = 'Nodes may not have both text and child nodes'
+
+      # @param [String] name
+      def initialize(name, *children)
+        @name = name
+        @attributes = {}
+        @child_nodes = []
+        @child_node_map = {}
+        @text = []
+        append(*children)
+      end
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [Hash<String, String>]
+      attr_reader :attributes
+
+      def <<(*children)
+        children.flatten.each do |child|
+          case child
+          when Node
+            raise ArgumentError, BOTH_TYPES unless @text.empty?
+
+            @child_nodes << child
+            @child_node_map[child.name] ||= []
+            @child_node_map[child.name] << child
+          when String
+            raise ArgumentError, BOTH_TYPES unless @child_nodes.empty?
+
+            @text << child
+          else
+            raise ArgumentError, 'expected Hearth::XML::Node or String, ' \
+                                 "got #{child.class}"
+          end
+        end
+      end
+      alias append <<
+
+      # @return [String, nil]
+      def text
+        @text.empty? ? nil : @text.join
+      end
+
+      # @param [String] node_name
+      # @return [Array<Node>]
+      def [](node_name)
+        children(node_name)
+      end
+
+      # @overload children()
+      #   @return [Array<Node>] Returns an array of all child nodes.
+      # @overload children(child_name)
+      #   @param [String] child_name
+      #   @return [Array<Node>] Returns an array of child nodes with the given
+      #     name.
+      def children(*args)
+        nodes =
+          case args.count
+          when 0 then @child_nodes
+          when 1 then @child_node_map.fetch(args.first, [])
+          else raise ArgumentError, 'expected 0 or 1 arguments'
+          end
+        yield(nodes) if block_given? && !nodes.empty?
+        nodes
+      end
+      alias child_nodes children
+
+      # @return [Boolean]
+      def empty?
+        @child_nodes.empty? && @text.empty?
+      end
+
+      # @return [Array<String>]
+      def child_node_names
+        @child_node_map.keys
+      end
+
+      # @return [Boolean]
+      def child_node?(name)
+        @child_node_map.key?(name)
+      end
+
+      # @yield [child]
+      # @yieldparam child [Node]
+      # @return [Node, nil]
+      def child(child_name)
+        child = @child_node_map[child_name]&.first
+        yield(child) if block_given? && !child.nil?
+        child
+      end
+      alias at child
+
+      # @yield [text]
+      # @yieldparam text [String]
+      # @return [String, nil]
+      def text_at(child_name)
+        text = @child_node_map[child_name].first&.text
+        yield(text) if block_given? && !text.nil?
+        text
+      end
+
+      # @option options [String] :indent ('')
+      #   When `indent` is non-empty whitespace, then the XML will
+      #   be pretty-formatted with each level of nodes indented by
+      #   `indent`.
+      # @return [String<XML>]
+      def to_xml(indent: '')
+        Formatter.new(indent: indent).format(self)
+      end
+      alias to_str to_xml
+      alias to_s to_xml
+    end
+  end
+end

data/lib/hearth/xml/node_matcher.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+# Provides an rspec matcher for Hearth::XML::Node
+# @api private
+RSpec::Matchers.define :match_xml_node do |expected|
+  match do |actual|
+    return true if actual == expected
+    return false unless actual.instance_of?(expected.class)
+
+    expect(actual.name).to eq(expected.name)
+    expect(actual.text).to eq(expected.text)
+    expect(actual.attributes).to eq(expected.attributes)
+
+    expect(actual.children.length).to eq(expected.children.length)
+
+    expected.children.zip(actual.children).each do |a, e|
+      expect(a).to match_xml_node(e)
+    end
+  end
+
+  diffable
+end

data/lib/hearth/xml/parse_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hearth
+  module XML
+    # An error class encountered when parsing XML.
+    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/xml.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'xml/formatter'
+require_relative 'xml/node'
+require_relative 'xml/parse_error'
+
+require 'rexml'
+
+module Hearth
+  # Hearth::XML is a purpose-built set of utilities for working with
+  # XML. It does not support many/most features of generic XML
+  # parsing and serialization.
+  # @api private
+  module XML
+    class << self
+      # @param [String] xml
+      # @return [Node]
+      def parse(xml)
+        doc = REXML::Document.new(xml.strip)
+        raise "no XML element found: #{xml.inspect}" unless doc.root
+
+        parse_node(doc.root)
+      rescue StandardError => e
+        raise ParseError, e
+      end
+
+      private
+
+      def parse_node(rexml_node)
+        node = Node.new(rexml_node.name)
+        apply_attributes(node, rexml_node)
+        apply_child_nodes(node, rexml_node)
+        apply_text(node, rexml_node)
+        node
+      end
+
+      def apply_attributes(node, rexml_node)
+        rexml_node.attributes.each_attribute do |attr|
+          node.attributes[attr.name] = attr.value
+        end
+      end
+
+      def apply_text(node, rexml_node)
+        text = rexml_node.text
+        return if text.nil?
+        return if text.strip.empty? && !node.empty?
+
+        node.append(text)
+      end
+
+      def apply_child_nodes(node, rexml_node)
+        rexml_node.each_element do |value|
+          node.append(parse_node(value))
+        end
+      end
+    end
+  end
+end

data/lib/hearth.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'hearth/api_error'
+require_relative 'hearth/block_io'
+require_relative 'hearth/context'
+require_relative 'hearth/http'
+require_relative 'hearth/json'
+require_relative 'hearth/middleware'
+require_relative 'hearth/middleware_builder'
+require_relative 'hearth/middleware_stack'
+require_relative 'hearth/number_helper'
+require_relative 'hearth/output'
+require_relative 'hearth/structure'
+require_relative 'hearth/stubbing/client_stubs'
+require_relative 'hearth/stubbing/stubs'
+require_relative 'hearth/time_helper'
+require_relative 'hearth/union'
+require_relative 'hearth/validator'
+require_relative 'hearth/waiters/errors'
+require_relative 'hearth/waiters/poller'
+require_relative 'hearth/waiters/waiter'
+require_relative 'hearth/xml'
+
+module Hearth
+  VERSION = File.read(File.expand_path('../VERSION', __dir__)).strip
+end

data/sig/lib/seahorse/api_error.rbs

@@ -0,0 +1,10 @@
+module Hearth
+  # Base class for errors returned from an API. This excludes networking
+  # errors and errors generated on the client-side.
+  class ApiError < StandardError
+    def initialize: (error_code: String, ?message: String) -> ApiError
+
+    # @return [String]
+    attr_reader error_code: String
+  end
+end

data/sig/lib/seahorse/document.rbs

@@ -0,0 +1,2 @@
+# Declare an alias for Document shapes
+type document = Hash[Symbol,document] | Array[document] | String | bool | Numeric

data/sig/lib/seahorse/http/api_error.rbs

@@ -0,0 +1,21 @@
+module Hearth
+  module HTTP
+    # Base class for HTTP errors returned from an API. Inherits from
+    # {Hearth::ApiError}.
+    class ApiError < Hearth::ApiError
+      def initialize: (http_resp: Response, **untyped kwargs) -> ApiError
+
+      # @return [Integer]
+      attr_reader http_status: Integer
+
+      # @return [Hash<String, String>]
+      attr_reader http_headers: Hash[String, String]
+
+      # @return [String]
+      attr_reader http_body: String
+
+      # @return [String]
+      attr_reader request_id: String
+    end
+  end
+end

data/sig/lib/seahorse/http/headers.rbs

@@ -0,0 +1,47 @@
+module Hearth
+  module HTTP
+    # Provides Hash like access for Headers with key normalization
+    # @api private
+    class Headers
+      # @param [Hash<String,String>] headers
+      def initialize: (?headers: ::Hash[String, String] headers) -> Headers
+
+      # @param [String] key
+      def []: (String key) -> String
+
+      # @param [String] key
+      # @param [String] value
+      def []=: (String key, String value) -> String
+
+      # @param [String] key
+      # @return [Boolean] Returns `true` if there is a header with
+      #   the given key.
+      def key?: (String key) -> bool
+
+      # @return [Array<String>]
+      def keys: () -> Array[String]
+
+      # @param [String] key
+      # @return [String, nil] Returns the value for the deleted key.
+      def delete: (String key) -> (String | nil)
+
+      # @return [Enumerable<String,String>]
+      def each_pair: () { () -> String } -> Enumerable[Array[String]]
+
+      alias each each_pair
+
+      # @return [Hash]
+      def to_hash: () -> Hash[String, String]
+
+      alias to_h to_hash
+
+      # @return [Integer] Returns the number of entries in the headers
+      #   hash.
+      def size: () -> Integer
+
+      private
+
+      def normalize: (String key) -> String
+    end
+  end
+end

data/sig/lib/seahorse/http/response.rbs

@@ -0,0 +1,21 @@
+module Hearth
+  module HTTP
+    # Represents an HTTP Response.
+    # @api private
+    class Response
+      # @param [Integer] status
+      # @param [Headers] headers
+      # @param [IO] body
+      def initialize: (?status: ::Integer status, ?headers: Headers headers, ?body: IO body) -> Response
+
+      # @return [Integer]
+      attr_accessor status: Integer
+
+      # @return [Headers]
+      attr_accessor headers: Headers
+
+      # @return [IO]
+      attr_accessor body: IO
+    end
+  end
+end

data/sig/lib/seahorse/simple_delegator.rbs

@@ -0,0 +1,3 @@
+# Hack - https://github.com/ruby/delegate/issues/8
+class SimpleDelegator
+end

data/sig/lib/seahorse/structure.rbs

@@ -0,0 +1,18 @@
+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: (?untyped obj) -> Hash[Symbol,untyped]
+
+    alias to_hash to_h
+
+    private
+
+    def _to_h_struct: (untyped obj) -> untyped
+
+    def _to_h_hash: (untyped obj) -> untyped
+  end
+end

data/sig/lib/seahorse/stubbing/client_stubs.rbs

@@ -0,0 +1,103 @@
+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: (Symbol operation_name, *Hearth::Stubbing::Stubs stubs) -> void
+  end
+end

data/sig/lib/seahorse/stubbing/stubs.rbs

@@ -0,0 +1,14 @@
+module Hearth
+  # @api private
+  module Stubbing
+    # Provides a thread safe data structure for adding and getting stubs
+    # per operation.
+    class Stubs
+      def initialize: () -> Stubs
+
+      def add_stubs: (Symbol operation_name, Array[Hash[Symbol, untyped]] | Proc | StandardError stubs) -> void
+
+      def next: (Symbol operation_name) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/lib/seahorse/union.rbs

@@ -0,0 +1,6 @@
+module Hearth
+  # Top level class for all Union types
+  class Union < ::SimpleDelegator
+    include Hearth::Structure
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: hearth
+version: !ruby/object:Gem::Version
+  version: 1.0.0.pre1
+platform: ruby
+authors:
+- Amazon Web Services
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jmespath
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- VERSION
+- lib/hearth.rb
+- lib/hearth/api_error.rb
+- lib/hearth/block_io.rb
+- lib/hearth/context.rb
+- lib/hearth/http.rb
+- lib/hearth/http/api_error.rb
+- lib/hearth/http/client.rb
+- lib/hearth/http/error_parser.rb
+- lib/hearth/http/headers.rb
+- lib/hearth/http/middleware/content_length.rb
+- lib/hearth/http/networking_error.rb
+- lib/hearth/http/request.rb
+- lib/hearth/http/response.rb
+- lib/hearth/json.rb
+- lib/hearth/json/parse_error.rb
+- lib/hearth/middleware.rb
+- lib/hearth/middleware/around_handler.rb
+- lib/hearth/middleware/build.rb
+- lib/hearth/middleware/host_prefix.rb
+- lib/hearth/middleware/parse.rb
+- lib/hearth/middleware/request_handler.rb
+- lib/hearth/middleware/response_handler.rb
+- lib/hearth/middleware/retry.rb
+- lib/hearth/middleware/send.rb
+- lib/hearth/middleware/validate.rb
+- lib/hearth/middleware_builder.rb
+- lib/hearth/middleware_stack.rb
+- lib/hearth/number_helper.rb
+- lib/hearth/output.rb
+- lib/hearth/structure.rb
+- lib/hearth/stubbing/client_stubs.rb
+- lib/hearth/stubbing/stubs.rb
+- lib/hearth/time_helper.rb
+- lib/hearth/union.rb
+- lib/hearth/validator.rb
+- lib/hearth/waiters/errors.rb
+- lib/hearth/waiters/poller.rb
+- lib/hearth/waiters/waiter.rb
+- lib/hearth/xml.rb
+- lib/hearth/xml/formatter.rb
+- lib/hearth/xml/node.rb
+- lib/hearth/xml/node_matcher.rb
+- lib/hearth/xml/parse_error.rb
+- sig/lib/seahorse/api_error.rbs
+- sig/lib/seahorse/document.rbs
+- sig/lib/seahorse/http/api_error.rbs
+- sig/lib/seahorse/http/headers.rbs
+- sig/lib/seahorse/http/response.rbs
+- sig/lib/seahorse/simple_delegator.rbs
+- sig/lib/seahorse/structure.rbs
+- sig/lib/seahorse/stubbing/client_stubs.rbs
+- sig/lib/seahorse/stubbing/stubs.rbs
+- sig/lib/seahorse/union.rbs
+homepage:
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: A base library for Smithy generated SDKs
+test_files: []