hearth 1.0.0.pre1 → 1.0.0.pre3

data/lib/hearth/signers/http_basic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP Basic Auth scheme.
+    class HTTPBasic
+      # rubocop:disable Lint/UnusedMethodArgument
+      def sign(request:, identity:, properties:)
+        # TODO: does not handle realm or other properties
+        identity_string = "#{identity.username}:#{identity.password}"
+        encoded = Base64.strict_encode64(identity_string)
+        request.headers['Authorization'] = "Basic #{encoded}"
+      end
+
+      def reset(request:, properties:)
+        request.headers.delete('Authorization')
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/hearth/signers/http_bearer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP Bearer Auth scheme.
+    class HTTPBearer < Signers::Base
+      # rubocop:disable Lint/UnusedMethodArgument
+      def sign(request:, identity:, properties:)
+        # TODO: does not handle realm or other properties
+        request.headers['Authorization'] = "Bearer #{identity.token}"
+      end
+
+      def reset(request:, properties:)
+        request.headers.delete('Authorization')
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/hearth/signers/http_digest.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP Digest Auth scheme.
+    class HTTPDigest < Signers::Base
+      def sign(request:, identity:, properties:)
+        # TODO: requires a nonce from the server - this cannot
+        # be implemented unless we rescue from a 401 and retry
+        # with the nonce
+        raise NotImplementedError
+      end
+
+      def reset(request:, properties:)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/hearth/signers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Namespace for all Signer classes.
+  module Signers
+    # Base class for all Signer classes.
+    class Base
+      def sign(request:, identity:, properties:)
+        raise NotImplementedError
+      end
+
+      def reset(request:, properties:)
+        raise NotImplementedError
+      end
+    end
+  end
+end
+
+require_relative 'signers/anonymous'
+require_relative 'signers/http_api_key'
+require_relative 'signers/http_basic'
+require_relative 'signers/http_bearer'
+require_relative 'signers/http_digest'

data/lib/hearth/structure.rb

@@ -6,15 +6,15 @@ module Hearth
     # Deeply converts the Struct into a hash. Structure members that
     # are `nil` are omitted from the resultant hash.
     #
-    # @return [Hash]
+    # @return [Hash, Structure]
     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 Array
+        _to_h_array(obj)
       when Union
         obj.to_h
       else
@@ -36,5 +36,9 @@ module Hearth
         hash[key] = to_hash(value)
       end
     end
+
+    def _to_h_array(obj)
+      obj.collect { |value| to_hash(value) }
+    end
   end
 end

data/lib/hearth/stubs.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Provides a thread safe data structure for adding and getting stubs
+  # per operation.
+  class Stubs
+    # Initializes the stubs with an optional hash of stubs.
+    # For an example of stubs, see {ClientStubs}.
+    # @param [Hash<Symbol, Array<Stub>>] stubs
+    def initialize(stubs = {})
+      @stubs = stubs
+      @stub_mutex = Mutex.new
+    end
+
+    # Adds a stub or list of stubs to the given operation name.
+    # @param [String] operation_name
+    # @param [Array<Stub>] stubs
+    def set_stubs(operation_name, stubs)
+      @stub_mutex.synchronize do
+        @stubs[operation_name.to_sym] = stubs
+      end
+    end
+
+    # Returns the next stub for the given operation name.
+    # @param [String] operation_name
+    # @return [Stub, nil]
+    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

data/lib/hearth/time_helper.rb

@@ -11,24 +11,25 @@ module Hearth
       # @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')
+        optional_ms_digits = time.subsec.zero? ? nil : 3
+        time.utc.iso8601(optional_ms_digits)
       end
 
       # @param [Time] time
-      # @return [Float<Epoch Seconds>] Returns float value of
+      # @return [Float<Epoch Seconds>] Returns the 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
+        epoch_seconds + ((time.nsec / 1_000_000) / 1000.0)
       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
+        fractional = '.%L' unless time.subsec.zero?
+        time.utc.strftime("%a, %d %b %Y %H:%M:%S#{fractional} GMT")
       end
     end
   end

data/lib/hearth/validator.rb

@@ -3,18 +3,73 @@
 module Hearth
   # Utility module for working with request parameters.
   #
-  # * Validate structure of parameters against the expected type.
+  # * Validate structure of parameters against the expected input.
   # * Raise errors with context when validation fails.
   # @api private
   module Validator
