$ compendium/api

The C API

A small, testable wire + lookup core, exposed through dnsd.h.

API surface

// src/dnsd.h

The server's logic is split from the UDP loop so it can be unit-tested and embedded. config_load evaluates a Dhall file into a DnsConfig; dns_handle_query turns one received packet into a response; dns_lookup exposes the pure lookup semantics.

#include dnsd.h

// evaluate a Dhall config file into the server's zone table
DnsConfig cfg;
int rc = config_load(&cfg, path, err, sizeof err);

// look up a name (lowercase, trailing dot) of a type, filling answers
int n, int rcode;
dns_lookup(&cfg, qn, T_A, ans, MAX_ANSWERS, &n, &rcode);

The same core, compiled to wasm, is what powers the <compendium-playground> in your browser (via src/dnsd-wasm.c).

DNS wire format

// RFC 1035 · record types · rcodes

Responses are capped at MAX_PKT (512) bytes with TC truncation; answers are capped at MAX_ANSWERS (16) per response. The supported rcodes are NOERROR, FORMERR, NXDOMAIN, NOTIMP, and REFUSED. EDNS0 is ignored (no large-response amplification).

The wire path is fully bounds-checked: label-length caps, compressed-pointer depth limits, and cached rdata parsing keep the remote path deterministic and memory-safe.

Rate limiting

// rl.c · token buckets

An authoritative nameserver on the open internet is a reflection/amplification target. rl.c factors the pure token-bucket decision out of the UDP loop so it is unit-tested directly. Per-source burst 100 / 20 q/s; a rotating-spoofed-source flood is bounded by a global bucket burst 500 / 100 q/s.