hearth 1.0.0.pre2 → 1.0.0.pre3

data/lib/hearth/stubs.rb

@@ -3,19 +3,27 @@
 module Hearth
   # Provides a thread safe data structure for adding and getting stubs
   # per operation.
-  # @api private
   class Stubs
-    def initialize
-      @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
 
-    def add_stubs(operation_name, stubs)
+    # 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] || []

data/lib/hearth/time_helper.rb

@@ -21,8 +21,7 @@ module Hearth
       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

data/lib/hearth/validator.rb

@@ -7,17 +7,34 @@ module Hearth
   # * Raise errors with context when validation fails.
   # @api private
   module Validator
-    # Validate the given value is of the given type(s).
+    # Validate the given value is within the expected range (inclusive).
     # @param value [Object] The value to validate.
-    # @param types [Array<Class>] The types to validate against.
+    # @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 one of given type(s).
-    def self.validate_types!(value, *types, context:)
-      return if value.nil? || types.any? { |type| value.is_a?(type) }
+    # @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 in " \
-            "[#{types.map(&:to_s).join(', ')}], got #{value.class}."
+            "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.
@@ -28,6 +45,19 @@ module Hearth
       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_types!(value, *types, context:)
+      return if value.nil? || types.any? { |type| value.is_a?(type) }
+
+      raise ArgumentError,
+            "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.
@@ -41,19 +71,5 @@ module Hearth
       raise ArgumentError,
             "Unexpected members: [#{unknown.join(', ')}]"
     end
-
-    # 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
   end
 end

data/lib/hearth/waiters/poller.rb

@@ -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,7 +39,7 @@ 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_interceptor)
@@ -81,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

@@ -68,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/node.rb

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

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

@@ -6,10 +6,11 @@ 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_stubs'
+require_relative 'hearth/client'
 require_relative 'hearth/configuration'
 require_relative 'hearth/config/env_provider'
 require_relative 'hearth/config/resolver'
@@ -23,8 +24,12 @@ 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_resolver'
+require_relative 'hearth/identity_provider'
 require_relative 'hearth/interceptor'
 require_relative 'hearth/interceptors'
 require_relative 'hearth/interceptor_context'
@@ -36,10 +41,9 @@ require_relative 'hearth/number_helper'
 require_relative 'hearth/output'
 require_relative 'hearth/query/param'
 require_relative 'hearth/query/param_list'
-require_relative 'hearth/refreshing_identity_resolver'
+require_relative 'hearth/refreshing_identity_provider'
 require_relative 'hearth/retry'
 require_relative 'hearth/signers'
-require_relative 'hearth/structure'
 require_relative 'hearth/stubs'
 require_relative 'hearth/time_helper'
 require_relative 'hearth/union'

data/sig/lib/hearth/aliases.rbs

@@ -1,4 +1,6 @@
-type document = Hash[Symbol,document] | Array[document] | String | bool | Numeric
+module Hearth
+  type document = Hash[Symbol, document] | Array[document] | String | bool | Numeric
 
-type stub = Hearth::Structure | Hearth::Response | { data: Hash[Symbol, untyped] } |
-  { error: { class: Class, data: Hash[Symbol, untyped] } } | Hearth::ApiError | Proc
+  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/auth_schemes.rbs

@@ -5,7 +5,7 @@ module Hearth
 
       attr_reader scheme_id: String
 
-      def identity_resolver: (?Hash[Symbol, IdentityResolver] identity_resolvers) -> IdentityResolver
+      def identity_provider: (?Hash[Symbol, IdentityProvider] identity_providers) -> IdentityProvider
 
       attr_reader signer: Signers::Base
     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/configuration.rbs

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

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

@@ -1,8 +1,6 @@
 module Hearth
   module DNS
-    class HostAddress
-      def initialize: (address_type: Symbol, address: String, hostname: String) -> void
-
+    class HostAddress < Struct[untyped]
       attr_reader address_type: Symbol
 
       attr_reader address: String

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

@@ -5,13 +5,13 @@ module Hearth
 
       attr_reader service: Integer
 
