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
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.
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.
dnsParseHosts
Reads the hosts file b[off, off + len) into hosts, which starts over empty.
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.
DnsConfig
One resolv.conf, read by dnsParseResolvConf, made once and reusable.
DnsHosts
One hosts file, read by dnsParseHosts, made once and reusable.
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
hostsDnsHostsrequiredThe table dnsParseHosts filled.
namestringrequiredThe 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.
porti32requiredThe port written into each address, 0 to 65535; any other value panics.
outu8[]requiredWhere 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.
returnsi32How 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[]requiredThe bytes the literal is in.
offi32requiredWhere 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[]requiredWhere the 18-byte address goes.
ati32requiredWhere in out it starts; out[at, at + 18) must lie inside out, or this panics.
porti32requiredThe port written after the address, 0 to 65535; any other value panics.
returnsbooleanTrue 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[]requiredThe file's bytes, read by the caller.
offi32requiredWhere the file starts in b.
leni32requiredThe file's length in bytes; a window outside b panics.
hostsDnsHostsrequiredThe 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[]requiredThe file's bytes, read by the caller.
offi32requiredWhere the file starts in b.
leni32requiredThe file's length in bytes; a window outside b panics.
configDnsConfigrequiredThe 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.

