// SPDX-FileCopyrightText: 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The DNS, as this library needs to see it. //! //! SPF's evaluation *is* a recursive DNS walk: what gets looked up next //! is decided by what the last lookup returned, so the queries cannot be //! hoisted out of the algorithm and handed in as data. What can be handed //! in is the thing that answers them, which is what this is. //! //! That is worth more than tidiness. [RFC //! 7208](https://datatracker.ietf.org/doc/html/rfc7208)'s conformance //! suite is written as a table of zone data and expected results, so a //! resolver that reads a table is the whole of running it — offline, with //! no server and no virtual machine. `Zone` in the tests is exactly that, //! and the same seam is what lets a caller put caching, DNSSEC validation //! or a query budget of its own underneath. //! //! Nothing here allocates. An answer is written into storage the caller //! owns, and a resolver that runs out of room leaves what it has already //! written in place and returns `error.NoSpace` — because for some of //! these queries running out of room is not an error at all, and the //! evaluator needs what was found. See `ptr`. const std = @import("std"); const Io = std.Io; const z46 = @import("z46"); const Resolver = @This(); context: ?*anyopaque, vtable: *const VTable, pub const Error = error{ /// The name does not exist, or exists with no records of the type /// asked for. The two are one answer here because SPF treats them /// alike: both are a mechanism that does not match, and both are a /// "void lookup" against the limit of §4.6.4. NotFound, /// Anything the question might be answered differently tomorrow: /// SERVFAIL, a timeout, no reachable server. §4.4 makes this a /// `temperror`, which is the result that asks the sender to try /// again rather than telling them they are forged. Temporary, /// The answer did not fit. Whatever was written stays written. NoSpace, } || Io.Cancelable; pub const VTable = struct { /// Every TXT record of `name`, each already joined from the /// character-strings it was published in. txt: *const fn (context: ?*anyopaque, io: Io, name: []const u8, out: *Strings) Error!void, /// The addresses of `name` in one family: A records for `.ipv4`, /// AAAA for `.ipv6`. The two are never mixed, because a mechanism /// compares against a client whose family is already known. addresses: *const fn ( context: ?*anyopaque, io: Io, name: []const u8, family: z46.Family, out: *Addresses, ) Error!void, /// The exchangers of `name`, in no particular order — SPF asks /// whether the client is one of them, so preference does not matter. mx: *const fn (context: ?*anyopaque, io: Io, name: []const u8, out: *Strings) Error!void, /// The names `name` points at, where `name` is a reverse-DNS name /// such as `1.0.0.127.in-addr.arpa`. /// /// §4.6.4 caps this at ten names and says the rest "MUST be ignored" /// — ignored, not refused, which is why a resolver that fills its /// storage must leave the names it did write in place. ptr: *const fn (context: ?*anyopaque, io: Io, name: []const u8, out: *Strings) Error!void, }; pub fn txt(resolver: Resolver, io: Io, name: []const u8, out: *Strings) Error!void { return resolver.vtable.txt(resolver.context, io, name, out); } pub fn addresses( resolver: Resolver, io: Io, name: []const u8, family: z46.Family, out: *Addresses, ) Error!void { return resolver.vtable.addresses(resolver.context, io, name, family, out); } pub fn mx(resolver: Resolver, io: Io, name: []const u8, out: *Strings) Error!void { return resolver.vtable.mx(resolver.context, io, name, out); } pub fn ptr(resolver: Resolver, io: Io, name: []const u8, out: *Strings) Error!void { return resolver.vtable.ptr(resolver.context, io, name, out); } /// A set of strings an answer is collected into: the TXT records of a /// name, the exchangers of a domain, the names an address points at. /// /// Both the bytes and the index are the caller's, so the whole of a /// lookup lives wherever that caller decided — a stack frame, in the /// evaluator's case. pub const Strings = struct { storage: []u8, index: [][]const u8, /// When set, a string that does not begin with this — compared /// without case — is discarded rather than stored. /// /// It is here rather than in each resolver so that no resolver can /// forget it, and it exists because of what a TXT record set looks /// like in practice: `amazon.com` publishes sixty-four TXT records /// and about 4.6 kilobytes of them, of which an SPF evaluation wants /// one. Sizing every recursion level's buffer for the whole set /// would cost tens of kilobytes of stack to hold ownership tokens /// nobody is going to read. keep_prefix: ?[]const u8 = null, len: usize = 0, used: usize = 0, pub fn init(storage: []u8, index: [][]const u8) Strings { return .{ .storage = storage, .index = index }; } /// Copies `bytes` in, unless `keep_prefix` says not to. `error.NoSpace` /// when either the bytes or the index is full; what was already added /// stays. pub fn append(strings: *Strings, bytes: []const u8) error{NoSpace}!void { if (strings.keep_prefix) |prefix| { if (bytes.len < prefix.len) return; if (!std.ascii.eqlIgnoreCase(bytes[0..prefix.len], prefix)) return; } if (strings.len == strings.index.len) return error.NoSpace; if (strings.used + bytes.len > strings.storage.len) return error.NoSpace; const at = strings.used; @memcpy(strings.storage[at..][0..bytes.len], bytes); strings.used += bytes.len; strings.index[strings.len] = strings.storage[at..][0..bytes.len]; strings.len += 1; } pub fn slice(strings: *const Strings) []const []const u8 { return strings.index[0..strings.len]; } pub fn reset(strings: *Strings) void { strings.len = 0; strings.used = 0; } }; /// The addresses of one name, in one family. pub const Addresses = struct { index: []z46.Address, len: usize = 0, pub fn init(index: []z46.Address) Addresses { return .{ .index = index }; } pub fn append(addresses_: *Addresses, address: z46.Address) error{NoSpace}!void { if (addresses_.len == addresses_.index.len) return error.NoSpace; addresses_.index[addresses_.len] = address; addresses_.len += 1; } pub fn slice(addresses_: *const Addresses) []const z46.Address { return addresses_.index[0..addresses_.len]; } pub fn reset(addresses_: *Addresses) void { addresses_.len = 0; } };