User-supplied resolver configuration. Carries the caller's choices: where nameservers come from, the per-attempt timeout and retry budget, default QueryControls, and any user-registered RR-type / EDNS option codecs. Built-in defaults are not stored here — they are merged into the effective configuration only when makeResolvSeed produces a ResolvSeed.

Default resolver configuration, with nameserver list from /etc/resolv.conf and no user-registered codec extensions.

Configuration file name, or explicit list of addresses/hostnames.

Nameserver address string or hostname, with optional port.

Resolved, immutable resolver state built by makeResolvSeed from a ResolverConf. Combines the user's choices with the library's built-in defaults: resolved nameserver addresses, and the effective RR-type and EDNS-option codec maps with user-registered code points overriding the library defaults (except at a small set of protected code points, where attempted user overrides are silently ignored).

A ResolvSeed is safe to share across threads; each query-issuing thread should call withResolver on the same seed to obtain its own per-thread Resolver handle.

Build a ResolvSeed from a ResolverConf. The seed is immutable and safely shared across threads; each thread then calls withResolver to obtain its own Resolver.

The configured nameservers are resolved to socket addresses, and the user's codec registrations (from registerRRtype, extendRRwithType and registerEdnsOption) are combined with the library's built-in codec set. At each RR-type or EDNS option code point, the user-registered codec takes precedence over the library default — except at a small set of protected code points (e.g. the SVCB mandatory key), where any attempted user override is silently ignored.

Returns Left err if the configured nameservers cannot be resolved or the configuration file cannot be parsed.

Example:

>>> seed <- makeResolvSeed defaultResolvConf >>= either throwIO pure

Internal DNS Resolver handle, obtained via withResolver. Must not be used concurrently in multiple threads.

Provide a Resolver to the supplied action. Concurrent use of a single Resolver is not supported: the handle carries internal mutable state and the library makes no soundness guarantees if it is shared across threads. Programs that issue queries from multiple threads must call withResolver once per worker thread (typically inside forkIO) to obtain a separate handle. The ResolvSeed itself is immutable and is the right object to share across threads.

The action runs in plain IO; DNS-protocol errors from individual lookups appear in the Either DNSError a return shape of each lookup function inside the action. This function does not itself produce or propagate DNSErrors.

Shape of a typed lookup: a Resolver and a query Domain produce either a list of answers, or a DNSError. An empty list means that either the name exists and has no records of the queried type (NODATA), or the name does not exist (NXDOMAIN). Both are non-error outcomes.

Given a DNSMessage return answer RRs that match its question, possibly after chasing CNAME aliases within the answer section of the message.

Perform a raw lookup returning the full DNSMessage or a DNSError. See lookupRawCtl for the variant that takes per-call query controls.

Perform a raw lookup with per-call QueryControls overrides, returning the full DNSMessage or a DNSError. The supplied controls are merged into the resolver's ambient query controls: only the flag and EDNS bits specified in the controls affect the outgoing query, the rest are inherited from the resolver configuration. Use lookupAnswers (or the per-RRtype Lookup functions) when you want only the answer RRs for the requested name and type, rather than the entire response DNSMessage.

Perform the requested query and return the answer RRs from the response, or a DNSError carrying the RCODE for error responses. The QueryControls argument carries per-call tweaks; it is merged onto the resolver's ambient query controls, so callers only need to specify the flag and EDNS bits they want to change, the rest are inherited from the resolver configuration.

Note that NXDOMAIN is not a lookup error. An empty list of RRs is returned for both NODATA and NXDOMAIN.

If the nameserver's response does not include any RRs matching query name and type, but does include a CNAME record for the requested name, the response is (recursively) rescanned for records matching that name and type instead. Note, no additional queries are issued if the final CNAME found does not lead to any record of the desired record type.

The returned RRs may include covering DNSSEC signatures when the DOflag is set as part of the QueryControls, and the response was signed.

The presence of RRSIG records does not however imply that the response was validated by the resolver. For that one would typically use a trusted DNSSEC-validating local (loopback) resolver, to which the network path is immune to potential active attacks, and inspect the ADflag in the response message.

