nish/net/dns-config

/etc/resolv.conf and /etc/hosts, read from bytes the caller already has into fixed tables.

import {
  DNS_CONFIG_MAX_LINE,
  DNS_DEFAULT_ATTEMPTS,
  DNS_DEFAULT_NDOTS,
  DNS_DEFAULT_TIMEOUT,
  DNS_HOSTS_MAX_ENTRIES,
  DNS_HOSTS_MAX_NAME,
  DNS_HOSTS_MAX_NAMES,
  DNS_HOSTS_MAX_NAME_BYTES,
  DNS_MAX_ATTEMPTS,
  DNS_MAX_NDOTS,
  DNS_MAX_SEARCH,
  DNS_MAX_SEARCH_BYTES,
  DNS_MAX_SERVERS,
  DNS_MAX_TIMEOUT,
  DNS_PORT,
  DnsConfig,
  DnsHosts,
  dnsHostsFind,
  dnsParseAddress,
  dnsParseHosts,
  dnsParseResolvConf,
} from "nish/net/dns-config";
import { DnsConfig, DnsHosts, dnsHostsFind, dnsParseHosts, dnsParseResolvConf } from "nish/net/dns-config"
import { DNS_ADDRESS_BYTES, DNS_TYPE_A } from "nish/net/dns-message"
import { readFileBytesSync } from "nish:fs"

const config: DnsConfig = new DnsConfig()
const resolv: u8[] | null = readFileBytesSync("/etc/resolv.conf")
if (resolv !== null) {
  dnsParseResolvConf(resolv, 0, toI32(resolv.length), config)
} else {
  // An empty file still gives the defaults; a fresh DnsConfig has no servers.
  dnsParseResolvConf(new Array<u8>(0), 0, 0, config)
}
// config.servers[i * 18, +18) for i < config.serverCount, on port 53
const hosts: DnsHosts = new DnsHosts()
const file: u8[] | null = readFileBytesSync("/etc/hosts")
if (file !== null) {
  dnsParseHosts(file, 0, toI32(file.length), hosts)
}
const out: u8[] = new Array<u8>(8 * DNS_ADDRESS_BYTES)
const found: i32 = dnsHostsFind(hosts, "localhost", DNS_TYPE_A, 80, out, 8)
// out[0, found * 18): the A addresses /etc/hosts gives localhost, on port 80

Both files are local, but neither is trusted to be small or well formed: a container image, a DHCP client or a VPN writes them, and a resolver that believed a 40,000-entry search list or a line a megabyte long would spend a lookup on it. This module reads each into tables of fixed, documented size, and counts what did not fit rather than growing:

resolv.conf

resolv.conf is read as glibc reads it, minus what a stub resolver does not use. nameserver takes one IPv4 or IPv6 literal (no zone), and the first DNS_MAX_SERVERS (3) are kept; search and domain each replace the list, so the last one wins, and it holds at most DNS_MAX_SEARCH (6) domains and DNS_MAX_SEARCH_BYTES (256) bytes; options reads ndots:n (clamped to 0 to 15), timeout:n (1 to 30 seconds) and attempts:n (1 to 5) and ignores every other option. With no nameserver line that holds an address, the servers are 127.0.0.1 and ::1, as glibc's are.

hosts

hosts is an address and then its names, one entry a line. At most DNS_HOSTS_MAX_ENTRIES entries and DNS_HOSTS_MAX_NAMES names are kept, in at most DNS_HOSTS_MAX_NAME_BYTES bytes; a name past a cap is dropped and counted. Names are kept in lowercase and found without case, with one trailing . ignored on either side; an IPv4 address answers only an A lookup and an IPv6 address only an AAAA one, ::ffff:a.b.c.d being IPv4.

In both

In both, # and ; start a comment that runs to the end of the line, a line no directive names is ignored, and a line longer than DNS_CONFIG_MAX_LINE bytes is skipped whole and counted in skippedLines, never cut to a shorter line that means something else. A window outside its array is a bug in the caller and panics; nothing in a file does.

