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
}
`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).

hostsDnsHostsrequired

A 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
configDnsConfigrequired

The resolv.conf to use, as dnsParseResolvConf filled it.

hostsDnsHosts | nullrequired

The hosts file to consult first, as dnsParseHosts filled it, or null for none.

namestringrequired

The name to look up.

timeoutMsi32required

The most the whole lookup may take, in milliseconds, on the monotonic clock.

porti32required

The 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.

timeoutMsi32required

The most the whole lookup may take, in milliseconds, on the monotonic clock.

porti32required

The 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[]required

Where 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.