The full response DNSMessage can be obtained via lookupRawCtl.

IPv4 addresses of query domain.

IPv6 addresses of query domain.

MX RData of query domain.

Nameservers of query domain.

CNAMEs of query domain (should be at most one).

PTR names of query domain.

TXT RData of query domain. Applications typically concatenate each list of character strings into a single combined value.

SOA RData of query domain.

SRV RData of query domain.

TLSA RData of query domain.

HTTPS RData of query domain.

This type holds the wire form of fully-qualified DNS domain names encoded as A-labels.

The encoding of valid domain names to presentation form (the Presentable instance) performs any required escaping of special characters to ensure lossless round-trip encoding and decoding of valid DNS names, and compatibility with the standard zone file format. Valid names are not limited to the letter-digit-hyphen (LDH) syntax of hostnames, all 8-bit characters are allowed in DNS names, subject to the 63-byte limit on wire form label length and 255-byte limit on the wire form domain name (including the terminal empty label).

Equality and comparison are based on the wire-form and are case-sensitive. The Host newtype implements case-insensitive equality and comparison over the same wire-form bytes. The toHost and fromHost functions implement coercions between the two types.

Template-Haskell typed splice for a compile-time Domain literal. The caller supplies a parser of type Text -> Either e ShortByteString; dnLit packs the source String literal as Text, runs the parser at compile time, additionally checks the bytes via wireToDomain, and embeds the resulting Domain as a constant. An invalid literal (parser failure or wire-shape failure) becomes a compile-time error.

The dnsbase library deliberately does not bundle a domain parser; users compose a parser of their choice and pass it in. The natural source of validating parsers is the idna2008 package, whose parsers already operate on Text. Template-Haskell staging forbids referring to a same-module top-level binding from inside the splice, so the parser must either be defined in an imported module or bound by a let inside the splice; for a single-call site the latter is the more compact form:

import qualified Text.IDNA2008 as I

example :: Domain
example = $$(let parser = fmap I.wireBytesShort . I.mkDomain
              in dnLit parser "www.example.org")

mkDomain runs strict IDNA2008 with default label forms and no mappings, returning just the validated idna2008 library's Domain object. The I.wireBytesShort function extracts the wire form bytes needed by dnLit.

For looser policies (mappings, emoji domain tolerance, etc.) use parseDomainOpt with an explicit LabelFormSet and IDNAOpts, and discard the LabelInfo half of its result.

Hoisting the parser into a separate module avoids retyping the composition at every literal:

-- in MyDomainParsers.hs
strictParser :: Text -> Either I.IdnaError ShortByteString
strictParser = fmap I.wireBytesShort . I.mkDomain

-- in any module that imports MyDomainParsers
example :: Domain
example = $$(dnLit strictParser "www.example.org")