Addresses are the 18-byte form of docs/LANGUAGE.md, which dnsParseAddress writes from a literal. The record of what this module refuses and why is docs/security/dns.md.

Functions

dnsHostsFind

Writes the addresses hosts gives name, of qtype (DNS_TYPE_A or DNS_TYPE_AAAA), into out from offset 0 with port, in file order and at most max of them, and answers how many it wrote. An entry that names name twice is written once; two entries with the same address are each written. It allocates nothing.

const dnsHostsFind: (
  hosts: DnsHosts,
  name: string,
  qtype: i32,
  port: i32,
  out: u8[],
  max: i32,
) => i32
hostsDnsHostsrequired

The table dnsParseHosts filled.

namestringrequired

The name to find, without case, one trailing . ignored.

qtypei32required

DNS_TYPE_A for the IPv4 entries or DNS_TYPE_AAAA for the IPv6 ones; any other type panics.

porti32required

The port written into each address, 0 to 65535; any other value panics.

outu8[]required

Where the 18-byte addresses go, back to back from offset 0.

maxi32required

The most addresses to write, 0 or more; out must have room for max of them, or this panics.

returnsi32

How many addresses were written, 0 when hosts does not name name.

dnsParseAddress

Writes the IPv4 or IPv6 literal b[off, off + len) at out[at, at + 18), IPv4 as ::ffff:a.b.c.d, with port big-endian after it, and answers whether it was one. out is written only when it was. A zone (%eth0), brackets and a port are not part of a literal, so a window holding one is refused; so is an IPv4 part with a leading zero, never read as octal.

Each call allocates the sixteen bytes it parses into, released when it returns; the two file parsers reuse a buffer of their own instead.

const dnsParseAddress: (
  b: u8[],
  off: i32,
  len: i32,
  out: u8[],
  at: i32,
  port: i32,
) => boolean
bu8[]required

The bytes the literal is in.

offi32required

Where the literal starts in b.

leni32required

The literal's length in bytes; the whole window must be the literal, with no blank. A window outside b panics.

outu8[]required

Where the 18-byte address goes.

ati32required

Where in out it starts; out[at, at + 18) must lie inside out, or this panics.

porti32required

The port written after the address, 0 to 65535; any other value panics.

returnsboolean

True when the window was an IPv4 or IPv6 literal and out now holds it.

dnsParseHosts

Reads the hosts file b[off, off + len) into hosts, which starts over empty. It allocates nothing; a line whose address is not a literal, or that names nothing, is ignored, and what does not fit is counted.

const dnsParseHosts: (
  b: u8[],
  off: i32,
  len: i32,
  hosts: DnsHosts,
) => void
bu8[]required

The file's bytes, read by the caller.

offi32required

Where the file starts in b.

leni32required

The file's length in bytes; a window outside b panics.

hostsDnsHostsrequired

The table to fill; it is emptied first, so one can be reused.

dnsParseResolvConf

Reads the resolv.conf b[off, off + len) into config, which starts over from the defaults, and gives it 127.0.0.1 and ::1 on port 53 when no nameserver line held an address. It allocates nothing, and nothing in the bytes makes it panic or fail: what it cannot use is ignored or counted.

const dnsParseResolvConf: (
  b: u8[],
  off: i32,
  len: i32,
  config: DnsConfig,
) => void
bu8[]required

The file's bytes, read by the caller.

offi32required

Where the file starts in b.

leni32required

The file's length in bytes; a window outside b panics.

configDnsConfigrequired

The table to fill; its counts and options are reset first, so one can be reused.

Classes

DnsConfig

One resolv.conf, read by dnsParseResolvConf, made once and reusable.

