nish/net/dns
The stub resolver of nish/net/dns-resolver driven over nish:net sockets on the caller's own readiness loop, and resolveHost, which runs a loop of its own for a program that has none.
import {
DNS_CLIENT_MAX_DATAGRAMS,
DNS_UDP_MAX_REPLY,
DnsClient,
dnsLoadSystem,
dnsLookupWith,
resolveHost,
} from "nish/net/dns";
import { DnsClient, resolveHost } from "nish/net/dns"
import { DNS_RESOLVE_MAX_ADDRESSES, DNS_RESOLVE_PENDING, DnsResolver } from "nish/net/dns-resolver"
import { DnsConfig, dnsParseResolvConf } from "nish/net/dns-config"
import { DNS_ADDRESS_BYTES } from "nish/net/dns-message"
import { readFileBytesSync } from "nish:fs"
import { pollCreate, pollWait } from "nish:net"
import { monotonicNanos } from "nish:process"
const out: u8[] = new Array<u8>(DNS_RESOLVE_MAX_ADDRESSES * DNS_ADDRESS_BYTES)
const ttls: i32[] = new Array<i32>(DNS_RESOLVE_MAX_ADDRESSES)
// A command-line tool: block for at most two seconds.
const count: i32 = resolveHost("example.com", 2000, 443, out, ttls)
// A server: the lookup rides the loop it already runs.
const config: DnsConfig = new DnsConfig()
const resolv: u8[] = readFileBytesSync("/etc/resolv.conf") ?? new Array<u8>(0)
dnsParseResolvConf(resolv, 0, toI32(resolv.length), config)
const loop: i32 = pollCreate()
const client: DnsClient = new DnsClient(new DnsResolver(config, null, 4), loop, 1000)
const lookup: i32 = client.start("example.com", 443, monotonicNanos())
if (lookup >= 0) {
const ready: i32[] = new Array<i32>(16)
let status: i32 = client.result(lookup, out, ttls)
while (status === DNS_RESOLVE_PENDING) {
const n: i32 = pollWait(loop, ready, client.timeoutMs(monotonicNanos(), -1))
const now: i64 = monotonicNanos()
for (let k: i32 = 0; k < n; k++) {
if (client.owns(ready[2 * k])) {
client.ready(ready[2 * k], ready[2 * k + 1], now)
}
}
client.tick(now)
status = client.result(lookup, out, ttls)
}
// status: the address count, 18 bytes each in out, or a DNS_RESOLVE_* code
}
dnsLoadSystem
Reads the system's resolver settings the way resolveHost does: /etc/resolv.conf into config (a missing file means the defaults) and /etc/hosts into hosts (a missing file adds no entry).
dnsLookupWith
resolveHost with the configuration given rather than read: one lookup of name on a loop of its own, for at most timeoutMs.
resolveHost
The addresses of name, looked up as /etc/resolv.conf and /etc/hosts say (a missing resolv.conf means the defaults, a missing hosts file no entries), each 18 bytes with port into out and its TTL in seconds into ttls.
DnsClient
A DnsResolver driven on the caller's loop.
`DnsClient` is for a program with a loop
It opens a fresh UDP socket
on a kernel-chosen port for every UDP try and a TCP connection for every
TCP one, watches each under a token of the range it was given, and closes
it when the try ends. It never waits, never reads the clock and never
reads a file: the caller's loop owns all three, so a lookup costs a server
nothing while it waits. Each send's query ID is drawn from
crypto.getRandomValues, and every buffer it uses is made in its
constructor.
`resolveHost` and `dnsLookupWith` block the thread
resolveHost and dnsLookupWith block the thread, on a poll loop of
their own, so they are for a command-line tool or a program's start-up.
The caller owns `out` and `ttls`
Both need room for
DNS_RESOLVE_MAX_ADDRESSES entries (18 bytes each in out), or the call
that reads the answer panics; they are written only when it answers a
count. Reading a finished lookup's answer frees its slot, so read it once.
Errors are negative numbers
start answers DNS_RESOLVE_BUSY when
every slot is in use or the DNS_ERR_* code of a name that is not one; a
finished lookup answers DNS_RESOLVE_NOT_FOUND, DNS_RESOLVE_NO_ANSWER or
DNS_RESOLVE_CNAME. A socket that cannot be opened, written or connected
fails that one try, counted in socketFailures, and the query moves to
the next server. A token outside the client's range, a negative token base
and an out or ttls that is too short are bugs in the caller and panic.
Private helpers share the importing program's flat symbol namespace
(docs/wp26-stdlib.md §3e), which is why each one carries the module's name.
Functions
dnsLoadSystem
Reads the system's resolver settings the way resolveHost does:
/etc/resolv.conf into config (a missing file means the defaults) and
/etc/hosts into hosts (a missing file adds no entry). A driver of its
own, such as the async fetch's, starts from this so every lookup in a
program honours the same files. Both reads are synchronous file reads.
const dnsLoadSystem: (
config: DnsConfig | null,
hosts: DnsHosts,
) => void
configDnsConfig | nullrequired
A fresh DnsConfig to fill, or null to leave
/etc/resolv.conf unread (a caller with a configuration of its own).
hostsDnsHostsrequiredA fresh DnsHosts to fill.
dnsLookupWith
resolveHost with the configuration given rather than read: one lookup
of name on a loop of its own, for at most timeoutMs. Blocks as
resolveHost does, and reads no file. config and hosts are only read,
so one pair can serve many calls.
const dnsLookupWith: (
config: DnsConfig,
hosts: DnsHosts | null,
name: string,
timeoutMs: i32,
port: i32,
out: u8[],
ttls: i32[],
) => i32
configDnsConfigrequiredThe resolv.conf to use, as dnsParseResolvConf filled it.
hostsDnsHosts | nullrequiredThe hosts file to consult first, as dnsParseHosts filled it, or null for none.
namestringrequiredThe name to look up.
timeoutMsi32requiredThe most the whole lookup may take, in milliseconds, on the monotonic clock.
porti32requiredThe port, 0 to 65535, written into every address; any other value panics.
outu8[]required
Where the addresses go, from offset 0, A first; at least
DNS_RESOLVE_MAX_ADDRESSES * 18 bytes, or this panics.
ttlsi32[]required
Where each address's TTL goes, in seconds; at least DNS_RESOLVE_MAX_ADDRESSES,
or this panics.
returnsi32
What resolveHost answers: the address count, or a negative DNS_RESOLVE_*,
DNS_ERR_* or errno code.
resolveHost
The addresses of name, looked up as /etc/resolv.conf and /etc/hosts
say (a missing resolv.conf means the defaults, a missing hosts file no
entries), each 18 bytes with port into out and its TTL in seconds into
ttls. It waits for both the A and the AAAA answer until timeoutMs
passes; then a family that answered with addresses is returned on its own,
and only a lookup with none yet is DNS_RESOLVE_TIMEOUT.
It blocks the thread until the lookup ends, on a loop of its own, so
it is for a CLI or a program's start-up; a server resolves with a
DnsClient on its own loop. out and ttls need room for
DNS_RESOLVE_MAX_ADDRESSES, or it panics. Each call reads both files and
makes its own configuration, resolver and loop, closing the loop before
it returns.
const resolveHost: (
name: string,
timeoutMs: i32,
port: i32,
out: u8[],
ttls: i32[],
) => i32
namestringrequired
The name to look up; localhost, an address literal and a hosts entry answer
without a packet, even with a timeoutMs of 0.
timeoutMsi32requiredThe most the whole lookup may take, in milliseconds, on the monotonic clock.
porti32requiredThe port, 0 to 65535, written into every address; any other value panics.
outu8[]required
Where the addresses go, from offset 0, A first; at least
DNS_RESOLVE_MAX_ADDRESSES * 18 bytes.
ttlsi32[]requiredWhere each address's TTL goes, in seconds; at least DNS_RESOLVE_MAX_ADDRESSES.
returnsi32
The count of addresses written; or a negative code: DNS_RESOLVE_TIMEOUT once
timeoutMs has passed with no address found, DNS_RESOLVE_NOT_FOUND, DNS_RESOLVE_NO_ANSWER or
DNS_RESOLVE_CNAME from the lookup, the DNS_ERR_* code of a name that is not one, or
the negative errno of a poll loop that cannot be made or waited on.
Classes
DnsClient
A DnsResolver driven on the caller's loop. Its sockets are watched under
tokens tokenBase to tokenBase + tokens() - 1, one per query, and the
caller hands every ready pair in that range to ready.
class DnsClient
| Member | |
|---|---|
new DnsClient(resolver: DnsResolver, loop: i32, tokenBase: i32) |
A client for resolver whose sockets join the loop loop under tokens from tokenBase. Every buffer the client uses is made here, one TCP output buffer per query among them. Panics when tokenBase is negative. |
resolver: DnsResolver |
The core; start, result and cancel go through the client so its sockets follow. |
socketFailures: i32 |
Sockets that could not be opened, written or connected, each a failed try. |
socketsOpened: i32 |
Sockets opened, UDP and TCP, one per try. |
tokenBase: i32 |
The first of the client's tokens; its sockets use tokenBase to tokenBase + tokens() - 1. |
cancel(lookup: i32, nowNanos: i64): void |
DnsResolver.cancel, closing the lookup's sockets now and freeing its slot, whether or not it had finished. Panics for an id that is not a lookup in progress, as result does. |
owns(token: i32): boolean |
Whether token is one of the client's, so the caller knows which ready pairs from pollWait to hand to ready. |
ready(token: i32, events: i32, nowNanos: i64): void |
The pair token, events that pollWait reported at nowNanos, for a token owns answers true for: reads the datagrams (at most DNS_CLIENT_MAX_DATAGRAMS) or stream bytes that are waiting, finishes a connection or a write, and sends whatever the core asks next. Panics for a token that is not the client's. A token whose try has already ended is ignored. |
result(lookup: i32, out: u8[], ttls: i32[]): i32 |
DnsResolver.result; a finished lookup's sockets are already closed. Answering a finished lookup frees its slot, so a second call for it, or one for an id start did not give out, panics. |
settle(lookup: i32, nowNanos: i64): boolean |
DnsResolver.settle, closing the socket of the query it stops: ends the lookup with the addresses one family has found when the other is still asking, so a caller whose time is up keeps them. |
start(name: string, port: i32, nowNanos: i64): i32 |
DnsResolver.start, with its first packets sent. localhost, an address literal and a hosts entry finish at once, so result has their answer straight away. |
tick(nowNanos: i64): void |
DnsResolver.tick, then whatever it asks to send: every try past its deadline moves to the next server. Call it after each wake of the loop. |
timeoutMs(nowNanos: i64, ownMs: i32): i32 |
The pollWait timeout for a caller who would otherwise wait ownMs (negative for ever): the smaller of it and the milliseconds, rounded up, to the core's next deadline after nowNanos. |
tokens(): i32 |
How many tokens, from tokenBase, the client's sockets use: two per lookup slot, one for the A query and one for the AAAA query. |
Limits
32
DNS_CLIENT_MAX_DATAGRAMS: i32
The most datagrams one ready reads from a query's socket. The loop is
level-triggered, so the rest wait for the next pollWait, and a flood on
the port cannot hold the caller's loop inside the client.
4,096
DNS_UDP_MAX_REPLY: i32
The longest datagram a UDP try reads, in bytes; a longer one is cut, fails to parse and is dropped. A TCP try reads its stream in chunks of this size.

