# Nameservers

## Servers

A resolver has 1 to 16 servers, asked in order:

- `DNS.Server.Tcp(host, port)` is DNS over TCP (RFC 7766): the message with its 2-byte length in front, on a connection of its own.
- `DNS.Server.Tls(host, port, name)` is DNS over TLS (RFC 7858): the same over TLS. The connection goes to `host`, and the certificate must have `name`, or `host` when `name` is `""`. So `Tls("1.1.1.1", 853, "one.one.one.one")` connects to the address and checks the name.
- `DNS.Server.Https(url)` is DNS over HTTPS (RFC 8484): the `https://` URL of the server. Each query is a POST of the type `application/dns-message` with the id 0, and an answer must be a 200 of that type, at most 65535 bytes. A `http://` URL is an error when the resolver is made.

`DNS.Options` has three fields:

- `timeout_ms` (3000 by default, 1 to one day): how long each server has for a whole query. For TCP and TLS it covers the connect, the handshake, the send and the read; for HTTPS, the whole request.
- `max_cnames` (8, 0 to 32): how many CNAMEs a name may follow.
- `tls`: the client context of the TLS and HTTPS servers, the system trust by default. Pass `TLS.client_context(TLS.ClientOptions(ca_file: "ca.pem"))` to trust your own CA.

DoH goes through `std/http` with no proxy and no connection reuse: each query makes its own TLS handshake, so a `lookup` (an A and an AAAA query) makes two. TCP and TLS keep nothing between queries either.

## Order and failures

A query goes to the first server. When it fails, the next one gets it: a timeout, a broken connection, SERVFAIL, REFUSED, a cut answer, and an answer that is not for the query. When all fail, the `error` of the last one is the result. NXDOMAIN ends the search, since the next server would say the same, and an NXDOMAIN answer must have its question.

## What is checked in an answer

Every answer must have the id of the query (0 over HTTPS), the QR flag, and one question that is the one asked, with the same type and class and the same name (names compare without case, as `DNS.same_name?(a, b)` does: `example.com.` is `EXAMPLE.com`). A server that fails may leave out the question. An answer with the TC flag is an error: a stream answer is never meant to be cut.

`DNS.addresses` takes only records of the class IN whose owner is the name asked or a name of its CNAME chain, so a record that a server adds for another name is not an address. The TTL of an address is the smallest of its chain.

## CNAMEs

A CNAME in the answer is followed. When the chain leaves the answer, the end of it is asked in a new query. More than `max_cnames` links, or a loop, is an error of the kind `dns.cname_limit`. A name that exists with no address of the type gives an empty list from `addresses`, and `dns.no_address` from `lookup`.

## Time

Each nameserver has `timeout_ms` for a query, so a query takes at most that for each server; `lookup` asks A and then AAAA (and skips AAAA when the name does not exist), and each CNAME that leaves an answer adds a query, so a `lookup` takes at most `2 * (max_cnames + 1) * servers * timeout_ms`.

## The nameservers of the system

Nothing reads `/etc/resolv.conf` unless you ask. `DNS.system_servers()` gives its `nameserver` lines (at most 3, as the C library reads them) as `Tcp` servers on port 53, and `DNS.system_servers(path)` reads another file. A nameserver must be an IPv4 or IPv6 address: a name, an address with a zone (`fe80::1%eth0`) and a line that is not `nameserver` are skipped. `search`, `ndots` and `options` are not applied, so a host is always asked as written. Not every system resolver answers over TCP, so use it only when yours does.

```agentica
import DNS from "pkg/dns/dns"

def main() -> Void
  servers = DNS.system_servers().unwrap!
  resolver = DNS.resolver(servers).unwrap!
  puts(DNS.lookup(resolver, "example.com").unwrap!)
end
```