-    # Validate the given values is of the given type(s).
+    # Validate the given value is within the expected range (inclusive).
+    # @param value [Object] The value to validate.
+    # @param min [Numeric] The minimum that the given value should be.
+    # @param max [Numeric] The maximum that the given value should be.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when the value is not within expected range.
+    def self.validate_range!(value, min:, max:, context:)
+      return if value.nil? || value.between?(min, max)
+
+      raise ArgumentError,
+            "Expected #{context} to be between " \
+            "#{min} to #{max}, got #{value}."
+    end
+
+    # Validate the given value responds to the given methods.
+    # @param value [Object] The value to validate.
+    # @param methods [Array<Symbol>] The methods to validate against.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when the value does not respond to the
+    #   methods.
+    def self.validate_responds_to!(value, *methods, context:)
+      if value.nil? || methods.all? { |method| value.respond_to?(method) }
+        return
+      end
+
+      raise ArgumentError,
+            "Expected #{context} to respond to " \
+            "[#{methods.map(&:to_s).join(', ')}], got #{value.class}."
+    end
+
+    # Validate a value is present and not nil.
+    # @param value [Object] The value to validate.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when the value is nil.
+    def self.validate_required!(value, context:)
+      raise ArgumentError, "Expected #{context} to be set." if value.nil?
+    end
+
+    # Validate the given value is of the given type(s).
+    # @param value [Object] The value to validate.
+    # @param types [Array<Class>] The types to validate against.
+    # @param context [String] The context of the value being validated.
     # @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) }
+    def self.validate_types!(value, *types, context:)
+      return if value.nil? || types.any? { |type| value.is_a?(type) }
 
       raise ArgumentError,
-            "Expected #{context} to be in "\
+            "Expected #{context} to be in " \
             "[#{types.map(&:to_s).join(', ')}], got #{value.class}."
     end
+
+    # Validate unknown parameters are not present for a given Struct.
+    # @param struct [Struct] The Struct to validate against.
+    # @param params [Hash] The parameters to validate.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when unknown parameters are present.
+    def self.validate_unknown!(struct, params, context:)
+      unknown = params.keys - struct.members
+      return if unknown.empty?
+
+      unknown = unknown.map { |key| "#{context}[:#{key}]" }
+      raise ArgumentError,
+            "Unexpected members: [#{unknown.join(', ')}]"
+    end
   end
 end

data/lib/hearth/waiters/poller.rb

@@ -6,8 +6,8 @@ module Hearth
   module Waiters
     # Abstract Poller used by generated service Waiters. This class handles
     # sending the request and matching input or output.
+    # @api private
     class Poller
-      # @api private
       def initialize(options = {})
         @operation_name = options[:operation_name]
         @acceptors = options[:acceptors]
@@ -21,7 +21,7 @@ module Hearth
       # * `: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.
+      # @example A trivial (bad) example of a waiter that polls indefinitely.
       #
       #   loop do
       #
@@ -39,10 +39,10 @@ module Hearth
       # @param [Client] client
       # @param [Hash] params
       # @param [Hash] options
-      # @return [Array<Symbol,Response>]
+      # @return [Array<Symbol, Response, ApiError>]
       def call(client, params = {}, options = {})
         begin
-          options = options.merge(input_output_middleware)
+          options = options.merge(input_output_interceptor)
           response = client.send(@operation_name, params, options)
         rescue Hearth::ApiError => e
           error = e
@@ -58,11 +58,10 @@ module Hearth
 
       private
 
-      def input_output_middleware
-        middleware = lambda do |input, _context|
-          @input = input # get internal details of middleware
-        end
-        { middleware: MiddlewareBuilder.before_send(middleware) }
+      def input_output_interceptor
+        # get internal details - capture input before send
+        interceptor = proc { |context| @input = context.input }
+        { interceptors: [Interceptor.new(read_before_transmit: interceptor)] }
       end
 
       def acceptor_matches?(matcher, response, error)
@@ -82,6 +81,8 @@ module Hearth
       end
 
       def error_type_matcher?(matcher, error)
+        return false unless error
+
         # handle shape ID cases
         matcher = matcher.split('#').last.split('$').first
         error.class.to_s.include?(matcher) || error.error_code == matcher

data/lib/hearth/waiters/waiter.rb

@@ -2,9 +2,22 @@
 
 module Hearth
   module Waiters
+    # A super class error that is raised when a waiter detects a condition
+    # where the waiter can never succeed.
+    class WaiterFailed < StandardError; end
+
+    # Raised when the waiter reached an expected failure state.
+    class FailureStateError < WaiterFailed; end
+
+    # Raised when the waiter has reached the maximum waiting time.
+    class MaxWaitTimeExceededError < WaiterFailed; end
+
+    # Raised when the waiter received an unexpected error.
+    class UnexpectedError < WaiterFailed; end
+
     # Abstract waiter class with high level logic for polling and waiting.
+    # @api private
     class Waiter
-      # @api private
       def initialize(options = {})
         unless options[:max_wait_time].is_a?(Integer)
           raise ArgumentError,
@@ -42,11 +55,11 @@ module Hearth
           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
