Skip to content

Dns

Spice
import "std/net/dns";

DnsServer struct

Name server to send queries to

Fields

Name Type Description
address IpAddress Address of the name server
port unsigned short Port of the name server, usually DNS_PORT

DnsConfig struct

Configuration of the resolver, usually read from /etc/resolv.conf (see resolv.conf(5)) or, on Windows, taken from the network adapters

Fields

Name Type Description
servers Vector<DnsServer> Name servers, asked in this order
searchDomains Vector<String> Domains to append to names with less than ndots dots
ndots unsigned int Number of dots, from which on a name is tried as absolute name first
timeoutMs unsigned long Time to wait for the answer of a name server
attempts unsigned int Number of rounds over all name servers

DnsResponse struct

Answer of a name server to a single query

Fields

Name Type Description
responseCode int Response code (RCODE), e.g. DNS_RCODE_NO_ERROR or DNS_RCODE_NAME_ERROR
truncated bool The answer did not fit into the datagram and has to be asked for over TCP
addresses Vector<IpAddress> Addresses of the queried name, with CNAME records followed

DnsResolver struct

Resolves host names to IPv4 and IPv6 addresses via the hosts file and DNS

Constructors

ctor

Spice
public p DnsResolver.ctor()

Creates a resolver with the system configuration (see loadDnsConfig) and the hosts file of the system (see getSystemHostsFilePath). The configuration is only loaded, once a name server has to be asked, so that IP address literals and names from the hosts file do not pay for it.

ctor

Spice
public p DnsResolver.ctor(const DnsConfig& config, const String& hostsFilePath)

Creates a resolver with the given configuration

Parameters

Name Type Description
config const DnsConfig& Name servers and search rules
hostsFilePath const String& Path of the hosts file, empty to skip the hosts file

Methods

resolve

Spice
public f<Result<Vector<IpAddress>>> DnsResolver.resolve(const String& host, bool includeIpv4 = true, bool includeIpv6 = true)

Resolves a host name to its addresses. An IP address literal (IPv6 optionally in brackets, like in URLs) resolves to itself. Otherwise the name is looked up in the hosts file first and, if it is not listed there, asked for at the name servers, with the search domains applied like described in resolv.conf(5). The names "localhost" and "*.localhost" resolve to the loopback addresses, unless the hosts file lists them (it takes precedence, like with the C library). Names, whose last label is a decimal or hexadecimal number (like "127.1" or "0x7f000001"), are rejected instead of being sent to the name servers. IPv4 addresses come first in the result, IPv6 addresses second.

Parameters

Name Type Description
host const String& Host name or IP address literal
includeIpv4 bool Look for IPv4 addresses (default: true)
includeIpv6 bool Look for IPv6 addresses (default: true)

Returns: Result<Vector<IpAddress>> — Addresses of the host, never empty

connectTcp

Spice
public f<Result<int>> DnsResolver.connectTcp(const String& host, unsigned short port)

Opens a TCP connection to the given host and port. A host may have several IPv4 and IPv6 addresses,
which are tried one after the other, until a connection is established:
- Addresses, that need no name server (IP address literals, the hosts file, the localhost names),
are tried first, IPv4 ones before IPv6 ones.
- Otherwise the candidate names (see resolve) are asked for one after the other. For each one, the
IPv4 addresses are looked up and tried first; the IPv6 addresses are only looked up, if none of
them works, so that a slow or missing answer for them never delays a connection. The first
candidate, that has any addresses, is the last one to be asked for, like with resolve.

Parameters

Name Type Description
host const String& Host name or IP address literal (IPv6 optionally in brackets)
port unsigned short Port to connect to

Returns: Result<int> — File descriptor (socket handle on Windows) of the connected socket

query

Spice
public f<Result<DnsResponse>> DnsResolver.query(const String& name, unsigned short recordType)

Asks the name servers for the records of the given type of exactly the given name. The name servers are asked one after the other, until one gives a definite answer (the name exists or does not exist), for the configured number of rounds.

Parameters

Name Type Description
name const String& Absolute name to ask for, with or without trailing dot
recordType unsigned short DNS_TYPE_A or DNS_TYPE_AAAA

Returns: Result<DnsResponse> — Definite answer of a name server

Functions

loadDnsConfig

Spice
public f<DnsConfig> loadDnsConfig()

Reads the DNS configuration of the system: on Linux and macOS from /etc/resolv.conf, on Windows from the name servers and DNS suffixes of the network adapters. If there is none, the defaults apply, i.e. the name server on the local host is asked.

Returns: DnsConfig — DNS configuration

parseResolvConf

Spice
public f<DnsConfig> parseResolvConf(const String& content)

Parses the content of a resolv.conf file (see resolv.conf(5)). Understood are the keywords 'nameserver' (up to three), 'search', 'domain' and 'options' with the options 'ndots:n', 'timeout:n' and 'attempts:n'. Anything else is ignored. Without any name server, the name server on the local host is used.

Parameters

Name Type Description
content const String& Content of the resolv.conf file

Returns: DnsConfig — DNS configuration

lookupHostsFile

Spice
public f<Vector<IpAddress>> lookupHostsFile(const String& content, const String& name)

Looks up a name in the content of a hosts file (see hosts(5)). Each line holds an address, followed by the canonical name and the aliases of the host.

Parameters

Name Type Description
content const String& Content of the hosts file
name const String& Name to look up, in lowercase and without trailing dot

Returns: Vector<IpAddress> — Addresses of all lines, that list the name, in the order of the lines

buildDnsQuery

Spice
public f<Result<Vector<unsigned byte>>> buildDnsQuery(unsigned short id, const String& name, unsigned short recordType)

Encodes a query for the records of the given type of the given name, with recursion desired

Parameters

Name Type Description
id unsigned short ID of the query, that the answer has to carry
name const String& Absolute name to ask for, without trailing dot
recordType unsigned short Record type to ask for

Returns: Result<Vector<unsigned byte>> — Encoded query

parseDnsResponse

Spice
public f<Result<DnsResponse>> parseDnsResponse(const Vector<unsigned byte>& message, unsigned short id, const String& name, unsigned short recordType)

Decodes the answer of a name server to a query. The answer is only accepted, if it carries the ID of the query and repeats its question. The addresses are taken from the records of the queried name or, if it is an alias, from the records of the name that the CNAME records lead to.

Parameters

Name Type Description
message const Vector<unsigned byte>& Encoded answer
id unsigned short ID of the query
name const String& Name, that the query asked for, in lowercase and without trailing dot
recordType unsigned short Record type, that the query asked for

Returns: Result<DnsResponse> — Decoded answer

getSystemHostsFilePath

Spice
public f<String> getSystemHostsFilePath()

Returns the path of the hosts file of the system: /etc/hosts on Linux and macOS, %SystemRoot%\System32\drivers\etc\hosts on Windows

Returns: String — Path of the hosts file

resolveHostAddresses

Spice
public f<Result<Vector<IpAddress>>> resolveHostAddresses(const String& host, bool includeIpv4 = true, bool includeIpv6 = true)

Resolves a host name to its addresses with the system configuration (see loadDnsConfig) and the hosts file of the system. See DnsResolver.resolve for the details.

Parameters

Name Type Description
host const String& Host name or IP address literal
includeIpv4 bool Look for IPv4 addresses (default: true)
includeIpv6 bool Look for IPv6 addresses (default: true)

Returns: Result<Vector<IpAddress>> — Addresses of the host, IPv4 ones first, never empty