DNS

Bun implements its own dns module and the node:dns module.

import * as dns from "node:dns";

const addrs = await dns.promises.resolve4("bun.com", { ttl: true });
console.log(addrs);
// => [{ address: "172.67.161.226", ttl: 0 }, ...]

import { dns } from "bun";

dns.prefetch("bun.com", 443);

Choosing a resolver backend#

Bun.dns.lookup() accepts a backend option that selects the resolver implementation:

• "c-ares": the c-ares asynchronous resolver. It reads /etc/resolv.conf directly, so it does not consult NSS modules such as systemd-resolved. This backend is the default for Bun.dns.lookup() on Linux.
• "system": the platform's own resolver (the non-blocking system API on macOS, getaddrinfo on a thread pool everywhere else). This backend is the default on macOS, Windows, and Android.
• "getaddrinfo" (alias "libc"): the POSIX getaddrinfo(3) function on a thread pool.

import { dns } from "bun";

const [{ address }] = await dns.lookup("example.com", { backend: "system" });

node:dns.lookup() always uses the "system" backend to match Node.js, whose dns.lookup() is documented as calling getaddrinfo(3). The node:dns.resolve*() functions use c-ares, as they do in Node.js.

DNS caching in Bun#

Bun caches DNS lookups, which makes repeated connections to the same hosts faster.

The cache holds up to 256 entries for a maximum of 30 seconds each. If a connection to a host fails, Bun removes that host's entry from the cache. Simultaneous connections to the same host share one DNS lookup.

Bun uses this cache automatically in:

• bun install
• fetch()
• node:http (client)
• Bun.connect
• node:net
• node:tls

When should I prefetch a DNS entry?#

Web browsers expose <link rel="dns-prefetch"> to resolve a hostname before it's needed. In Bun, dns.prefetch does the same thing: use it when you know you'll connect to a host soon and want to avoid the initial DNS lookup.

import { dns } from "bun";

dns.prefetch("my.database-host.com", 5432);

A database driver is a good example: prefetch the database host's DNS entry when your application starts. By the time the rest of the application has loaded, the lookup may already be complete.

dns.prefetch#

dns.prefetch resolves a hostname before you need it.

dns.prefetch(hostname: string, port?: number): void;

Here's an example:

import { dns } from "bun";

dns.prefetch("bun.com", 443);
//
// ... sometime later ...
await fetch("https://bun.com");

dns.getCacheStats()#

dns.getCacheStats() returns the current cache stats as an object with the following properties:

{
  cacheHitsCompleted: number; // Cache hits completed
  cacheHitsInflight: number; // Cache hits in flight
  cacheMisses: number; // Cache misses
  size: number; // Number of items in the DNS cache
  errors: number; // Number of times a connection failed
  totalCount: number; // Number of times a connection was requested at all (including cache hits and misses)
}

Example:

import { dns } from "bun";

const stats = dns.getCacheStats();
console.log(stats);
// => { cacheHitsCompleted: 0, cacheHitsInflight: 0, cacheMisses: 0, size: 0, errors: 0, totalCount: 0 }

Configuring DNS cache TTL#

Bun caches DNS entries for 30 seconds by default. To change the TTL, set the $BUN_CONFIG_DNS_TIME_TO_LIVE_SECONDS environment variable. For example, to set it to 5 seconds:

BUN_CONFIG_DNS_TIME_TO_LIVE_SECONDS=5 bun run my-script.ts

Why is 30 seconds the default?#

The system API underneath (getaddrinfo) does not expose the TTL of a DNS entry, so Bun has to pick a number. We chose 30 seconds because it's long enough to see the benefits of caching and short enough to be unlikely to cause issues if a DNS entry changes. Amazon Web Services recommends 5 seconds for the Java Virtual Machine, though the JVM's default is to cache indefinitely.