+          when :failure then raise FailureStateError, resp_or_error
+          when :error   then raise UnexpectedError, resp_or_error
           end
 
-          raise Errors::MaxWaitTimeExceeded if @one_more_retry
+          raise MaxWaitTimeExceededError if @one_more_retry
 
           delay = delay(n)
           @remaining_time -= delay
@@ -55,11 +68,12 @@ module Hearth
       end
 
       def delay(attempt)
-        delay = if attempt > attempt_ceiling
-                  max_delay
-                else
-                  min_delay * (2**(attempt - 1))
-                end
+        delay =
+          if attempt > attempt_ceiling
+            max_delay
+          else
+            min_delay * (2**(attempt - 1))
+          end
 
         delay = Kernel.rand(min_delay..delay)
 

data/lib/hearth/xml/formatter.rb

@@ -45,7 +45,7 @@ module Hearth
       end
 
       def text_node(node, pad)
-        text = node.text.encode(xml: :text)
+        text = escape(node.text, :text)
         "#{pad}<#{node.name}#{attrs(node)}>#{text}</#{node.name}>#{@eol}"
       end
 
@@ -60,9 +60,18 @@ module Hearth
 
       def attrs(node)
         node.attributes.map do |key, value|
-          " #{key}=#{value.to_s.encode(xml: :attr)}"
+          " #{key}=#{escape(value, :attr)}"
         end.join
       end
+
+      def escape(string, text_or_attr)
+        string.to_s
+              .encode(xml: text_or_attr)
+              .gsub("\u{000D}", '&#xD;') # Carriage Return
+              .gsub("\u{000A}", '&#xA;') # Line Feed
+              .gsub("\u{0085}", '&#x85;') # Next Line
+              .gsub("\u{2028}", '&#x2028;') # Line Separator
+      end
     end
   end
 end

data/lib/hearth/xml/node.rb

@@ -5,13 +5,12 @@ module Hearth
     # 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)
+      def initialize(name, *children, attributes: {})
         @name = name
-        @attributes = {}
+        @attributes = attributes
         @child_nodes = []
         @child_node_map = {}
         @text = []

data/lib/hearth/xml/node_matcher.rb

@@ -3,7 +3,6 @@
 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

data/lib/hearth.rb

@@ -1,22 +1,53 @@
 # frozen_string_literal: true
 
 require_relative 'hearth/api_error'
+require_relative 'hearth/auth_option'
+
+# must be required before auth_schemes
+require_relative 'hearth/identities'
+require_relative 'hearth/auth_schemes'
+require_relative 'hearth/anonymous_auth_resolver'
+
 require_relative 'hearth/block_io'
+require_relative 'hearth/checksums'
+require_relative 'hearth/client'
+require_relative 'hearth/configuration'
+require_relative 'hearth/config/env_provider'
+require_relative 'hearth/config/resolver'
+require_relative 'hearth/connection_pool'
 require_relative 'hearth/context'
+require_relative 'hearth/dns'
+
+# must be required before http
+require_relative 'hearth/middleware'
+require_relative 'hearth/networking_error'
+require_relative 'hearth/request'
+require_relative 'hearth/response'
+
+# must be required before endpoint rules
+require_relative 'hearth/structure'
+
+require_relative 'hearth/endpoint_rules'
 require_relative 'hearth/http'
+require_relative 'hearth/identity_provider'
+require_relative 'hearth/interceptor'
+require_relative 'hearth/interceptors'
+require_relative 'hearth/interceptor_context'
+require_relative 'hearth/interceptor_list'
 require_relative 'hearth/json'
-require_relative 'hearth/middleware'
-require_relative 'hearth/middleware_builder'
+require_relative 'hearth/plugin_list'
 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/query/param'
+require_relative 'hearth/query/param_list'
+require_relative 'hearth/refreshing_identity_provider'
+require_relative 'hearth/retry'
+require_relative 'hearth/signers'
+require_relative 'hearth/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'

data/sig/lib/hearth/aliases.rbs

@@ -0,0 +1,6 @@
+module Hearth
+  type document = Hash[Symbol, document] | Array[document] | String | bool | Numeric
+
+  type stub = Structure | Response | { data: Hash[Symbol, untyped] } |
+    { error: { class: Class, data: Hash[Symbol, untyped] } } | ApiError | Proc
+end

data/sig/lib/hearth/anonymous_auth_resolver.rbs

@@ -0,0 +1,5 @@
+module Hearth
+  class AnonymousAuthResolver
+    def resolve: -> ::Array[AuthOption]
+  end
+end

data/sig/lib/hearth/api_error.rbs