-      attr_reader family: Integer
+      attr_reader family: Integer?
 
       attr_reader socktype: Symbol
 
-      attr_reader protocol: Integer
+      attr_reader protocol: Integer?
 
-      attr_reader flags: Integer
+      attr_reader flags: Integer?
 
       def resolve_address: (nodename: String, ?service: Integer, ?family: Integer?, ?socktype: Symbol, ?protocol: Integer?, ?flags: Integer?) -> Array[HostAddress]
     end

data/sig/lib/hearth/endpoint_rules.rbs

@@ -0,0 +1,17 @@
+module Hearth
+  module EndpointRules
+    class AuthScheme < Struct[untyped]
+      attr_accessor scheme_id: String
+
+      attr_accessor properties: Hash[String, untyped]
+    end
+
+    class Endpoint < Struct[untyped]
+      attr_accessor uri: String
+
+      attr_accessor auth_schemes: Array[AuthScheme]
+
+      attr_accessor headers: Hash[String, String | Array[String]]
+    end
+  end
+end

data/sig/lib/hearth/http/field.rbs

@@ -1,7 +1,7 @@
 module Hearth
   module HTTP
     class Field
-      def initialize: (String name, ?(Array[String] | _ToS)? value, ?kind: Symbol) -> void
+      def initialize: (String name, ?(_ToS)? value, ?kind: Symbol) -> void
 
       attr_reader name: String
 

data/sig/lib/hearth/http/fields.rbs

@@ -28,7 +28,7 @@ module Hearth
 
         def []: (String key) -> (String | nil)
 
-        def []=: (String, String) -> String
+        def []=: (String, String) -> Field
 
         def key?: (String) -> bool
 

data/sig/lib/hearth/http/header_list_builder.rbs

@@ -0,0 +1,15 @@
+module Hearth
+  module HTTP
+    module HeaderListBuilder
+      def self.build_list: (Array[untyped] value) -> String
+
+      def self.build_string_list: (Array[String] value ) -> String
+
+      def self.build_http_date_list: (Array[Time] value) -> String
+
+      def self.build_date_time_list: (Array[Time] value) -> String
+
+      def self.build_epoch_seconds_list: (Array[Time] value) -> String
+    end
+  end
+end

data/sig/lib/hearth/http/header_list_parser.rbs

@@ -0,0 +1,19 @@
+module Hearth
+  module HTTP
+    module HeaderListParser
+      def self.parse_boolean_list: (String value) -> Array[bool]
+
+      def self.parse_integer_list: (String value) -> Array[Integer]
+
+      def self.parse_float_list: (String value) -> Array[Float]
+
+      def self.build_string_list: (String value ) -> Array[String]
+
+      def self.build_http_date_list: (String value ) -> Array[Time]
+
+      def self.build_date_time_list: (String value ) -> Array[Time]
+
+      def self.build_epoch_seconds_list: (String value ) -> Array[Time]
+    end
+  end
+end

data/sig/lib/hearth/http/networking_error.rbs

@@ -0,0 +1,6 @@
+module Hearth
+  module HTTP
+    class NetworkingError < Hearth::NetworkingError
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 module Hearth
   module HTTP
     class Response < Hearth::Response
-      def initialize: (?status: Integer, ?reason: String?, ?fields: Fields, ?body: IO) -> void
+      def initialize: (?status: Integer, ?reason: String?, ?fields: Fields, ?body:  _WritableIO) -> void
 
       attr_accessor status: Integer
 

data/sig/lib/hearth/identities.rbs

@@ -3,7 +3,7 @@ module Hearth
     class Base
       def initialize: (?expiration: Time?) -> void
 
-      attr_reader expiration: Time
+      attr_reader expiration: Time?
     end
   end
 end

data/sig/lib/hearth/{identity_resolver.rbs → identity_provider.rbs}

@@ -1,5 +1,5 @@
 module Hearth
-  class IdentityResolver
+  class IdentityProvider
     def initialize: (Proc) -> void
 
     def identity: (?Hash[Symbol, untyped] properties) -> Identities::Base

data/sig/lib/hearth/interceptor_context.rbs

