/**
* Node.js implementation of Effect's `Dns` service.
*
* Address lookups use the operating system resolver through `dns.lookup`,
* including the hosts file. Record queries and reverse lookups share one
* `dns.Resolver`. Interruption discards a query's result but cannot cancel
* that query; closing the scope cancels all pending queries.
*
* Unrepresentable records, such as invalid `Host.DomainName` values, are
* skipped. If every record is skipped, the query fails with `InvalidResponse`.
* `make` decodes Node.js's Latin-1 TXT and CAA strings as UTF-8. TLSA queries
* need Node.js 22.15 or 23.9 and later, and fail with `Unsupported` on runtimes
* without `resolveTlsa`. Other runtimes reuse `lookup`, `resolver`, and the
* conversion helpers to build their services.
*
* @stability experimental
* @since 4.0.0
*/
import * as Arr from "effect/Array"
import * as Config from "effect/Config"
import * as Duration from "effect/Duration"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"
import * as Dns from "effect/net/Dns"
import * as Host from "effect/net/Host"
import * as NetAddress from "effect/net/NetAddress"
import * as Result from "effect/Result"
import * as NodeDns from "node:dns"
/**
* Options for the Node.js `Dns` service and `resolver`.
*
* **Details**
*
* `nameServers` replaces the system name servers, which are converted like
* `Dns.nameServerFromInput`, and an empty list keeps the system name servers.
* `timeout` is the time allowed for each attempt and `tries` the number of
* attempts per name server. Address lookups always use the operating system
* resolver and are not affected.
*
* `timeout` is rounded up to whole milliseconds and `tries` down to a whole
* number, and both are clamped to 1 through 2^31 - 1, so `Duration.infinity`
* uses the longest timeout the resolver supports.
*
* **Gotchas**
*
* Invalid name servers fail with a `NetAddress.NetAddressError` when the
* service is created, and so do IPv6 name servers with a scope ID, such as
* link-local addresses, because the resolver drops the scope.
*
* @stability experimental
* @category models
* @since 4.0.0
*/
export interface Options {
readonly nameServers?: ReadonlyArray<NetAddress.IpAddressInput | NetAddress.InetAddressInput> | undefined
readonly timeout?: Duration.Input | undefined
readonly tries?: number | undefined
}
const reasons: Record<string, Dns.DnsErrorReason> = {
ENOTFOUND: "NotFound",
ENODATA: "NotFound",
ETIMEOUT: "Timeout",
// `getaddrinfo` reports SERVFAIL answers as `EAI_AGAIN`, and REFUSED,
// FORMERR, and NOTIMP answers alike as `EAI_FAIL`.
EAI_AGAIN: "Temporary",
EAI_FAIL: "Refused",
ESERVFAIL: "ServerFailure",
EREFUSED: "Refused",
ECONNREFUSED: "Refused",
EBADNAME: "BadName",
ENONAME: "BadName",
EBADFAMILY: "BadName",
EBADQUERY: "BadName",
EFORMERR: "InvalidResponse",
EBADRESP: "InvalidResponse",
ENOTIMP: "Unsupported"
}
/**
* Converts a failure of `node:dns` or of Bun's DNS functions to a
* `Dns.DnsError`, choosing the reason from the error's `code`.
*
* **Details**
*
* Bun prefixes c-ares codes with `DNS_`, such as `DNS_ENOTFOUND`; the prefix is
* ignored. Errors without a known code get the reason `Unknown`.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const dnsErrorFromCause = (
cause: unknown,
method: Dns.DnsError["method"],
hostname: string,
recordType?: Dns.RecordType
): Dns.DnsError => {
const code = typeof cause === "object" && cause !== null && "code" in cause
? String(cause.code).replace(/^DNS_/, "")
: undefined
return new Dns.DnsError({
reason: (code !== undefined ? reasons[code] : undefined) ?? "Unknown",
method,
hostname,
recordType,
cause
})
}
// c-ares omits the root dot and represents the root name as an empty string.
const absoluteName = (name: string): string => {
if (name.endsWith(".")) {
let backslashes = 0
for (let i = name.length - 2; i >= 0 && name[i] === "\\"; i--) {
backslashes++
}
if (backslashes % 2 === 0) return name
}
return `${name}.`
}
/**
* Converts a name returned by a resolver to a fully qualified
* `Host.DomainName`, throwing when it is not a valid domain name.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const domainNameFromResolverUnsafe = (name: string): Host.DomainName =>
Host.domainNameFromStringUnsafe(absoluteName(name))
const decoder = new TextDecoder()
const encoder = new TextEncoder()
const nameParts = /\\(\d{3})|\\(.)|[^\\]+|\\/gsu
/**
* Converts a name returned by a resolver to fully qualified text, for names
* that need not be host names, such as PTR targets and SOA mailboxes.
*
* **Details**
*
* Resolvers write bytes as `\DDD` escapes, c-ares in decimal (`radix` 10) and
* `Deno.resolveDns` in octal (`radix` 8), and escape special characters with
* a backslash, such as `\.` for a dot inside a label or `\(` for a
* parenthesis. Decoding the bytes as UTF-8 and removing the escapes gives the
* text of the name, keeping only the `\.` and `\\` escapes.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const nameTextFromResolver = (name: string, radix: 8 | 10 = 10): string => {
if (!name.includes("\\")) return absoluteName(name)
const bytes: Array<number> = []
for (const [part, digits, escaped] of name.matchAll(nameParts)) {
if (digits !== undefined) {
const byte = Number.parseInt(digits, radix)
if (byte === 46 || byte === 92) bytes.push(92)
bytes.push(byte)
} else if (escaped !== undefined) {
if (escaped === "." || escaped === "\\") bytes.push(92)
bytes.push(...encoder.encode(escaped))
} else {
bytes.push(...encoder.encode(part))
}
}
return absoluteName(decoder.decode(Uint8Array.from(bytes)))
}
/**
* Converts a number of seconds that a resolver reports as a signed 32-bit
* integer, such as the SOA refresh, retry, and expire intervals, to a
* `Duration`.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const secondsFromInt32 = (value: number): Duration.Duration => Duration.seconds(value >>> 0)
/**
* Decodes a string that holds one byte per character as UTF-8.
*
* **Details**
*
* Node.js and `Deno.resolveDns` decode each byte of TXT and CAA character
* strings as one Latin-1 character; decoding the bytes as UTF-8 matches other
* runtimes. Strings with only ASCII characters are returned unchanged.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const utf8FromLatin1 = (value: string): string =>
// oxlint-disable-next-line no-control-regex
/[^\x00-\x7f]/.test(value) ? decoder.decode(Uint8Array.from(value, (character) => character.charCodeAt(0))) : value
/**
* Converts the entries of a resolver's answer to a query for `name` to records
* of a record type, skipping entries whose data cannot be represented, such as
* names that are not valid `Host.DomainName` values.
*
* **Details**
*
* When the answer has entries but every one is skipped, the conversion fails
* with an `InvalidResponse` error whose cause is the first entry's failure,
* rather than returning no records, which would be reported as `NotFound`.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const recordsFromResolver = <T extends Dns.RecordType, A>(
name: string,
type: T,
entries: ReadonlyArray<A>,
fields: (entry: A) => Dns.RecordFields<T>
): Result.Result<Array<Dns.RecordFor<T>>, Dns.DnsError> => {
const records: Array<Dns.RecordFor<T>> = []
let skipped: { readonly failure: unknown } | undefined
for (const entry of entries) {
const result = Result.try(() => Dns.makeRecordUnsafe(type, fields(entry)))
if (Result.isSuccess(result)) {
records.push(result.success)
} else {
skipped ??= result
}
}
return records.length === 0 && skipped !== undefined
? Result.fail(
new Dns.DnsError({
reason: "InvalidResponse",
method: "resolve",
hostname: name,
recordType: type,
cause: skipped.failure
})
)
: Result.succeed(records)
}
const queries: {
readonly [K in Dns.RecordType]: (
resolver: NodeDns.promises.Resolver,
name: string
) => Promise<Result.Result<Array<Dns.DnsRecord>, Dns.DnsError>>
} = {
A: async (resolver, name) =>
recordsFromResolver(name, "A", await resolver.resolve4(name), (address) => ({
address: NetAddress.ipFromStringUnsafe(address) as NetAddress.Ipv4Address
})),
AAAA: async (resolver, name) =>
recordsFromResolver(name, "AAAA", await resolver.resolve6(name), (address) => ({
address: NetAddress.ipFromStringUnsafe(address) as NetAddress.Ipv6Address
})),
CAA: async (resolver, name) =>
recordsFromResolver(name, "CAA", await resolver.resolveCaa(name), (caa) => {
const tag = Object.keys(caa).find((key) => key !== "critical" && key !== "type")
if (tag === undefined) throw new Error("CAA record without a property tag")
// Only the issuer critical flag (bit 7) is defined; other flag bits are reserved.
return { critical: (caa.critical & 0x80) !== 0, tag, value: String((caa as any)[tag]) }
}),
CNAME: async (resolver, name) =>
recordsFromResolver(name, "CNAME", await resolver.resolveCname(name), (target) => ({
target: domainNameFromResolverUnsafe(target)
})),
MX: async (resolver, name) =>
recordsFromResolver(name, "MX", await resolver.resolveMx(name), (mx) => ({
exchange: domainNameFromResolverUnsafe(mx.exchange),
priority: mx.priority
})),
NAPTR: async (resolver, name) =>
recordsFromResolver(name, "NAPTR", await resolver.resolveNaptr(name), (naptr) => ({
order: naptr.order,
preference: naptr.preference,
flags: naptr.flags,
service: naptr.service,
regexp: naptr.regexp,
replacement: domainNameFromResolverUnsafe(naptr.replacement)
})),
NS: async (resolver, name) =>
recordsFromResolver(name, "NS", await resolver.resolveNs(name), (host) => ({
host: domainNameFromResolverUnsafe(host)
})),
PTR: async (resolver, name) =>
recordsFromResolver(name, "PTR", await resolver.resolvePtr(name), (host) => ({
host: nameTextFromResolver(host)
})),
SOA: async (resolver, name) =>
recordsFromResolver(name, "SOA", [await resolver.resolveSoa(name)], (soa) => ({
primary: domainNameFromResolverUnsafe(soa.nsname),
admin: nameTextFromResolver(soa.hostmaster),
serial: soa.serial,
refresh: secondsFromInt32(soa.refresh),
retry: secondsFromInt32(soa.retry),
expire: secondsFromInt32(soa.expire),
minimum: Duration.seconds(soa.minttl)
})),
SRV: async (resolver, name) =>
recordsFromResolver(name, "SRV", await resolver.resolveSrv(name), (srv) => ({
target: domainNameFromResolverUnsafe(srv.name),
port: srv.port,
priority: srv.priority,
weight: srv.weight
})),
// `resolveTlsa` was added in Node.js 22.15 and 23.9; Bun and Deno lack it.
TLSA: async (resolver, name) =>
typeof resolver.resolveTlsa === "function"
? recordsFromResolver(name, "TLSA", await resolver.resolveTlsa(name), (tlsa) => ({
certUsage: tlsa.certUsage,
selector: tlsa.selector,
matchingType: tlsa.match,
data: new Uint8Array(tlsa.data)
}))
: Result.fail(
new Dns.DnsError({ reason: "Unsupported", method: "resolve", hostname: name, recordType: "TLSA" })
),
TXT: async (resolver, name) =>
recordsFromResolver(name, "TXT", await resolver.resolveTxt(name), (chunks) => ({
chunks: chunks as unknown as Arr.NonEmptyReadonlyArray<string>
}))
}
/**
* Converts an IP family to the numeric family used by `dns.lookup`, with `0`
* for addresses of either family.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const toFamily = (family: NetAddress.IpFamily | undefined): 0 | 4 | 6 =>
family === "IPv4" ? 4 : family === "IPv6" ? 6 : 0
const stripZone = (address: string): string => {
const separator = address.indexOf("%")
return separator === -1 ? address : address.slice(0, separator)
}
/**
* Converts the entries returned by an address lookup, such as `dns.lookup`
* with `all: true`, to IP addresses, keeping their order.
*
* **Details**
*
* IPv6 zones are dropped, and addresses that cannot be parsed are skipped.
*
* @stability experimental
* @category converting
* @since 4.0.0
*/
export const addressesFromLookup = (
entries: ReadonlyArray<{ readonly address: string }>
): Array<NetAddress.IpAddress> =>
Arr.filterMap(entries, (entry) => Result.try(() => NetAddress.ipFromStringUnsafe(stripZone(entry.address))))
/**
* Looks up the addresses of a host name with `dns.lookup`, keeping the order
* returned by the operating system resolver.
*
* @stability experimental
* @category resolving
* @since 4.0.0
*/
export const lookup = (
host: string,
family?: NetAddress.IpFamily | undefined
): Effect.Effect<Array<NetAddress.IpAddress>, Dns.DnsError> =>
Effect.tryPromise({
// `verbatim` keeps the system order on Node versions without `order`.
try: () =>
NodeDns.promises.lookup(host, { all: true, family: toFamily(family), order: "verbatim", verbatim: true }),
catch: (cause) => dnsErrorFromCause(cause, "lookup", host)
}).pipe(Effect.map(addressesFromLookup))
// Clamp resolver options to positive signed 32-bit integers; NaN becomes 1.
const resolverInt = (value: number): number => value >= 1 ? Math.min(value, 2 ** 31 - 1) : 1
/**
* Creates a function that queries DNS records with the runtime's `node:dns`
* module.
*
* **Details**
*
* All queries share one `dns.Resolver`, which is cancelled when the scope
* closes. Names in records are fully qualified, and TXT and CAA character
* strings are returned as the runtime decodes them, without the UTF-8
* correction that `make` applies for Node.js. Records are converted with
* `recordsFromResolver`.
*
* @stability experimental
* @category constructors
* @since 4.0.0
*/
export const resolver = Effect.fnUntraced(function*(options?: Options) {
const resolverOptions: NodeDns.ResolverOptions = {
...(options?.timeout !== undefined && { timeout: resolverInt(Math.ceil(Duration.toMillis(options.timeout))) }),
...(options?.tries !== undefined && { tries: resolverInt(Math.floor(options.tries)) })
}
const nameServers: Array<NetAddress.InetAddress> = []
for (const input of options?.nameServers ?? []) {
const server = yield* Effect.fromResult(Dns.nameServerFromInput(input))
if (NetAddress.isInetAddressV6(server) && server.scopeId !== 0) {
return yield* new NetAddress.NetAddressError({
input,
message: "IPv6 name servers with a scope ID are not supported"
})
}
nameServers.push(server)
}
const resolver = yield* Effect.acquireRelease(
Effect.sync(() => {
const resolver = new NodeDns.promises.Resolver(resolverOptions)
if (nameServers.length > 0) {
resolver.setServers(
nameServers.map(NetAddress.formatInet)
)
}
return resolver
}),
(resolver) => Effect.sync(() => resolver.cancel())
)
return (name: string, type: Dns.RecordType): Effect.Effect<Array<Dns.DnsRecord>, Dns.DnsError> =>
Effect.tryPromise({
try: () => queries[type](resolver, name),
catch: (cause) => dnsErrorFromCause(cause, "resolve", name, type)
}).pipe(Effect.flatMap(Effect.fromResult))
})
const utf8Strings = (record: Dns.DnsRecord): Dns.DnsRecord => {
switch (record._tag) {
case "TXT":
return Dns.makeRecordUnsafe("TXT", {
chunks: Arr.map(record.chunks, utf8FromLatin1)
})
case "CAA":
return Dns.makeRecordUnsafe("CAA", {
critical: record.critical,
tag: record.tag,
value: utf8FromLatin1(record.value)
})
default:
return record
}
}
/**
* Creates a Node.js `Dns` service whose resolver lives as long as the scope.
*
* @stability experimental
* @category constructors
* @since 4.0.0
*/
export const make = Effect.fnUntraced(function*(options?: Options) {
const resolve = yield* resolver(options)
return Dns.make({
lookup,
resolve: (name, type) => Effect.map(resolve(name, type), Arr.map(utf8Strings))
})
})
/**
* Layer that provides the Node.js `Dns` service using the system resolver
* configuration.
*
* @stability experimental
* @category layers
* @since 4.0.0
*/
export const layer: Layer.Layer<Dns.Dns> = Layer.effect(Dns.Dns, Effect.orDie(make()))
/**
* Creates a layer that provides the Node.js `Dns` service with options read
* from configuration.
*
* @stability experimental
* @category layers
* @since 4.0.0
*/
export const layerConfig = (
options: Config.Wrap<Options>
): Layer.Layer<Dns.Dns, Config.ConfigError | NetAddress.NetAddressError> =>
Layer.effect(Dns.Dns, Effect.flatMap(Config.unwrap(options), make))