@@ -0,0 +1,13 @@
+module Hearth
+  class ApiError < StandardError
+    def initialize: (error_code: String, ?metadata: Hash[Symbol, untyped], ?message: String?) -> void
+
+    attr_reader error_code: String
+
+    attr_reader metadata: Hash[Symbol, untyped]
+
+    def retryable?: () -> false
+
+    def throttling?: () -> false
+  end
+end

data/sig/lib/hearth/auth_option.rbs

@@ -0,0 +1,11 @@
+module Hearth
+  class AuthOption
+    def initialize: (scheme_id: String, ?identity_properties: Hash[Symbol, untyped], ?signer_properties: Hash[Symbol, untyped]) -> void
+
+    attr_reader scheme_id: String
+
+    attr_reader identity_properties: Hash[Symbol, untyped]
+
+    attr_reader signer_properties: Hash[Symbol, untyped]
+  end
+end

data/sig/lib/hearth/auth_schemes/anonymous.rbs

@@ -0,0 +1,7 @@
+module Hearth
+  module AuthSchemes
+    class Anonymous < AuthSchemes::Base
+      def initialize: () -> void
+    end
+  end
+end

data/sig/lib/hearth/auth_schemes/http_api_key.rbs

@@ -0,0 +1,7 @@
+module Hearth
+  module AuthSchemes
+    class HTTPApiKey < AuthSchemes::Base
+      def initialize: () -> void
+    end
+  end
+end

data/sig/lib/hearth/auth_schemes/http_basic.rbs

@@ -0,0 +1,7 @@
+module Hearth
+  module AuthSchemes
+    class HTTPBasic < AuthSchemes::Base
+      def initialize: () -> void
+    end
+  end
+end

data/sig/lib/hearth/auth_schemes/http_bearer.rbs

@@ -0,0 +1,7 @@
+module Hearth
+  module AuthSchemes
+    class HTTPBearer < AuthSchemes::Base
+      def initialize: () -> void
+    end
+  end
+end

data/sig/lib/hearth/auth_schemes/http_digest.rbs

@@ -0,0 +1,7 @@
+module Hearth
+  module AuthSchemes
+    class HTTPDigest < AuthSchemes::Base
+      def initialize: () -> void
+    end
+  end
+end

data/sig/lib/hearth/auth_schemes.rbs

@@ -0,0 +1,13 @@
+module Hearth
+  module AuthSchemes
+    class Base
+      def initialize: (scheme_id: String, signer: Signers::Base, identity_type: Class) -> void
+
+      attr_reader scheme_id: String
+
+      def identity_provider: (?Hash[Symbol, IdentityProvider] identity_providers) -> IdentityProvider
+
+      attr_reader signer: Signers::Base
+    end
+  end
+end

data/sig/lib/hearth/block_io.rbs

@@ -0,0 +1,9 @@
+module Hearth
+  class BlockIO
+    def initialize: (Proc block) -> void
+
+    attr_reader bytes_yielded: Integer
+
+    def write: (String data) -> Integer
+  end
+end

data/sig/lib/hearth/client.rbs

@@ -0,0 +1,9 @@
+module Hearth
+  class Client
+    def initialize: (Hash[Symbol, untyped], Class) -> void
+
+    attr_reader config: untyped
+
+    def self.plugins: () -> PluginList[untyped]
+  end
+end

data/sig/lib/hearth/client_stubs.rbs

@@ -0,0 +1,5 @@
+module Hearth
+  module ClientStubs
+    def stub_responses: (Symbol operation_name, *stub stubs) -> void
+  end
+end

data/sig/lib/hearth/configuration.rbs

@@ -0,0 +1,7 @@
+module Hearth
+  module Configuration[ServiceConfig]
+    def initialize: (**Hash[Symbol, untyped] options) -> void
+
+    def merge: (Hash[Symbol, untyped] configuration) -> ServiceConfig
+  end
+end

data/sig/lib/hearth/dns/host_address.rbs

@@ -0,0 +1,11 @@
+module Hearth
+  module DNS
+    class HostAddress < Struct[untyped]
+      attr_reader address_type: Symbol
+
+      attr_reader address: String
+
+      attr_reader hostname: String
+    end
+  end
+end

data/sig/lib/hearth/dns/host_resolver.rbs

@@ -0,0 +1,19 @@
+module Hearth
+  module DNS
+    class HostResolver
+      def initialize: (?service: Integer, ?family: Integer?, ?socktype: Symbol, ?protocol: Integer?, ?flags: Integer?) -> void
+
+      attr_reader service: Integer
+
+      attr_reader family: Integer?
+
+      attr_reader socktype: Symbol
+
+      attr_reader protocol: Integer?
+
+      attr_reader flags: Integer?
+
+      def resolve_address: (nodename: String, ?service: Integer, ?family: Integer?, ?socktype: Symbol, ?protocol: Integer?, ?flags: Integer?) -> Array[HostAddress]
+    end
+  end
+end