@@ -1,6 +1,6 @@
 module Hearth
   class InterceptorContext
-    def initialize: (input: Structure, request: Request, response: Response, output: Structure, ?attributes: Hash[Symbol, untyped]) -> void
+    def initialize: (input: Structure, request: Request, response: Response, output: Output[Structure], logger: Logger) -> void
 
     attr_reader input: Structure
 
@@ -8,7 +8,9 @@ module Hearth
 
     attr_reader response: Response
 
-    attr_reader output: Structure
+    attr_reader output: Output[Structure]
+
+    attr_reader logger: Logger
 
     attr_reader attributes: Hash[Symbol, untyped]
   end

data/sig/lib/hearth/interfaces.rbs

@@ -10,56 +10,78 @@ end
 class Logger
 end
 
-interface _Plugin
-  def call: (Hearth::Configuration) -> void
-end
+module Hearth
+  interface _Plugin[ServiceConfig]
+    def call: (ServiceConfig) -> void
+  end
 
-interface _Interceptor
-  def read_before_execution: (Hearth::InterceptorContext) -> void
+  interface _Interceptor
+    def read_before_execution: (InterceptorContext) -> void
 
-  def modify_before_serialization: (Hearth::InterceptorContext) -> void
+    def modify_before_serialization: (InterceptorContext) -> void
 
-  def read_before_serialization: (Hearth::InterceptorContext) -> void
+    def read_before_serialization: (InterceptorContext) -> void
 
-  def read_after_serialization: (Hearth::InterceptorContext) -> void
+    def read_after_serialization: (InterceptorContext) -> void
 
-  def modify_before_retry_loop: (Hearth::InterceptorContext) -> void
+    def modify_before_retry_loop: (InterceptorContext) -> void
 
-  def read_before_attempt: (Hearth::InterceptorContext) -> void
+    def read_before_attempt: (InterceptorContext) -> void
 
-  def modify_before_signing: (Hearth::InterceptorContext) -> void
+    def modify_before_signing: (InterceptorContext) -> void
 
-  def read_before_signing: (Hearth::InterceptorContext) -> void
+    def read_before_signing: (InterceptorContext) -> void
 
-  def read_after_signing: (Hearth::InterceptorContext) -> void
+    def read_after_signing: (InterceptorContext) -> void
 
-  def modify_before_transmit: (Hearth::InterceptorContext) -> void
+    def modify_before_transmit: (InterceptorContext) -> void
 
-  def read_before_transmit: (Hearth::InterceptorContext) -> void
+    def read_before_transmit: (InterceptorContext) -> void
 
-  def read_after_transmit: (Hearth::InterceptorContext) -> void
+    def read_after_transmit: (InterceptorContext) -> void
 
-  def modify_before_deserialization: (Hearth::InterceptorContext) -> void
+    def modify_before_deserialization: (InterceptorContext) -> void
 
-  def read_before_deserialization: (Hearth::InterceptorContext) -> void
+    def read_before_deserialization: (InterceptorContext) -> void
 
-  def read_after_deserialization: (Hearth::InterceptorContext) -> void
+    def read_after_deserialization: (InterceptorContext) -> void
 
-  def modify_before_attempt_completion: (Hearth::InterceptorContext) -> void
+    def modify_before_attempt_completion: (InterceptorContext) -> void
 
-  def read_after_attempt: (Hearth::InterceptorContext) -> void
+    def read_after_attempt: (InterceptorContext) -> void
 
-  def modify_before_completion: (Hearth::InterceptorContext) -> void
+    def modify_before_completion: (InterceptorContext) -> void
 
-  def read_after_execution: (Hearth::InterceptorContext) -> void
-end
+    def read_after_execution: (InterceptorContext) -> void
+  end
+
+  interface _ErrorInspector
+    def initialize: (ApiError, Response) -> void
+
+    def retryable?: () -> bool
+
+    def error_type: () -> String
 
-interface _ErrorInspector
-  def initialize: (Hearth::ApiError, Hearth::Response) -> void
+    def hints: () -> Hash[Symbol, untyped]
+  end
 
