honeyryder

Dns Resolvers

The DNS resolver is a building block which the user can switch.

httpx ships with the following resolvers:

  • :native: pure ruby resolver (default).
  • :system: uses Addrinfo.getaddrinfo to perform DNS queries.
  • :https: DNS over HTTPS (DoH) resolver.

You can switch from DNS resolver by passing it as an option:

HTTPX.with(resolver_class: :https).get(....

or set the default via the HTTPX_RESOLVER environment variable (ex: HTTPX_RESOLVER=https).

You can also pass additional DNS resolver options by using :resolver_options:

HTTPX.with(resolver_class: :https, resolver_options: {uri: "https://cloudflare-dns.com/dns-query", ...)

Native Resolver

The native resolver is a custom pure ruby DNS resolver implementation deeply integrated with httpx. It essentially delivers the same functionality as getaddrinfo without the drawbacks (no socket handler for IO operations, no support for timeouts, sorting applied by default…)

As extra :resolver_options, you can pass the same ones used for the ruby Resolv::DNS initializer (hint: check the options available for your ruby version), along with:

  • :socket_type: (:udp by default) type of socket used to send DNS queries to the nameservers (also accepts :tcp).

System Resolver

This system resolver uses Addrinfo.getaddrinfo to perform the DNS queries. It integrates with the IO loop by running the resolution call in a background thread and notifying the loop asynchronously.

(Prior to 0.19.0, the resolv library is used (via Resolv.getaddresses). The resolution is blocking and therefore doesn’t integrate in a performant way. However, it’s a stable API, and in case that the native resolver needs some tweaks, one can always fall back to it).

HTTPS Resolver

The https resolver uses the same internal HTTP stack as the requests to perform DNS resolution following the DoH spec.

As extra :resolver_options, you can pass the following:

  • uri: the DoH-enabled URI where to send the query (default: https://1.1.1.1/dns-query);
  • use_get: whether to use GET instead of POST for DoH requests (default: false);

(It requires HTTP/2 support, so make sure that your ruby-openssl dependency supports ALPN negotiation.)

Happy Eyeballs v2

Starting from version 0.19.0, DNS uses the happy eyeballs v2 algorithm to perform DNS resolution on multi-homed dual-stack (IPv6 / IPv4) networks. This means that, whenever possible, preference will be given to IPv6 connections, depending on availability and overall resolution performance.

Next: TLS