The source literal is converted to Text before the parser is invoked; literals whose UTF-8 byte length exceeds 1024 are rejected as invalid without consulting the parser. The emitted splice is a constant Domain value (the wire-form ShortByteString is materialised once from its compile-time Addr# literal on first evaluation); the splice itself runs no runtime IDNA code, and the caller's binary carries no idna2008 dependency unless the user imports it themselves.

Decode a domain in presentation form. The caller supplies the parser; this entry point validates the parser's output as a wire-form ShortByteString that wireToDomain accepts.

When the parser returns an error e, the return value is Left (Just e). If a buggy parser produces an invalid wire form, the return value is Left Nothing.

Template-Haskell splice for literal Domain names that are validated and converted from presentation form to wire form at compile-time. Example:

domain :: Domain
domain = $$(dnLit8 "example.org")

This is the byte-level path: it accepts any 8-bit master-file text but performs no IDN processing. For IDN-aware literals (RFC 5890+, Punycode A-label encoding) use dnLit with a parser from the companion idna2008 package.

Construct a Domain object directly from a presentation form ByteString.

The bytes are not treated as UTF-8 content, and IDNA processing does not apply. Backslash-escape encoding aside, each 8-bit byte in the input is copied verbatim into the wire-form domain. For Unicode IDN domain support, see the parsers in the idna2008 package.

Example

>>> import qualified Data.ByteString.Char8 as BC
>>> dn = makeDomain8 $ BC.pack "www.corp.acme.example"
>>> dn
Right "www.corp.acme.example."
>>> toLabels <$> dn
Right ["www","corp","acme","example"]

Same as makeDomain8, but the input is a String, and an error (Left) is also returned if any of the input string's characters are outside the 8-bit range.

Note that UTF-8 encoding of names in the Latin-1 alphabet might still produce surprising results. For parsing IDN domain names, see the idna2008 package.

Example

>>> dn = makeDomain8Str "www.corp.acme.example"
>>> dn
Right "www.corp.acme.example."
>>> toLabels <$> dn
Right ["www","corp","acme","example"]

The wire form of a domain name, including the zero-valued length byte of the terminal empty label.

Validating import of a wire-form ShortByteString as a Domain. Returns Just iff the bytes are a well-formed DNS domain on the wire:

• total length in 1..255,
• every label length byte in 1..63 except the trailing zero-byte root label,
• label boundaries align exactly with the buffer end -- i.e. the terminating empty label's NUL length-byte is the last byte, and there is no truncation or trailing garbage.

Suitable for receiving bytes the caller cannot prove well-formed (e.g. labels handed back by a foreign library or another package). Wire-form bytes that come straight from the decoder in Net.DNSBase.Decode.Domain are already validated and do not need to round-trip through this check.

DNS Resource Record RFC1035 3.2.1

                                1  1  1  1  1  1
  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                                               |
/                                               /
/                      NAME                     /
|                                               |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                      TYPE                     |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                     CLASS                     |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                      TTL                      |
|                                               |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                   RDLENGTH                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--|
/                     RDATA                     /
/                                               /
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

The TYPE field is implicit in the polymorphic rrData.

An RRSet is uniquely idenfified by a name, type, class triple.

Wrapper around any concrete KnownRData type.

Its presentation form includes both the type and the value, space-separated. The underlying concrete types present just their values.

Recover a typed RR payload from the existential RData wrapper. Returns Just x when the dynamic payload's type matches the caller's expected type a, and Nothing otherwise.

The target type is selected by the result-side pattern; once there's a concrete constructor on the Just side, the KnownRData a constraint is resolved without an explicit type ascription. A typical use is a view-pattern dispatch that handles two or more RR types at once:

evalIP :: (IP -> a) -> RData -> Maybe a
evalIP f (fromRData -> Just (T_A    ip)) = Just $! f (IPv4 ip)
evalIP f (fromRData -> Just (T_AAAA ip)) = Just $! f (IPv6 ip)
evalIP _ _                               = Nothing

fromRData is the right tool when the value in hand is already an RData. If you instead have an RR (or a list of them, as returned by lookupAnswers), rrDataCast is the convenience composition fromRData . rrData. And monoRData performs the filter-and-cast over a Foldable container in one step.

DNS Resource Record type numbers. The Presentable instance displays the standard presentation form of the type name for known types, or else TYPEnnnnn for a generic type number nnnnn.

DNS query or resource record class.

DNS query or response header, here consisting of just the query ID and the flags, sans the record counts, which are implicit in the corresponding lists, RFC1035 4.1.1, updated by RFC2535.

The basic DNS header contains the following fields:

                                1  1  1  1  1  1
  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                      ID                       |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|QR|   Opcode  |AA|TC|RD|RA| Z|AD|CD|   RCODE   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    QDCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    ANCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    NSCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    ARCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

The basic 4-bit RCODE is augmented with 8 bits from the EDNS header, forming a single extended 12-bit RCODE, with the basic RCODE as its least-significant 4 bits. Similarly, the extended 32-bit DNSFlags are a combination of the basic flags above with 16 more flag bits from the EDNS header, with the basic flags in the low 16-bits (with the Opcode and RCODE bits always cleared).

DNS message format for queries and replies, RFC1035 4.1

 +---------------------+
 |        Header       |
 +---------------------+
 |       Question      | the question for the name server
 +---------------------+
 |        Answer       | RRs answering the question
 +---------------------+
 |      Authority      | RRs pointing toward an authority
 +---------------------+
 |      Additional     | RRs holding additional information
 +---------------------+

DNS API errors.

The A resource record (RFC 1035 section 3.4.1) — a 32-bit IPv4 address transmitted as four bytes in network order. The derived Ord is numeric IPv4 order, which agrees with canonical RR-content ordering (RFC 4034 section 6.2).

See T_aaaa for the IPv6-family parallel, and evalIP for a helper that handles either uniformly.

The AAAA resource record (RFC 3596 section 2.1) — a 128-bit IPv6 address transmitted as sixteen bytes in network order. The derived Ord is numeric IPv6 order, which agrees with canonical RR-content ordering (RFC 4034 section 6.2).

See T_a for the IPv4-family parallel, and evalIP for a helper that handles either uniformly.

The MX resource record (RFC 1035 section 3.3.9) — a mail exchanger for the owner name: a 16-bit preference (lower is preferred) and a Domain naming the exchange host.

 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 |                  PREFERENCE                   |
 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 /                   EXCHANGE                    /
 /                                               /
 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

The exchange field is subject to wire-form name compression on encode (RFC 3597 section 4) and canonicalises to lower case (RFC 4034 section 6.2). The Eq and Ord instances compare the exchange in canonical wire form (via equalWireHost / compareWireHost), so Ord is canonical.

A name that resolves to a CNAME should not be used in the exchange field (RFC 2181 section 10.3, RFC 5321 section 5.1).

The SRV resource record (RFC 2782) — names the location of a service: 16-bit priority, weight, and port, plus a Domain naming the target host.

The target field is not subject to wire-form name compression on encode (RFC 3597 section 4) but compression is tolerated on decode. It canonicalises to lower case (RFC 4034 section 6.2). The Eq and Ord instances compare the target in canonical wire form (via equalWireHost / compareWireHost), so Ord is canonical.

The TXT resource record (RFC 1035 section 3.3.14) — a non-empty list of byte-strings, each at most 255 bytes long. Most TXT-record conventions (SPF, DKIM, DMARC, ...) concatenate the strings on read, but the wire format preserves the boundaries.

The constructor does not enforce the per-string 255-byte limit; encoding fails if any individual string exceeds it. Values decoded from wire form are always within the limit by construction.

The Ord instance compares the strings as DNS character-strings (length-prefixed lexicographic), agreeing with the canonical wire-form ordering of RFC 4034 section 6.2.

X_domain specialised to PTR records.

Domain-name pointer, typically used for reverse mapping (RFC 1035 section 3.3.12).

X_svcb specialised to HTTPS records.

Record pattern synonym viewing the shared X_svcb record as an HTTPS service-binding record (RFC 9460). Fields: httpsPriority, httpsTarget, httpsParamValues.

Query controls consisting of an endomorphism over FlagOps to modify DNS flag bits, and an EdnsControls structure to configure EDNS behavior.

Constitutes a Monoid with left-biased mappend operation

RD (Recursion Desired) - This bit may be set in a query and is copied into the response. If RD is set, it directs the name server to pursue the query recursively. Authoritative servers may refuse recursive queries, and, conversely, iterative resolvers may refuse non-recursive queries.

AD (Authentic Data) bit - RFC4035, Section 3.2.3. See also RFC6840, Section 5.8

CD (Checking Disabled) bit - RFC4035, Section 3.2.2.

DO (DNSSEC OK) bit - RFC3225, Section 3, RFC6891, Section-6.1.4.

Abstract DNS Resource Record (type-specific) data.

The decoding, encoding and presentation functions are responsible for just the value, presentation of the associated RR type defaults to the built-in names, for novel types override rdTypePres.

The Show instance is typically derived, and will output the type constructor (its output strives to produce syntactically valid Haskell values), in contrast with Presentable which produces RFC-standard presentation forms.