honeyryder

Dns Resolvers

The DNS resolver is a building block which the user can switch, or even enhance.

httpx ships with the following resolvers:

  • native: pure ruby resolver (which integrates with internal IO loop).
  • system: uses getaddrinfo to perform DNS queries.
  • https: DNS over HTTPS (DoH) resolver.

By default it uses the native resolver. You can switch your DNS resolver by passing it as an option:

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

or set HTTPX_RESOLVER environment variable in your environment to one of the possible values (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 DNS resolver implementation integrated with the IO loop (it still uses the ruby resolv library to build the DNS packets). This way, DNS requests can also run concurrently in the same flow as the HTTP requests, and the former will not slow down the latter.

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).

System Resolver

This system resolver uses 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 dual-stack (IPv6 / IPv4) enabled systems. This means that, whenever possible, preference will be given to IPv6 connections, depending on availability and overall resolution performance.

(Prior to 0.19.0, IPv4 resolution is the privileged IP family, and IPv6 is the fallback.)

Next: TLS