class DnsConfig
Member
new DnsConfig() Makes an empty configuration with no servers or search domains, and ndots, timeout and attempts at resolv.conf's defaults (1, 5 seconds, 2).
attempts: i32 Rounds through the servers before giving up, 1 to DNS_MAX_ATTEMPTS.
droppedSearch: i32 Search domains past DNS_MAX_SEARCH or DNS_MAX_SEARCH_BYTES, or empty (a bare .), read and not kept.
droppedServers: i32 Nameserver lines past DNS_MAX_SERVERS, read and not kept.
ndots: i32 Dots a name needs to be tried as it stands before the search list, 0 to DNS_MAX_NDOTS.
search: u8[] The search domains, back to back, lowercase, without a trailing dot.
searchCount: i32 How many search domains are kept, 0 to DNS_MAX_SEARCH.
searchLength: i32[] Each search domain's length in bytes, by the same index as searchStart.
searchStart: i32[] Where each of the searchCount domains starts in search, and its length.
serverCount: i32 How many addresses servers holds, 1 to DNS_MAX_SERVERS once a file is read.
servers: u8[] serverCount addresses of DNS_ADDRESS_BYTES each, on DNS_PORT.
skippedLines: i32 Lines longer than DNS_CONFIG_MAX_LINE, skipped whole.
timeout: i32 Seconds to wait for one server's reply, 1 to DNS_MAX_TIMEOUT.

DnsHosts

One hosts file, read by dnsParseHosts, made once and reusable.

class DnsHosts
Member
new DnsHosts() Makes an empty table, sized for DNS_HOSTS_MAX_ENTRIES addresses and DNS_HOSTS_MAX_NAMES names, for dnsParseHosts to fill.
droppedEntries: i32 Lines with an address word and a name past the first DNS_HOSTS_MAX_ENTRIES entries, read and not kept; their address is not parsed.
droppedNames: i32 Names past a cap, or longer than DNS_HOSTS_MAX_NAME, read and not kept.
entryCount: i32 How many entries, each an address and its names, are kept, 0 to DNS_HOSTS_MAX_ENTRIES.
nameBytes: i32 How many bytes those names take together, 0 to DNS_HOSTS_MAX_NAME_BYTES.
nameCount: i32 How many names all the entries hold together, 0 to DNS_HOSTS_MAX_NAMES.
skippedLines: i32 Lines longer than DNS_CONFIG_MAX_LINE, skipped whole.

Limits

1,024

DNS_CONFIG_MAX_LINE: i32

The longest line either parser reads; a longer one is skipped whole.

256

DNS_HOSTS_MAX_ENTRIES: i32

How many hosts lines, each an address with its names, are kept.

253

DNS_HOSTS_MAX_NAME: i32

The longest hosts name kept, the longest a DNS name can be.

1,024

DNS_HOSTS_MAX_NAMES: i32

How many names all hosts entries may hold together.

16,384

DNS_HOSTS_MAX_NAME_BYTES: i32

How many bytes those names may take together, 16 KiB.

5

DNS_MAX_ATTEMPTS: i32

The highest attempts:n kept; the lowest is 1.

15

DNS_MAX_NDOTS: i32

The highest ndots:n kept; a higher one is clamped to it, as glibc clamps.

6

DNS_MAX_SEARCH: i32

How many search domains are kept.

256

DNS_MAX_SEARCH_BYTES: i32

How many bytes the search domains may take together.

3

DNS_MAX_SERVERS: i32

How many nameserver lines are kept; glibc's MAXNS.

30

DNS_MAX_TIMEOUT: i32

The highest timeout:n kept, in seconds; the lowest is 1.

Constants

2

DNS_DEFAULT_ATTEMPTS: i32

The attempts without an option: rounds through the server list before a lookup gives up.

1

DNS_DEFAULT_NDOTS: i32

The ndots without an option: a name with a dot is tried as it stands first.

5

DNS_DEFAULT_TIMEOUT: i32

The timeout without an option, in seconds: how long one server's reply is waited for.

53

DNS_PORT: i32

The port every nameserver address carries.