nxdns/specs/milestone-2.md

Milestone 2: DNS Core

Goal: pure DNS wire-format module (src/dns/) — parse, encode, iterate, mutate — with unit tests, malformed-input tests, and fuzz targets. Bytes in, bytes out: no std.Io, no sockets, no allocator in the parse path.

Read first: AGENTS.md, specs/research/zig-0.16-api-notes.md, specs/milestone-1.md (module conventions). RFC 1035 is the wire-format authority; RFC 6891 for EDNS(0); RFC 7871 for ECS option layout.

Sessions

Four sessions, sequential (each builds on the previous session's types):

S1 (types/header/name) → S2 (question/record/edns) → S3 (packet) → S4 (fuzz)

The orchestrator wires src/tests.zig imports and the fuzz build step after each session verifies.

As built (S1): the encode convention is LOCKED — fixed-size items into caller buffers (header.encode(h, out: *[12]u8)), variable-size through *std.Io.Writer (name.encode(n, w)); S3's ResponseBuilder wraps its buffer via std.Io.Writer.fixed and yields w.buffered(). name.parse returns a named Parsed { name, end }; end is always past the name at the original location (past the first pointer when compressed) — advance section walks by it unconditionally. Name.wire() returns the wire bytes. Reserved label types (bit patterns 01/10) surface as LabelTooLong. Pointer loops are impossible by construction (strictly-decreasing targets) — loops yield BadPointer; TooManyJumps fires on legal descending chains > 32.

As built (S2): extendedRcode takes types.Rcode (not u4). parseOpt validates the whole option list (error.BadOption) so an OptRecord from it always iterates cleanly; findOption(packet, opt, code) added. rdataCname accepts cname/ns/ptr. record.ParseError == name.ParseError (rdlength overrun = Truncated). record.encode/encodeOpt guard 16-bit length fields (RdataTooLong/OptionsTooLong). encodeOpt writes the root owner name itself and clears Z bits. RdataSpan.slice(packet) yields raw rdata; typed accessors need the whole packet. parseOpt rejects non-root owner / wrong type with error.NotOpt.

As built (S3, amended by review round 1): packet.ParseError = error{Truncated} || WalkError where WalkError = error{BadName, SectionOverrun, TrailingBytes, MultipleOptRecords} — Truncated means < 12 header bytes (silent drop); every WalkError member means FORMERR (name-level Truncated maps to SectionOverrun so the drop-vs-FORMERR branch is just error.Truncated vs else). parse consumes the buffer exactly (no trailing bytes) and permits at most one OPT per message (RFC 6891 §6.1.1, counted across all record sections); findOptRecord's last-OPT-wins walk matters only for hand-assembled Packets. decrementTtls returns ParseError!?u32 (null = no meaningful TTL, e.g. OPT-only); it validates fully BEFORE mutating, so malformed input leaves the buffer byte-identical — but a packet whose owner name compression-points into another record's TTL bytes can still fail mid-walk after aging changed those bytes; on ANY error the caller must discard the buffer (milestone 3's cache hit path must honor this — it ages private copies, so discard = drop the copy and treat as miss). A pointer-blind record-skip helper in record.zig would make that case atomic; deliberately not built until a consumer needs it. Iterators position lazily; constructors are infallible, errors surface from next(). firstQuestion/findOptRecord return plain ?T (validated-view invariant). addAnswer takes types.Class; ResponseBuilder asserts buf ≤ 65535 and no addAnswer after addOptEcho; setAuthoritative exists for later local records. NOTE for milestone 3+: ResponseBuilder has no addAuthority yet — negative-cache SOA synthesis needs a helper slotted between addAnswer and addOptEcho (section order).

Design invariants (all sessions)

• Parse functions take []const u8 (+ offset where needed) and return typed values or error.Malformed-family errors. No allocation during parse. Encode functions write through *std.Io.Writer or into caller-provided buffers — pick ONE convention in S1 (recommended: caller buffer + returned slice for fixed-size items, *std.Io.Writer for variable-size composition) and every later session follows it.
• Every parse is bounds-checked; no @intCast/@truncate on attacker-controlled values without prior range checks.
• All limits are named constants in types.zig (max name length 255, max label 63, max compression jumps, max packet size handled).
• Unit tests live in-file. Every parser gets malformed-input tests, not just happy-path.

---

Session S1: dns/types.zig, dns/header.zig, dns/name.zig

S1.1 types.zig

• pub const Type = enum(u16) { a = 1, ns = 2, cname = 5, soa = 6, ptr = 12, mx = 15, txt = 16, aaaa = 28, srv = 33, opt = 41, https = 65, ... , _ } — non-exhaustive enum; include at least the listed values plus svcb = 64, any = 255. Same pattern for Class = enum(u16) { in = 1, ch = 3, hs = 4, any = 255, _ }.
• pub const Rcode = enum(u4) { no_error = 0, form_err = 1, serv_fail = 2, nx_domain = 3, not_imp = 4, refused = 5, ... , _ } (4-bit header field; extended RCODE handled in edns.zig).
• pub const Opcode = enum(u4) { query = 0, iquery = 1, status = 2, notify = 4, update = 5, _ }.
• Limits: max_name_len = 255, max_label_len = 63, max_compression_jumps = 32, max_udp_payload = 512 (pre-EDNS default), header_len = 12.

S1.2 header.zig

• pub const Header = struct { id: u16, flags: Flags, qdcount: u16, ancount: u16, nscount: u16, arcount: u16 } with Flags = packed struct or explicit bit accessors for: QR, Opcode, AA, TC, RD, RA, Z (must parse, re-encode as-is), RCODE. Choose the representation that round-trips unknown Z bits faithfully.
• parse(bytes: []const u8) error{Truncated}!Header (first 12 bytes, big-endian), encode(h: Header, out: *[12]u8) void.
• Test: round-trip all flag bits including Z; truncated input.

S1.3 name.zig

• pub const Name = struct { bytes: [255]u8, len: u8 } — decoded, uncompressed wire form (length-prefixed labels, terminating zero counted in len).
• parse(packet: []const u8, offset: usize) ParseError!struct { name: Name, end: usize }:
  • follows compression pointers; each pointer must target an offset strictly LOWER than the offset of the pointer byte itself (kills loops and forward references); additionally cap at max_compression_jumps;
  • end is the offset after the name in the original location (first pointer or terminating zero);
  • errors: error{Truncated, LabelTooLong, NameTooLong, BadPointer, TooManyJumps}.
• encode(name: Name, w: *std.Io.Writer) !void — always uncompressed output (valid per RFC 1035; compression on encode is out of scope, document why in a comment: simplicity beats bytes at household scale).
• Helpers: fromText("example.com.") error{...}!Name (accepts with/without trailing dot; rejects empty labels except root, oversize labels/names); formatText (dots, no trailing dot except root); eqlIgnoreCase(a, b) bool (DNS names compare case-insensitively, RFC 1035 §2.3.3 — ASCII only); labelCount, isRoot.
• Tests: round-trip; pointer chain decode (hand-built packet); pointer loop → BadPointer/TooManyJumps; forward pointer → BadPointer; label 64 → LabelTooLong; total > 255 → NameTooLong; truncation mid-label; case-insensitive eql.

S1.4 Acceptance Criteria

• zig test src/dns/types.zig, zig test src/dns/header.zig, zig test src/dns/name.zig all pass.
• Every listed malformed case has a test.
• zig fmt --check clean on the three files.

---

Session S2: dns/question.zig, dns/record.zig, dns/edns.zig

S2.1 question.zig

• pub const Question = struct { name: name.Name, qtype: types.Type, qclass: types.Class }.
• parse(packet: []const u8, offset: usize) !struct { question: Question, end: usize }; encode(q, w) !void.

S2.2 record.zig

• pub const Record = struct { name: name.Name, rtype: types.Type, class: u16, ttl: u32, rdata: RdataSpan } where RdataSpan = struct { offset: usize, len: usize } — RDATA stays a span into the original packet (no copy; names inside RDATA may use compression pointers into the whole packet, so the span alone is not decodable out of context — document this).
• parse(packet, offset) !struct { record: Record, end: usize } — bounds-check rdlength against packet length.
• Typed RDATA accessors (take the whole packet + the record): rdataA(packet, rec) ! [4]u8, rdataAaaa ! [16]u8, rdataCname(packet, rec) !name.Name (decompresses), rdataSoaMinimumTtl(packet, rec) !u32 (walks MNAME/RNAME — both possibly compressed — then reads the 5th fixed u32; needed for negative caching §PLAN 8).
• encode(rec: Record, rdata_bytes: []const u8, w) !void — writes name uncompressed + fixed fields + rdlength + raw rdata (encoding path is for synthesized records whose rdata contains no compression).
• Tests: A/AAAA/CNAME/SOA parse from hand-built packets (with compressed names inside RDATA), rdlength overrun → error, SOA minimum extraction.

S2.3 edns.zig

• pub const OptRecord = struct { udp_payload_size: u16, extended_rcode: u8, version: u8, do_bit: bool, options: RdataSpan }.
• parseOpt(packet, record.Record) !OptRecord (OPT reinterprets class=udp size, ttl=flags per RFC 6891); findOpt(packet, additional-section iterator) ? — S3 provides the iterator, so here just parseOpt.
• Option iterator over the options span: OptionIterator yielding struct { code: u16, data: []const u8 }; ECS option code = 8; pub const Ecs = struct { family: u16, source_prefix: u8, scope_prefix: u8, address: []const u8 } + parseEcs(data) !Ecs.
• encodeOpt(opt: OptRecord, options_bytes: []const u8, w) !void — for building queries/responses with EDNS (DO-bit passthrough).
• Extended RCODE composition helper: extendedRcode(header_rcode: u4, opt: ?OptRecord) u12.
• Tests: OPT parse round-trip, DO bit both states, ECS v4+v6 parse, malformed option length → error.

S2.4 Acceptance Criteria

• zig test passes per file; malformed cases covered; zig fmt --check clean.

---

Session S3: dns/packet.zig

S3.1 API

• pub const Packet = struct { bytes: []const u8, header: header.Header } — a validated view.
• parse(bytes: []const u8) !Packet — validates header + walks all four sections once to verify structural integrity (every name/record bounds-checked); stores nothing but the bytes + header. Errors distinguish error.Truncated (severely truncated: less than a full header — the server will silently drop) from other malformed errors (server responds FORMERR) — this distinction is the PLAN §6.1 contract, document it here.
• Section iterators: questions(p) QuestionIterator, answers(p) RecordIterator, authorities(p), additionals(p) — lazy, re-walk on demand; firstQuestion(p) ?Question.
• findOptRecord(p) ?record.Record — last OPT in additionals per RFC 6891.
• Mutation helpers on raw mutable buffers (for the cache hit path, PLAN §8):
  • setId(bytes: []u8, id: u16) void.
  • decrementTtls(bytes: []u8, elapsed_seconds: u32) error{...}!void — walks answer/authority/additional records in place, saturating-subtracts elapsed from each TTL (not OPT records — their TTL field is flags). Returns the minimum resulting TTL so the caller can treat ≤0 as a miss.
• Response builder for synthesized replies (used later by blocking + local records; pure encoding, no policy):
  • pub const ResponseBuilder = struct { ... } writing into a caller buffer: init(buf, request_header, question) (copies id, RD; sets QR, sets RA), setRcode, addAnswer(name, type, class, ttl, rdata), addOptEcho(request opt, do_bit), finish() []u8 (patches counts). Encoding only — which rcode/answer to use is the caller's policy.
• Tests: parse a real captured query + response (hand-encoded fixtures in-file); iterators yield expected records; structural validation rejects: count fields larger than actual records, record overruns, question name loops; setId; decrementTtls including saturation and OPT skip; ResponseBuilder round-trips through parse.

S3.2 Acceptance Criteria

• zig test src/dns/packet.zig passes; zig fmt --check clean.
• A packet built by ResponseBuilder re-parses cleanly and its TTLs decrement correctly.

---

Session S4: fuzz targets

S4.1 tests/fuzz/dns_fuzz.zig

• Fuzz tests using std.testing.fuzz (0.16 Smith API — see API notes; read lib/std/testing/Smith.zig and the build_runner fuzz flags before writing):
  1. packet.parse on arbitrary bytes — must never panic/overflow; errors are fine. Property when parse succeeds: all iterators complete without error.
  2. name.parse on arbitrary bytes at arbitrary valid offsets — same property; additionally fromText(formatText(n)) round-trips when parse succeeds.
  3. decrementTtls on mutated valid packets — never panics.
• Seed corpus: a handful of valid query/response byte strings (reuse S3's fixtures via a shared tests/fuzz/corpus.zig or inline constants) plus known-nasty cases (pointer loop, deep pointer chain, rdlength overrun).
• The fuzz file must also pass as a normal test (corpus replay under plain zig build test).
• Investigate and REPORT (do not guess): exact zig build test --fuzz semantics in 0.16 (time-bounded? forever?), so the orchestrator can wire a bounded CI smoke step.

S4.2 Acceptance Criteria

• Fuzz file passes under plain test run.
• A bounded local fuzz run (document the exact command) executes without crashes for ≥ 60 seconds.
• zig fmt --check clean.

---

Module Layout

src/dns/types.zig      S1  enums + limits
src/dns/header.zig     S1  12-byte header
src/dns/name.zig       S1  labels, compression decode, text conversion
src/dns/question.zig   S2
src/dns/record.zig     S2  RR + typed RDATA accessors
src/dns/edns.zig       S2  OPT, DO bit, ECS
src/dns/packet.zig     S3  validated view, iterators, mutation, ResponseBuilder
tests/fuzz/dns_fuzz.zig S4

File Ownership

Sequential sessions; each owns only its listed files. Nobody edits build.zig/src/tests.zig (orchestrator wires: tests.zig imports per session; fuzz step after S4).

Acceptance Criteria (Milestone 2 Complete)

• zig build test green with all dns files wired into the aggregator.
• zig build test -Dintegration and -Dintegration -Dlive remain green (no regressions).
• Bounded fuzz smoke runs clean locally; CI gets a bounded fuzz job only if runner semantics allow bounding (else fuzz stays local + documented).

As built (S4): plain zig build test replays the seed corpus deterministically (test_runner.zig:596) — that IS the CI fuzz smoke. --fuzz=<n> counts iterations per test (no time bound exists; bare --fuzz = forever + webui; --fuzz=<n> conflicts with --webui). Corpus entries are Smith byte streams (u32-LE length-prefixed slices), encoded by tests/fuzz/corpus.zig. Two upstream 0.16.0 defects block zig build test -Dfuzz --fuzz=<n> on stock installs: (A) fuzz-mode test_runner.zig:566 type mismatch (*builtin.StackTrace vs *const std.debug.StackTrace) — needs a patched --zig-lib-dir; (B) self-hosted x86_64 backend emits no sanitizer coverage PCs — needs .use_llvm = true, which -Dfuzz sets. Verified bounded run: --fuzz=6M, 18M runs, 70.6s, no findings. Wiring: src/dns/dns.zig module root + second test artifact fuzz importing dns as a named module (zig test collects tests only from the root module; files belong to one module per compilation). Known measured limit: coverage guidance did not reach a planted record-type-specific panic in 6M runs — the targets are a crash detector + corpus regression suite, not semantic-reach proof. The name round-trip property is conditional: wire labels may contain '.' bytes, which formatText/fromText cannot round-trip.

• zig fmt --check clean repo-wide; signed lowercase commits.

Anti-Requirements

• No sockets, no std.Io, no allocator in parse paths, no clocks.
• No blocking/filtering policy — ResponseBuilder is mechanism only.
• No name compression on encode.
• No DNSSEC record parsing (DO-bit passthrough only), no TSIG, no zone-transfer opcodes beyond enum values.
• No IDN/punycode handling (bytes pass through opaquely).
• Do not touch milestone-1 files.