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.

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

Coercible to/from a domain, but its presentation form is canonical (lower case) and has no terminating ., unless this is the root domain.

Equality and order are on the wire form, but are case-insensitive.

Coerce a Host to a Domain.

Coerce a Domain to a Host.

Coercible to/from a domain, but its presentation form uses the @ sign as the separator after the first label, and does not escape literal . characters within the first label. The second and subsequent labels are canonicalised to lower-case. No terminating . is appended unless this is the root domain.

Equality and order are on the wire form, but are case-insensitive.

Coerce an Mbox to a Domain.

Coerce a Domain to an Mbox. This changes the presentation form to one in which the first label is separated from the rest by an '@' character, and any dots in the first label remain unescaped. No period is appended after the last label. The same form can be parsed by:

• mbLit8
• makeMbox8
• makeMbox8Str
• mbLit
• decodePresentationMbox

provided the first label (localpart) uses only 7-bit ASCII characters. Mailboxes with non-ASCII localparts (EAI addresses) must be valid UTF-8 and can only be parsed by decodePresentationMbox or mbLit, but the presentation form of Mbox does escapes all non-ASCII bytes in \DDD decimal form, and would be rejected by all the above parsers. A UTF-8 presentation form that respects EAI addresses is not yet available, and would probably want a new EAIMbox data type.

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.

Template-Haskell typed splice for a compile-time mailbox literal. Packs the source String literal as Text (rejecting inputs longer than 1024 bytes) and hands it to decodePresentationMbox: the localpart is parsed locally with DNS-style escapes, and the post-separator domain text is passed to the caller-supplied parser. An invalid literal (localpart failure or domain-parser failure or combined-length failure) becomes a compile-time error.

The parser argument has the same shape as dnLit's: Text -> Either e ShortByteString. The user can pass the same parser they pass to dnLit (typically a composition with idna2008), and the mailbox literal inherits the same IDN policy for the domain portion of the name. See dnLit for the standard idioms.

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.

Template-Haskell splice for literal mailbox names. Example:

mbox :: Domain
mbox = $$(mbLit8 "hostmaster@example.org")

Byte-level all the way through: the localpart and the domain portion are both parsed by makeMbox8Str, which treats the input as opaque 8-bit master-file text. For EAI/UTF-8 localpart semantics use mbLit with an idna2008-style Text parser.

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.

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.

Parse a presentation-form mailbox into a Domain.

The input is split at the first unescaped '@' if any; otherwise at the first unescaped '.'; otherwise the entire input is the localpart and the resulting Domain has a single non-root label. A separator present but followed by empty domain text (e.g. "postmaster@" or "postmaster.") is treated the same way as if the separator were absent: the localpart is one label, the domain part is the root domain.

Following EAI semantics (RFC 6532), the localpart's wire bytes are either pure 7-bit ASCII or a well-formed UTF-8 sequence. The localpart decoder:

• Copies unescaped Text bytes verbatim into the wire form. A Text is already valid UTF-8, so the bytes for one codepoint are 1, 2, 3 or 4 bytes long depending on the codepoint; no decoding or validation is needed.
• \DDD (three ASCII decimal digits, 0..127) emits the single ASCII byte with that value. Values >= 128 are rejected.
• \X (any other single character) emits X as a single ASCII byte; X's codepoint must be < 0x80.

The rules above apply only to the localpart -- the first label of the mailbox name. The post-separator Text (if any) is handed verbatim to the caller-supplied domain parser, which decodes any remaining labels.

The parser's output is validated to be a wire-form ShortByteString that wireToDomain accepts. If length limits permit, the decoded localpart is prepended to form the combined Domain.

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.

Failure modes for the byte-level 8-bit presentation-form parser. Intentionally coarse and position-free. Callers that need richer diagnostics should use the idna2008 parser.

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"]

Construct a Domain object directly from a /presentation form/ ByteString representing a mailbox. As a convenience to users, the separator between the first and remaining labels is optionally the first unescaped '@' character, in which case prior '.' characters in the first label do not need to be escaped.

The first label must not contain any non-ASCII bytes (above 127), or an error (Left) is returned.

The toMbox function can be used to coerce the resulting Domain to an Mbox object whose presentation form uses an '@' between the first and remaining labels and does not escape dots in the first label.

Example

>>> import qualified Data.ByteString.Char8 as BC
>>> dn = makeMbox8 $ BC.pack "john.smith@acme.example"
>>> dn
Right "john\\.smith.acme.example."
>>> toLabels <$> dn
Right ["john.smith","acme","example"]
>>> toMbox <$> dn
Right "john.smith@acme.example"

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

The first label must not contain any non-ASCII bytes (above 127), or an error (Left) is returned.

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

Example

>>> dn = makeMbox8Str "john.smith@acme.example"
>>> dn
Right "john\\.smith.acme.example."
>>> toLabels <$> dn
Right ["john.smith","acme","example"]
>>> toMbox <$> dn
Right "john.smith@acme.example"

Canonicalise a Domain to lower-case form.

Given two Domains attempt to construct a new new domain consisting of the labels of the first, followed by the labels of the second. Fails (returns Nothing) if the result would be too long.

Attempt to prepend the given label to the given domain, provided the label length is 63 bytes or less, and the resulting domain is not too long.

Given a Domain, return a tuple containing its first unescaped label as a ShortByteString and the remainder of the Domain after removing the first label. Returns Nothing for the root domain.

Given a 'Domain/, return its label count. The root domain has zero labels.

>>> labelCount $$(dnLit8 "example.org")
2

>>> toLabels $$(mbLit8 "first.last@example.org")
3

Given a constituent list of raw unescaped labels, construct the corresponding wire form domain name. No label may be empty or longer than 63 bytes, and the number of labels + the sum of label lengths must not exceed 254. The return value is Nothing if the length constraints are violated.

fromLabels (toLabels dn) == Just dn

Given a 'Domain/, return its constituent list of raw unescaped labels, most-significant (TLD) label last.

>>> toLabels $$(dnLit8 "example.org")
["example","org"]

>>> toLabels $$(mbLit8 "first.last@example.org")
["first.last","example","org"]

Given a Domain, return its constituent list of raw unescaped labels in reverse order, with the TLD first.

>>> revLabels $$(dnLit8 "example.org")
["org","example"]

>>> revLabels $$(mbLit8 "first.last@example.org")
["org","example","first.last"]

Return the longest common suffix of two input domains.

Encode a Domain name without name compression

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

Return the wire form of a Domain name as a ByteString

Does the given Domain name consist entirely of LDH labels?

Is the given ShortByteString a valid non-empty LDH label?

Case-insensitive comparison of the wire forms of domains.

Case-insensitive equality of domain names.

Canonical name order: https://datatracker.ietf.org/doc/html/rfc4034#section-6.1. For sorting lists of more than a few elements, it may be best to perform a decorate, sort, undecorate via sortDomains.

Perform a decorate, sort, undecorate sort to return a list of domains in canonical order.