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 DNS resolvers by passing it as an option:

HTTPX.with(resolver_class: :https).get("https://example.com")

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 practically the same functionality as getaddrinfo without the drawbacks (examples of which are, 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, which it automatically falls back to in the large request TCP fallback scenario).

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.

getaddrinfo is a notoriously hard-to-integrate API for the kind of scenarios httpx supports. However, it’s a stable and widely available API, and easy to fall back to.

HTTPS Resolver

The https resolver uses the same internal httpx 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);

Happy Eyeballs v2

All options above are supported in the happy eyeballs v2 algorithm in multi-homed dual-stack (IPv6 / IPv4) networks. This means that, preference will be given to the fastest option to query and connect to (with a slight preference to IPv6 connections).

Next: TLS