-  def retryable?: () -> bool
+  interface _RetryStrategy
+    def acquire_initial_retry_token: (?String? _token_scope) -> Retry::Token
 
-  def error_type: () -> String
+    def refresh_retry_token: (Retry::Token _retry_token, _ErrorInspector _error_info) -> Retry::Token?
 
-  def hints: () -> Hash[Symbol, untyped]
-end
+    def record_success: (Retry::Token _retry_token) -> Retry::Token
+  end
+
+  interface _AuthResolver[Params]
+    def resolve: (Params) -> AuthSchemes::Base
+  end
+
+  interface _EndpointResolver[Params]
+    def resolve: (Params) -> EndpointRules::Endpoint
+  end
+
+  interface _WritableIO
+    def write: (*_ToS) -> Integer
+  end
+end

data/sig/lib/hearth/json/parse_error.rbs

@@ -0,0 +1,9 @@
+module Hearth
+  module JSON
+    class ParseError < StandardError
+      def initialize: (StandardError original_error) -> void
+
+      attr_reader original_error: StandardError
+    end
+  end
+end

data/sig/lib/hearth/networking_error.rbs

@@ -0,0 +1,7 @@
+module Hearth
+    class NetworkingError < StandardError
+      def initialize: (StandardError original_error) -> void
+
+      attr_reader original_error: StandardError
+    end
+end

data/sig/lib/hearth/output.rbs

@@ -1,10 +1,10 @@
 module Hearth
-  class Output
-    def initialize: (?error: (ApiError)?, ?data: (Structure)?, ?metadata: Hash[Symbol, untyped]) -> void
+  class Output[DATA]
+    def initialize: (?error: ApiError?, ?data: Structure?, ?metadata: Hash[Symbol, untyped]) -> void
 
-    attr_accessor error: (ApiError | nil)
+    attr_accessor error: ApiError?
 
-    attr_accessor data: (Structure | nil)
+    attr_accessor data: DATA?
 
     attr_accessor metadata: Hash[Symbol, untyped]
   end

data/sig/lib/hearth/plugin_list.rbs

@@ -1,15 +1,13 @@
 module Hearth
-  class PluginList
-    def initialize: (?Array[_Plugin] plugins) -> void
+  class PluginList[ServiceConfig]
+    def initialize: (?Array[_Plugin[ServiceConfig]] plugins) -> void
 
-    def add: (_Plugin plugin) -> void
+    def add: (_Plugin[ServiceConfig] plugin) -> void
 
     alias << add
 
-    def apply: (Hearth::Configuration) -> void
+    def apply: (ServiceConfig) -> void
 
-    def dup: () -> PluginList
-
-    def each: () ?{ (_Plugin) -> void } -> void
+    def each: () ?{ (_Plugin[ServiceConfig]) -> void } -> void
   end
 end

data/sig/lib/hearth/query/param.rbs

@@ -5,13 +5,13 @@ module Hearth
 
       attr_reader name: String
 
-      attr_reader value: (String | Array[String])
+      attr_reader value: (String | Array[String])?
 
       def to_s: () -> String
 
       def ==: (Param other) -> bool
 
-      def <=>: (Param other) -> bool
+      def <=>: (Param other) -> Integer
     end
   end
 end

data/sig/lib/hearth/refreshing_identity_provider.rbs

@@ -0,0 +1,10 @@
+module Hearth
+  module RefreshingIdentityProvider
+    ASYNC_EXPIRATION_LENGTH: Integer
+    SYNC_EXPIRATION_LENGTH: Integer
+
+    def initialize: -> void
+
+    def identity: (?Hash[Symbol, untyped] properties) -> Identities::Base
+  end
+end

data/sig/lib/hearth/request.rbs

@@ -1,9 +1,9 @@
 module Hearth
   class Request
-    def initialize: (?uri: URI, ?body: IO) -> void
+    def initialize: (?uri: URI, ?body: (IO | StringIO)) -> void
 
     attr_accessor uri: URI
 
-    attr_accessor body: IO
+    attr_accessor body: (IO | StringIO)
   end
 end