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