HTTP Client

The HTTP client is a class that handles transmission of a Request object over the network and populates a Response object.

Usage

Hearth provides a default HTTP client implemented using Ruby's Net::HTTP. The HTTP client takes many options related to wire trace output, various timeouts, SSL verify, certificate authorities, DNS host resolving options, etc. The default HTTP client also uses a connection pool to re-use existing and known good connections.

http_client = Hearth::HTTP::Client.new(read_timeout: 1, debug_output: true)
# => #<Hearth::HTTP ... >

client = HighScoreService::Client.new(
  endpoint: 'http://127.0.0.1:3000',
  http_client: http_client
)
# => #<HighScoreService ... >

client.list_high_scores
# <Uses HTTP client with wire trace logging to send>
# GET /high_scores ...
# => #<Hearth::Output @data=... >

DNS

The HTTP client has a hook for DNS resolution using the :host_resolver option. A host resolver is any class that responds to resolve_address(nodename:) where nodename is the domain name to resolve. The method must return a list of two Hearth::HostAddress objects, one containing an IPv6 address and one containing an IPv4 address. The default implementation of the host resolver uses Ruby's Addrinfo.getaddrinfo method.

Custom HTTP client

A custom implemented HTTP client can be provided as long as it implements a transmit(request:, response:, logger: nil) method. Implementations can use whatever transport library it would like, such as raw sockets, curb, Faraday, etc. The method must populate the Response object with headers, body, status, etc. If a networking issue occurs, a Hearth::NetworkingError should be raised.