-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | DNS library in Haskell
--   
--   A thread-safe DNS library for both clients and servers written in pure
--   Haskell.
@package dns
@version 4.0.0


-- | Data types for DNS Query and Response. For more information, see
--   <a>http://www.ietf.org/rfc/rfc1035</a>.
module Network.DNS.Types

-- | Raw data format for resource records.
data ResourceRecord
ResourceRecord :: !Domain -> !TYPE -> !CLASS -> !TTL -> !RData -> ResourceRecord

-- | Name
[rrname] :: ResourceRecord -> !Domain

-- | Resource record type
[rrtype] :: ResourceRecord -> !TYPE

-- | Resource record class
[rrclass] :: ResourceRecord -> !CLASS

-- | Time to live
[rrttl] :: ResourceRecord -> !TTL

-- | Resource data
[rdata] :: ResourceRecord -> !RData

-- | Type alias for resource records in the answer section.
type Answers = [ResourceRecord]

-- | Type alias for resource records in the answer section.
type AuthorityRecords = [ResourceRecord]

-- | Type for resource records in the additional section.
type AdditionalRecords = [ResourceRecord]

-- | This type holds the <i>presentation form</i> of fully-qualified DNS
--   domain names encoded as ASCII A-labels, with '.' separators between
--   labels. Non-printing characters are escaped as <tt>\DDD</tt> (a
--   backslash, followed by three decimal digits). The special characters:
--   <tt> ", $, (, ), ;, @,</tt> and <tt>\</tt> are escaped by prepending a
--   backslash. The trailing '.' is optional on input, but is recommended,
--   and is always added when decoding from <i>wire form</i>.
--   
--   The encoding of domain names to <i>wire form</i>, e.g. for
--   transmission in a query, requires the input encodings to be valid,
--   otherwise a <a>DecodeError</a> may be thrown. Domain names received in
--   wire form in DNS messages are escaped to this presentation form as
--   part of decoding the <a>DNSMessage</a>.
--   
--   This form is ASCII-only. Any conversion between A-label
--   <a>ByteString</a>s, and U-label <tt>Text</tt> happens at whatever
--   layer maps user input to DNS names, or presents <i>friendly</i> DNS
--   names to the user. Not all users can read all scripts, and
--   applications that default to U-label form should ideally give the user
--   a choice to see the A-label form. Examples:
--   
--   <pre>
--   www.example.org.           -- Ordinary DNS name.
--   _25._tcp.mx1.example.net.  -- TLSA RR initial labels have _ prefixes.
--   \001.exotic.example.       -- First label is Ctrl-A!
--   just\.one\.label.example.  -- First label is "just.one.label"
--   </pre>
type Domain = ByteString

-- | Resource record class.
type CLASS = Word16

-- | Resource record class for the Internet.
classIN :: CLASS

-- | Time to live in second.
type TTL = Word32

-- | Types for resource records.
data TYPE

-- | IPv4 address
pattern A :: TYPE

-- | An authoritative name serve
pattern NS :: TYPE

-- | The canonical name for an alias
pattern CNAME :: TYPE

-- | Marks the start of a zone of authority
pattern SOA :: TYPE

-- | A null RR (EXPERIMENTAL)
pattern NULL :: TYPE

-- | A domain name pointer
pattern PTR :: TYPE

-- | Mail exchange
pattern MX :: TYPE

-- | Text strings
pattern TXT :: TYPE

-- | IPv6 Address
pattern AAAA :: TYPE

-- | Server Selection (RFC2782)
pattern SRV :: TYPE

-- | DNAME (RFC6672)
pattern DNAME :: TYPE

-- | OPT (RFC6891)
pattern OPT :: TYPE

-- | Delegation Signer (RFC4034)
pattern DS :: TYPE

-- | RRSIG (RFC4034)
pattern RRSIG :: TYPE

-- | NSEC (RFC4034)
pattern NSEC :: TYPE

-- | DNSKEY (RFC4034)
pattern DNSKEY :: TYPE

-- | NSEC3 (RFC5155)
pattern NSEC3 :: TYPE

-- | NSEC3PARAM (RFC5155)
pattern NSEC3PARAM :: TYPE

-- | TLSA (RFC6698)
pattern TLSA :: TYPE

-- | Child DS (RFC7344)
pattern CDS :: TYPE

-- | DNSKEY(s) the Child wants reflected in DS (RFC7344)
pattern CDNSKEY :: TYPE

-- | Child-To-Parent Synchronization (RFC7477)
pattern CSYNC :: TYPE

-- | Zone transfer (RFC5936)
pattern AXFR :: TYPE

-- | A request for all records the server/cache has available
pattern ANY :: TYPE

-- | Certification Authority Authorization (RFC6844)
pattern CAA :: TYPE

-- | From type to number.
fromTYPE :: TYPE -> Word16

-- | From number to type.
toTYPE :: Word16 -> TYPE

-- | Raw data format for each type.
data RData

-- | IPv4 address
RD_A :: IPv4 -> RData

-- | An authoritative name serve
RD_NS :: Domain -> RData

-- | The canonical name for an alias
RD_CNAME :: Domain -> RData

-- | Marks the start of a zone of authority
RD_SOA :: Domain -> Mailbox -> Word32 -> Word32 -> Word32 -> Word32 -> Word32 -> RData

-- | NULL RR (EXPERIMENTAL, RFC1035).
RD_NULL :: ByteString -> RData

-- | A domain name pointer
RD_PTR :: Domain -> RData

-- | Mail exchange
RD_MX :: Word16 -> Domain -> RData

-- | Text strings
RD_TXT :: ByteString -> RData

-- | IPv6 Address
RD_AAAA :: IPv6 -> RData

-- | Server Selection (RFC2782)
RD_SRV :: Word16 -> Word16 -> Word16 -> Domain -> RData

-- | DNAME (RFC6672)
RD_DNAME :: Domain -> RData

-- | OPT (RFC6891)
RD_OPT :: [OData] -> RData

-- | Delegation Signer (RFC4034)
RD_DS :: Word16 -> Word8 -> Word8 -> ByteString -> RData

-- | DNSSEC signature
RD_RRSIG :: RD_RRSIG -> RData

-- | DNSSEC denial of existence NSEC record
RD_NSEC :: Domain -> [TYPE] -> RData

-- | DNSKEY (RFC4034)
RD_DNSKEY :: Word16 -> Word8 -> Word8 -> ByteString -> RData

-- | DNSSEC hashed denial of existence (RFC5155)
RD_NSEC3 :: Word8 -> Word8 -> Word16 -> ByteString -> ByteString -> [TYPE] -> RData

-- | NSEC3 zone parameters (RFC5155)
RD_NSEC3PARAM :: Word8 -> Word8 -> Word16 -> ByteString -> RData

-- | TLSA (RFC6698) RD_CDS RD_CDNSKEY RD_CSYNC
RD_TLSA :: Word8 -> Word8 -> Word8 -> ByteString -> RData

-- | Unknown resource data
UnknownRData :: ByteString -> RData

-- | RRSIG representation.
--   
--   As noted in <a>Section 3.1.5 of RFC 4034</a> the RRsig inception and
--   expiration times use serial number arithmetic. As a result these
--   timestamps <i>are not</i> pure values, their meaning is
--   time-dependent! They depend on the present time and are both at most
--   approximately +/-68 years from the present. This ambiguity is not a
--   problem because cached RRSIG records should only persist a few days,
--   signature lifetimes should be *much* shorter than 68 years, and key
--   rotation should result any misconstrued 136-year-old signatures fail
--   to validate. This also means that the interpretation of a time that is
--   exactly half-way around the clock at <tt>now +/-0x80000000</tt> is not
--   important, the signature should never be valid.
--   
--   The upshot for us is that we need to convert these *impure* relative
--   values to pure absolute values at the moment they are received from
--   from the network (or read from files, ... in some impure I/O context),
--   and convert them back to 32-bit values when encoding. Therefore, the
--   constructor takes absolute 64-bit representations of the inception and
--   expiration times.
--   
--   The <a>dnsTime</a> function performs the requisite conversion.
data RD_RRSIG
RDREP_RRSIG :: !TYPE -> !Word8 -> !Word8 -> !Word32 -> !Int64 -> !Int64 -> !Word16 -> !Domain -> !ByteString -> RD_RRSIG

-- | RRtype of RRset signed
[rrsigType] :: RD_RRSIG -> !TYPE

-- | DNSKEY algorithm
[rrsigKeyAlg] :: RD_RRSIG -> !Word8

-- | Number of labels signed
[rrsigNumLabels] :: RD_RRSIG -> !Word8

-- | Maximum origin TTL
[rrsigTTL] :: RD_RRSIG -> !Word32

-- | Time last valid
[rrsigExpiration] :: RD_RRSIG -> !Int64

-- | Time first valid
[rrsigInception] :: RD_RRSIG -> !Int64

-- | Signing key tag
[rrsigKeyTag] :: RD_RRSIG -> !Word16

-- | Signing domain
[rrsigZone] :: RD_RRSIG -> !Domain

-- | Opaque signature
[rrsigValue] :: RD_RRSIG -> !ByteString

-- | Given a 32-bit circle-arithmetic DNS time, and the current absolute
--   epoch time, return the epoch time corresponding to the DNS timestamp.
dnsTime :: Word32 -> Int64 -> Int64

-- | DNS message format for queries and replies.
data DNSMessage
DNSMessage :: !DNSHeader -> EDNSheader -> [Question] -> Answers -> AuthorityRecords -> AdditionalRecords -> DNSMessage

-- | Header with extended <a>RCODE</a>
[header] :: DNSMessage -> !DNSHeader

-- | EDNS pseudo-header
[ednsHeader] :: DNSMessage -> EDNSheader

-- | The question for the name server
[question] :: DNSMessage -> [Question]

-- | RRs answering the question
[answer] :: DNSMessage -> Answers

-- | RRs pointing toward an authority
[authority] :: DNSMessage -> AuthorityRecords

-- | RRs holding additional information
[additional] :: DNSMessage -> AdditionalRecords

-- | Construct a complete query <a>DNSMessage</a>, by combining the
--   <a>defaultQuery</a> template with the specified <a>Identifier</a>, and
--   <a>Question</a>. The <a>QueryControls</a> can be <a>mempty</a> to
--   leave all header and EDNS settings at their default values, or some
--   combination of overrides. A default set of overrides can be enabled
--   via the <a>resolvQueryControls</a> field of <a>ResolvConf</a>.
--   Per-query overrides are possible by using <a>loookupRawCtl</a>.
makeQuery :: Identifier -> Question -> QueryControls -> DNSMessage

-- | A query template with <a>QueryControls</a> overrides applied, with
--   just the <a>Question</a> and query <a>Identifier</a> remaining to be
--   filled in.
makeEmptyQuery :: QueryControls -> DNSMessage

-- | A <a>DNSMessage</a> template for queries with default settings for the
--   message <a>DNSHeader</a> and <a>EDNSheader</a>. This is the initial
--   query message state, before customization via <a>QueryControls</a>.
defaultQuery :: DNSMessage

-- | Query controls form a <a>Monoid</a>, as with function composition, the
--   left-most value has the last say. The <a>Monoid</a> is generated by
--   two sets of combinators, one that controls query-related DNS header
--   flags, and another that controls EDNS features.
--   
--   The header flag controls are: <a>rdFlag</a>, <a>adFlag</a> and
--   <a>cdFlag</a>.
--   
--   The EDNS feature controls are: <a>doFlag</a>, <a>ednsEnabled</a>,
--   <a>ednsSetVersion</a>, <a>ednsSetUdpSize</a> and
--   <a>ednsSetOptions</a>. When EDNS is disabled, all the other
--   EDNS-related controls have no effect.
--   
--   <b>Example:</b> Disable DNSSEC checking on the server, and request
--   signatures and NSEC records, perhaps for your own independent
--   validation. The UDP buffer size is set large, for use with a local
--   loopback nameserver on the same host.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   mconcat [ adFlag FlagClear
--           , cdFlag FlagSet
--           , doFlag FlagSet
--           , ednsSetUdpSize (Just 8192) -- IPv4 loopback server?
--           ]
--   :}
--   ad:0,cd:1,edns.udpsize:8192,edns.dobit:1
--   </pre>
--   
--   <b>Example:</b> Use EDNS version 1 (yet to be specified), request
--   nameserver ids from the server, and indicate a client subnet of
--   "192.0.2.1/24".
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; let emptyNSID = ""
--   
--   &gt;&gt;&gt; let mask = 24
--   
--   &gt;&gt;&gt; let ipaddr = read "192.0.2.1"
--   
--   &gt;&gt;&gt; :{
--   mconcat [ ednsSetVersion (Just 1)
--           , ednsSetOptions (ODataAdd [OD_NSID emptyNSID])
--           , ednsSetOptions (ODataAdd [OD_ClientSubnet mask 0 ipaddr])
--           ]
--   :}
--   edns.version:1,edns.options:[NSID,ClientSubnet]
--   </pre>
data QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the RD bit.
--   
--   <pre>
--   &gt;&gt;&gt; rdFlag FlagClear
--   rd:0
--   </pre>
rdFlag :: FlagOp -> QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the AD bit.
--   
--   <pre>
--   &gt;&gt;&gt; adFlag FlagSet
--   ad:1
--   </pre>
adFlag :: FlagOp -> QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the CD bit.
--   
--   <pre>
--   &gt;&gt;&gt; cdFlag FlagSet
--   cd:1
--   </pre>
cdFlag :: FlagOp -> QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the <a>EDNS</a>
--   DnssecOk (DO) bit.
--   
--   <pre>
--   &gt;&gt;&gt; doFlag FlagSet
--   edns.dobit:1
--   </pre>
doFlag :: FlagOp -> QueryControls

-- | Generator of <a>QueryControls</a> that enables or disables EDNS
--   support. When EDNS is disabled, the rest of the <a>EDNS</a> controls
--   are ignored.
--   
--   <pre>
--   &gt;&gt;&gt; ednsHeader $ makeEmptyQuery $ ednsEnabled FlagClear &lt;&gt; doFlag FlagSet
--   NoEDNS
--   </pre>
ednsEnabled :: FlagOp -> QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the <a>EDNS</a>
--   version. A value of <a>Nothing</a> makes no changes, while <a>Just</a>
--   <tt>v</tt> sets the EDNS version to <tt>v</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; ednsSetVersion (Just 1)
--   edns.version:1
--   </pre>
ednsSetVersion :: Maybe Word8 -> QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the <a>EDNS</a> UDP
--   buffer size. A value of <a>Nothing</a> makes no changes, while
--   <a>Just</a> <tt>n</tt> sets the EDNS UDP buffer size to <tt>n</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; ednsSetUdpSize (Just 2048)
--   edns.udpsize:2048
--   </pre>
ednsSetUdpSize :: Maybe Word16 -> QueryControls

-- | Generator of <a>QueryControls</a> that adjusts the list of <a>EDNS</a>
--   options.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; ednsSetOptions (ODataAdd [OD_NSID ""])
--   edns.options:[NSID]
--   </pre>
ednsSetOptions :: ODataOp -> QueryControls

-- | Boolean flag operations. These form a <a>Monoid</a>. When combined via
--   <a>mappend</a>, as with function composition, the left-most value has
--   the last say.
--   
--   <pre>
--   &gt;&gt;&gt; mempty :: FlagOp
--   FlagKeep
--   
--   &gt;&gt;&gt; FlagSet &lt;&gt; mempty
--   FlagSet
--   
--   &gt;&gt;&gt; FlagClear &lt;&gt; FlagSet &lt;&gt; mempty
--   FlagClear
--   
--   &gt;&gt;&gt; FlagReset &lt;&gt; FlagClear &lt;&gt; FlagSet &lt;&gt; mempty
--   FlagReset
--   </pre>
data FlagOp

-- | Set the flag to 1
FlagSet :: FlagOp

-- | Clear the flag to 0
FlagClear :: FlagOp

-- | Reset the flag to its default value
FlagReset :: FlagOp

-- | Leave the flag unchanged
FlagKeep :: FlagOp

-- | The default EDNS Option list is empty. We define two operations, one
--   to prepend a list of options, and another to set a specific list of
--   options.
data ODataOp

-- | Add the specified options to the list.
ODataAdd :: [OData] -> ODataOp

-- | Set the option list as specified.
ODataSet :: [OData] -> ODataOp

-- | Default response. When responding to EDNS queries, the response must
--   either be an EDNS response, or else FormatErr must be returned. The
--   default response message has EDNS disabled (<a>ednsHeader</a> set to
--   <a>NoEDNS</a>), it should be updated as appropriate.
--   
--   Do not explicitly add OPT RRs to the additional section, instead let
--   the encoder compute and add the OPT record based on the EDNS
--   pseudo-header.
--   
--   The <a>RCODE</a> in the <a>DNSHeader</a> should be set to the
--   appropriate 12-bit extended value, which will be split between the
--   primary header and EDNS OPT record during message encoding (low 4 bits
--   in DNS header, high 8 bits in EDNS OPT record). See <a>EDNSheader</a>
--   for more details.
defaultResponse :: DNSMessage

-- | Construct a query response <a>DNSMessage</a>.
makeResponse :: Identifier -> Question -> Answers -> DNSMessage

-- | Raw data format for the header of DNS Query and Response.
data DNSHeader
DNSHeader :: !Identifier -> !DNSFlags -> DNSHeader

-- | Query or reply identifier.
[identifier] :: DNSHeader -> !Identifier

-- | Flags, OPCODE, and RCODE
[flags] :: DNSHeader -> !DNSFlags

-- | An identifier assigned by the program that generates any kind of
--   query.
type Identifier = Word16

-- | Raw data format for the flags of DNS Query and Response.
data DNSFlags
DNSFlags :: !QorR -> !OPCODE -> !Bool -> !Bool -> !Bool -> !Bool -> !RCODE -> !Bool -> !Bool -> DNSFlags

-- | Query or response.
[qOrR] :: DNSFlags -> !QorR

-- | Kind of query.
[opcode] :: DNSFlags -> !OPCODE

-- | AA (Authoritative Answer) bit - this bit is valid in responses, and
--   specifies that the responding name server is an authority for the
--   domain name in question section.
[authAnswer] :: DNSFlags -> !Bool

-- | TC (Truncated Response) bit - specifies that this message was
--   truncated due to length greater than that permitted on the
--   transmission channel.
[trunCation] :: DNSFlags -> !Bool

-- | RD (Recursion Desired) bit - 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. Recursive query support is optional.
[recDesired] :: DNSFlags -> !Bool

-- | RA (Recursion Available) bit - this be is set or cleared in a
--   response, and denotes whether recursive query support is available in
--   the name server.
[recAvailable] :: DNSFlags -> !Bool

-- | The full 12-bit extended RCODE when EDNS is in use. Should always be
--   zero in well-formed requests. When decoding replies, the high eight
--   bits from any EDNS response are combined with the 4-bit RCODE from the
--   DNS header. When encoding replies, if no EDNS OPT record is provided,
--   RCODE values &gt; 15 are mapped to <a>FormatErr</a>.
[rcode] :: DNSFlags -> !RCODE

-- | AD (Authenticated Data) bit - (RFC4035, Section 3.2.3).
[authenData] :: DNSFlags -> !Bool

-- | CD (Checking Disabled) bit - (RFC4035, Section 3.2.2).
[chkDisable] :: DNSFlags -> !Bool

-- | Query or response.
data QorR

-- | Query.
QR_Query :: QorR

-- | Response.
QR_Response :: QorR

-- | Default <a>DNSFlags</a> record suitable for making recursive queries.
--   By default the RD bit is set, and the AD and CD bits are cleared.
defaultDNSFlags :: DNSFlags

-- | Kind of query.
data OPCODE

-- | A standard query.
OP_STD :: OPCODE

-- | An inverse query (inverse queries are deprecated).
OP_INV :: OPCODE

-- | A server status request.
OP_SSR :: OPCODE

-- | A zone change notification (RFC1996)
OP_NOTIFY :: OPCODE

-- | An update request (RFC2136)
OP_UPDATE :: OPCODE

-- | Convert the internal representation of a DNS OPCODE to its 16-bit
--   numeric value.
fromOPCODE :: OPCODE -> Word16

-- | Convert a 16-bit DNS OPCODE number to its internal representation
toOPCODE :: Word16 -> Maybe OPCODE

-- | EDNS extended 12-bit response code. Non-EDNS messages use only the low
--   4 bits. With EDNS this stores the combined error code from the DNS
--   header and and the EDNS psuedo-header. See <a>EDNSheader</a> for more
--   detail.
data RCODE

-- | No error condition.
pattern NoErr :: RCODE

-- | Format error - The name server was unable to interpret the query.
pattern FormatErr :: RCODE

-- | Server failure - The name server was unable to process this query due
--   to a problem with the name server.
pattern ServFail :: RCODE

-- | Name Error - Meaningful only for responses from an authoritative name
--   server, this code signifies that the domain name referenced in the
--   query does not exist.
pattern NameErr :: RCODE

-- | Not Implemented - The name server does not support the requested kind
--   of query.
pattern NotImpl :: RCODE

-- | Refused - The name server refuses to perform the specified operation
--   for policy reasons. For example, a name server may not wish to provide
--   the information to the particular requester, or a name server may not
--   wish to perform a particular operation (e.g., zone transfer) for
--   particular data.
pattern Refused :: RCODE

-- | YXDomain - Dynamic update response, a pre-requisite domain that should
--   not exist, does exist.
pattern YXDomain :: RCODE

-- | YXRRSet - Dynamic update response, a pre-requisite RRSet that should
--   not exist, does exist.
pattern YXRRSet :: RCODE

-- | NXRRSet - Dynamic update response, a pre-requisite RRSet that should
--   exist, does not exist.
pattern NXRRSet :: RCODE

-- | NotAuth - Dynamic update response, the server is not authoritative for
--   the zone named in the Zone Section.
pattern NotAuth :: RCODE

-- | NotZone - Dynamic update response, a name used in the Prerequisite or
--   Update Section is not within the zone denoted by the Zone Section.
pattern NotZone :: RCODE

-- | Bad OPT Version (BADVERS, RFC 6891).
pattern BadVers :: RCODE

-- | Key not recognized [RFC2845]
pattern BadKey :: RCODE

-- | Signature out of time window [RFC2845]
pattern BadTime :: RCODE

-- | Bad TKEY Mode [RFC2930]
pattern BadMode :: RCODE

-- | Duplicate key name [RFC2930]
pattern BadName :: RCODE

-- | Algorithm not supported [RFC2930]
pattern BadAlg :: RCODE

-- | Bad Truncation [RFC4635]
pattern BadTrunc :: RCODE

-- | Bad/missing Server Cookie [RFC7873]
pattern BadCookie :: RCODE

-- | Malformed (peer) EDNS message, no RCODE available. This is not an
--   RCODE that can be sent by a peer. It lies outside the 12-bit range
--   expressible via EDNS. The low 12-bits are chosen to coincide with
--   <a>FormatErr</a>. When an EDNS message is malformed, and we're unable
--   to extract the extended RCODE, the header <a>rcode</a> is set to
--   <a>BadRCODE</a>.
pattern BadRCODE :: RCODE

-- | Convert an <a>RCODE</a> to its numeric value.
fromRCODE :: RCODE -> Word16

-- | Convert a numeric value to a corresponding <a>RCODE</a>. The behaviour
--   is undefined for values outside the range <tt>[0 .. 0xFFF]</tt> since
--   the EDNS extended RCODE is a 12-bit value. Values in the range
--   <tt>[0xF01 .. 0xFFF]</tt> are reserved for private use.
toRCODE :: Word16 -> RCODE

-- | Data type representing the optional EDNS pseudo-header of a
--   <a>DNSMessage</a> When a single well-formed <tt>OPT</tt>
--   <a>ResourceRecord</a> was present in the message's additional section,
--   it is decoded to an <a>EDNS</a> record and and stored in the message
--   <a>ednsHeader</a> field. The corresponding <tt>OPT RR</tt> is then
--   removed from the additional section.
--   
--   When the constructor is <a>NoEDNS</a>, no <tt>EDNS OPT</tt> record was
--   present in the message additional section. When <a>InvalidEDNS</a>,
--   the message holds either a malformed OPT record or more than one OPT
--   record, which can still be found in (have not been removed from) the
--   message additional section.
--   
--   The EDNS OPT record augments the message error status with an 8-bit
--   field that forms 12-bit extended RCODE when combined with the 4-bit
--   RCODE from the unextended DNS header. In EDNS messages it is essential
--   to not use just the bare 4-bit <a>RCODE</a> from the original DNS
--   header. Therefore, in order to avoid potential misinterpretation of
--   the response <a>RCODE</a>, when the OPT record is decoded, the upper
--   eight bits of the error status are automatically combined with the
--   <a>rcode</a> of the message header, so that there is only one place in
--   which to find the full 12-bit result. Therefore, the decoded
--   <a>EDNS</a> pseudo-header, does not hold any error status bits.
--   
--   The reverse process occurs when encoding messages. The low four bits
--   of the message header <a>rcode</a> are encoded into the wire-form DNS
--   header, while the upper eight bits are encoded as part of the OPT
--   record. In DNS responses with an <a>rcode</a> larger than 15, EDNS
--   extensions SHOULD be enabled by providing a value for
--   <a>ednsHeader</a> with a constructor of <a>EDNSheader</a>. If EDNS is
--   not enabled in such a message, in order to avoid truncation of
--   <a>RCODE</a> values that don't fit in the non-extended DNS header, the
--   encoded wire-form <a>RCODE</a> is set to <a>FormatErr</a>.
--   
--   When encoding messages for transmission, the <a>ednsHeader</a> is used
--   to generate the additional OPT record. Do not add explicit
--   <tt>OPT</tt> records to the aditional section, configure EDNS via the
--   <a>EDNSheader</a> instead.
--   
--   <pre>
--   &gt;&gt;&gt; let getopts eh = mapEDNS eh ednsOptions []
--   
--   &gt;&gt;&gt; let optsin     = [OD_ClientSubnet 24 0 $ read "192.0.2.1"]
--   
--   &gt;&gt;&gt; let masked     = [OD_ClientSubnet 24 0 $ read "192.0.2.0"]
--   
--   &gt;&gt;&gt; let message    = makeEmptyQuery $ ednsSetOptions $ ODataSet optsin
--   
--   &gt;&gt;&gt; let optsout    = getopts. ednsHeader &lt;$&gt; (decode $ encode message)
--   
--   &gt;&gt;&gt; optsout       == Right masked
--   True
--   </pre>
data EDNSheader

-- | A valid EDNS message
EDNSheader :: EDNS -> EDNSheader

-- | A valid non-EDNS message
NoEDNS :: EDNSheader

-- | Multiple or bad additional <tt>OPT</tt> RRs
InvalidEDNS :: EDNSheader

-- | Return the second argument for EDNS messages, otherwise the third.
ifEDNS :: EDNSheader -> a -> a -> a

-- | Return the output of a function applied to the EDNS pseudo-header if
--   EDNS is enabled, otherwise return a default value.
mapEDNS :: EDNSheader -> (EDNS -> a) -> a -> a

-- | EDNS information defined in RFC 6891.
data EDNS
EDNS :: !Word8 -> !Word16 -> !Bool -> ![OData] -> EDNS

-- | EDNS version, presently only version 0 is defined.
[ednsVersion] :: EDNS -> !Word8

-- | Supported UDP payload size.
[ednsUdpSize] :: EDNS -> !Word16

-- | Request DNSSEC replies (with RRSIG and NSEC records as as appropriate)
--   from the server. Generally, not needed (except for diagnostic
--   purposes) unless the signatures will be validated. Just setting the
--   <tt>AD</tt> bit in the query and checking it in the response is
--   sufficient (but often subject to man-in-the-middle forgery) if all
--   that's wanted is whether the server validated the response.
[ednsDnssecOk] :: EDNS -> !Bool

-- | EDNS options (e.g. <a>OD_NSID</a>, <a>OD_ClientSubnet</a>, ...)
[ednsOptions] :: EDNS -> ![OData]

-- | The default EDNS pseudo-header for queries. The UDP buffer size is set
--   to 1216 bytes, which should result in replies that fit into the 1280
--   byte IPv6 minimum MTU. Since IPv6 only supports fragmentation at the
--   source, and even then not all gateways forward IPv6 pre-fragmented
--   IPv6 packets, it is best to keep DNS packet sizes below this limit
--   when using IPv6 nameservers. A larger value may be practical when
--   using IPv4 exclusively.
--   
--   <pre>
--   defaultEDNS = EDNS
--       { ednsVersion = 0      -- The default EDNS version is 0
--       , ednsUdpSize = 1216   -- IPv6-safe UDP MTU
--       , ednsDnssecOk = False -- We don't do DNSSEC validation
--       , ednsOptions = []     -- No EDNS options by default
--       }
--   </pre>
defaultEDNS :: EDNS

-- | Maximum UDP size that can be advertised. If the <a>ednsUdpSize</a> of
--   <a>EDNS</a> is larger, then this value is sent instead. This value is
--   likely to work only for local nameservers on the loopback network.
--   Servers may enforce a smaller limit.
--   
--   <pre>
--   &gt;&gt;&gt; maxUdpSize
--   16384
--   </pre>
maxUdpSize :: Word16

-- | Minimum UDP size to advertise. If <a>ednsUdpSize</a> of <a>EDNS</a> is
--   smaller, then this value is sent instead.
--   
--   <pre>
--   &gt;&gt;&gt; minUdpSize
--   512
--   </pre>
minUdpSize :: Word16

-- | RData formats for a few EDNS options, and an opaque catcall
data OData

-- | Name Server Identifier (RFC5001). Bidirectional, empty from client.
--   (opaque octet-string). May contain binary data, which MUST be empty in
--   queries.
OD_NSID :: ByteString -> OData

-- | DNSSEC Algorithm Understood (RFC6975). Client to server. (array of
--   8-bit numbers). Lists supported DNSKEY algorithms.
OD_DAU :: [Word8] -> OData

-- | DS Hash Understood (RFC6975). Client to server. (array of 8-bit
--   numbers). Lists supported DS hash algorithms.
OD_DHU :: [Word8] -> OData

-- | NSEC3 Hash Understood (RFC6975). Client to server. (array of 8-bit
--   numbers). Lists supported NSEC3 hash algorithms.
OD_N3U :: [Word8] -> OData

-- | Client subnet (RFC7871). Bidirectional. (source bits, scope bits,
--   address). The address is masked and truncated when encoding queries.
--   The address is zero-padded when decoding. Invalid input encodings
--   result in an <a>OD_ECSgeneric</a> value instead.
OD_ClientSubnet :: Word8 -> Word8 -> IP -> OData

-- | Unsupported or malformed IP client subnet option. Bidirectional.
--   (address family, source bits, scope bits, opaque address).
OD_ECSgeneric :: Word16 -> Word8 -> Word8 -> ByteString -> OData

-- | Generic EDNS option. (numeric <a>OptCode</a>, opaque content)
UnknownOData :: Word16 -> ByteString -> OData

-- | EDNS Option Code (RFC 6891).
data OptCode

-- | Client subnet (RFC7871)
pattern ClientSubnet :: OptCode

-- | DNSSEC algorithm support (RFC6974, section 3)
pattern DAU :: OptCode
pattern DHU :: OptCode
pattern N3U :: OptCode

-- | NSID (RFC5001, section 2.3)
pattern NSID :: OptCode

-- | From option code to number.
fromOptCode :: OptCode -> Word16

-- | From number to option code.
toOptCode :: Word16 -> OptCode

-- | Raw data format for DNS questions.
data Question
Question :: Domain -> TYPE -> Question

-- | A domain name
[qname] :: Question -> Domain

-- | The type of the query
[qtype] :: Question -> TYPE

-- | An enumeration of all possible DNS errors that can occur.
data DNSError

-- | The sequence number of the answer doesn't match our query. This could
--   indicate foul play.
SequenceNumberMismatch :: DNSError

-- | The question section of the response doesn't match our query. This
--   could indicate foul play.
QuestionMismatch :: DNSError

-- | A zone tranfer, i.e., a request of type AXFR, was attempted with the
--   "lookup" interface. Zone transfer is different enough from "normal"
--   requests that it requires a different interface.
InvalidAXFRLookup :: DNSError

-- | The number of retries for the request was exceeded.
RetryLimitExceeded :: DNSError

-- | TCP fallback request timed out.
TimeoutExpired :: DNSError

-- | The answer has the correct sequence number, but returned an unexpected
--   RDATA format.
UnexpectedRDATA :: DNSError

-- | The domain for query is illegal.
IllegalDomain :: DNSError

-- | The name server was unable to interpret the query.
FormatError :: DNSError

-- | The name server was unable to process this query due to a problem with
--   the name server.
ServerFailure :: DNSError

-- | This code signifies that the domain name referenced in the query does
--   not exist.
NameError :: DNSError

-- | The name server does not support the requested kind of query.
NotImplemented :: DNSError

-- | The name server refuses to perform the specified operation for policy
--   reasons. For example, a name server may not wish to provide the
--   information to the particular requester, or a name server may not wish
--   to perform a particular operation (e.g., zone transfer) for particular
--   data.
OperationRefused :: DNSError

-- | The server does not support the OPT RR version or content
BadOptRecord :: DNSError

-- | Configuration is wrong.
BadConfiguration :: DNSError

-- | Network failure.
NetworkFailure :: IOException -> DNSError

-- | Error is unknown
DecodeError :: String -> DNSError
UnknownDNSError :: DNSError

-- | Type for a mailbox encoded on the wire as a DNS name, but the first
--   label is conceptually the local part of an email address, and may
--   contain internal periods that are not label separators. Therefore, in
--   mailboxes @ is used as the separator between the first and second
--   labels, and any '.' characters in the first label are not escaped. The
--   encoding is otherwise the same as <a>Domain</a> above. This is most
--   commonly seen in the <i>mrname</i> of <tt>SOA</tt> records. On input,
--   if there is no unescaped @ character in the <a>Mailbox</a>, it is
--   reparsed with '.' as the first label separator. Thus the traditional
--   format with all labels separated by dots is also accepted, but
--   decoding from wire form always uses @ between the first label and the
--   domain-part of the address. Examples:
--   
--   <pre>
--   hostmaster@example.org.  -- First label is simply <tt>hostmaster</tt>
--   john.smith@examle.com.   -- First label is <tt>john.smith</tt>
--   </pre>
type Mailbox = ByteString
instance GHC.Classes.Eq Network.DNS.Types.QueryControls
instance GHC.Classes.Eq Network.DNS.Types.EdnsControls
instance GHC.Classes.Eq Network.DNS.Types.ODataOp
instance GHC.Show.Show Network.DNS.Types.DNSMessage
instance GHC.Classes.Eq Network.DNS.Types.DNSMessage
instance GHC.Show.Show Network.DNS.Types.ResourceRecord
instance GHC.Classes.Eq Network.DNS.Types.ResourceRecord
instance GHC.Classes.Ord Network.DNS.Types.RData
instance GHC.Classes.Eq Network.DNS.Types.RData
instance GHC.Show.Show Network.DNS.Types.EDNSheader
instance GHC.Classes.Eq Network.DNS.Types.EDNSheader
instance GHC.Show.Show Network.DNS.Types.EDNS
instance GHC.Classes.Eq Network.DNS.Types.EDNS
instance GHC.Classes.Ord Network.DNS.Types.OData
instance GHC.Classes.Eq Network.DNS.Types.OData
instance GHC.Classes.Ord Network.DNS.Types.OptCode
instance GHC.Classes.Eq Network.DNS.Types.OptCode
instance GHC.Classes.Ord Network.DNS.Types.RD_RRSIG
instance GHC.Classes.Eq Network.DNS.Types.RD_RRSIG
instance GHC.Show.Show Network.DNS.Types.Question
instance GHC.Classes.Eq Network.DNS.Types.Question
instance GHC.Show.Show Network.DNS.Types.DNSHeader
instance GHC.Classes.Eq Network.DNS.Types.DNSHeader
instance GHC.Show.Show Network.DNS.Types.DNSFlags
instance GHC.Classes.Eq Network.DNS.Types.DNSFlags
instance GHC.Classes.Eq Network.DNS.Types.RCODE
instance GHC.Enum.Bounded Network.DNS.Types.OPCODE
instance GHC.Enum.Enum Network.DNS.Types.OPCODE
instance GHC.Show.Show Network.DNS.Types.OPCODE
instance GHC.Classes.Eq Network.DNS.Types.OPCODE
instance GHC.Enum.Bounded Network.DNS.Types.QorR
instance GHC.Enum.Enum Network.DNS.Types.QorR
instance GHC.Show.Show Network.DNS.Types.QorR
instance GHC.Classes.Eq Network.DNS.Types.QorR
instance GHC.Classes.Eq Network.DNS.Types.HeaderControls
instance GHC.Show.Show Network.DNS.Types.FlagOp
instance GHC.Classes.Eq Network.DNS.Types.FlagOp
instance GHC.Show.Show Network.DNS.Types.DNSError
instance GHC.Classes.Eq Network.DNS.Types.DNSError
instance GHC.Classes.Ord Network.DNS.Types.TYPE
instance GHC.Classes.Eq Network.DNS.Types.TYPE
instance GHC.Base.Semigroup Network.DNS.Types.QueryControls
instance GHC.Base.Monoid Network.DNS.Types.QueryControls
instance GHC.Show.Show Network.DNS.Types.QueryControls
instance GHC.Base.Semigroup Network.DNS.Types.EdnsControls
instance GHC.Base.Monoid Network.DNS.Types.EdnsControls
instance GHC.Show.Show Network.DNS.Types.EdnsControls
instance GHC.Base.Semigroup Network.DNS.Types.ODataOp
instance GHC.Base.Monoid Network.DNS.Types.ODataOp
instance GHC.Show.Show Network.DNS.Types.RData
instance GHC.Show.Show Network.DNS.Types.OData
instance GHC.Show.Show Network.DNS.Types.OptCode
instance GHC.Show.Show Network.DNS.Types.RD_RRSIG
instance GHC.Enum.Enum Network.DNS.Types.RCODE
instance GHC.Show.Show Network.DNS.Types.RCODE
instance GHC.Base.Semigroup Network.DNS.Types.HeaderControls
instance GHC.Base.Monoid Network.DNS.Types.HeaderControls
instance GHC.Show.Show Network.DNS.Types.HeaderControls
instance GHC.Base.Semigroup Network.DNS.Types.FlagOp
instance GHC.Base.Monoid Network.DNS.Types.FlagOp
instance GHC.Exception.Type.Exception Network.DNS.Types.DNSError
instance GHC.Show.Show Network.DNS.Types.TYPE


-- | DNS message encoder.
--   
--   Note: <a>DNS</a> is a client library, and its focus is on
--   <i>sending</i> <i>queries</i>, and <i>receiving</i> <i>replies</i>.
--   Thefore, while this module is reasonably adept at query generation,
--   building a DNS server with this module requires additional work to
--   handle message size limits, correct UDP truncation, proper EDNS
--   negotiation, and so on. Support for server-side DNS is at best
--   rudimentary.
--   
--   For sending queries, in most cases you should be using one of the
--   functions from <a>Lookup</a> and <a>LookupRaw</a>, or lastly, if you
--   want to handle the network reads and writes for yourself (with your
--   own code for UDP retries, TCP fallback, EDNS fallback, ...), then
--   perhaps <a>encodeQuestion</a> (letting <a>DNS</a> do the lookups for
--   you in an <tt>async</tt> thread is likely much simpler).
module Network.DNS.Encode

-- | Encode a <a>DNSMessage</a> for transmission over UDP. For transmission
--   over TCP encapsulate the result via <a>encodeVC</a>, or use
--   <a>sendVC</a>, which handles this internally. If any
--   <a>ResourceRecord</a> in the message contains incorrectly encoded
--   <a>Domain</a> name ByteStrings, this function may raise a
--   <a>DecodeError</a>.
encode :: DNSMessage -> ByteString


-- | DNS message decoders.
--   
--   When in doubt, use the <a>decodeAt</a> or <a>decodeManyAt</a>
--   functions, which correctly handle <i>circle-arithmetic</i> DNS
--   timestamps, e.g., in <tt>RRSIG</tt> resource records. The
--   <a>decode</a>, and <a>decodeMany</a> functions are only appropriate in
--   pure contexts when the current time is not available, and
--   <tt>RRSIG</tt> records are not expected or desired.
--   
--   The <a>decodeMany</a> and <a>decodeManyAt</a> functions decode a
--   buffer holding one or more messages, each preceded by 16-bit length in
--   network byte order. This encoding is generally only appropriate for
--   DNS TCP, and because TCP does not preserve message boundaries, the
--   decode is prepared to return a trailing message fragment to be
--   completed and retried when more input arrives from network.
module Network.DNS.Decode

-- | Decode an input buffer containing a single encoded DNS message. If the
--   input buffer has excess content beyond the end of the message an error
--   is returned. DNS <i>circle-arithmetic</i> timestamps (e.g. in RRSIG
--   records) are interpreted at the supplied epoch time.
decodeAt :: Int64 -> ByteString -> Either DNSError DNSMessage

-- | Decode an input buffer containing a single encoded DNS message. If the
--   input buffer has excess content beyond the end of the message an error
--   is returned. DNS <i>circle-arithmetic</i> timestamps (e.g. in RRSIG
--   records) are interpreted based on a nominal time in the year 2073
--   chosen to maximize the time range for which this gives correct
--   translations of 32-bit epoch times to absolute 64-bit epoch times.
--   This will yield incorrect results starting circa 2141.
decode :: ByteString -> Either DNSError DNSMessage

-- | Decode a buffer containing multiple encoded DNS messages each preceded
--   by a 16-bit length in network byte order. Any left-over bytes of a
--   partial message after the last complete message are returned as the
--   second element of the result tuple. DNS <i>circle-arithmetic</i>
--   timestamps (e.g. in RRSIG records) are interpreted at the supplied
--   epoch time.
decodeManyAt :: Int64 -> ByteString -> Either DNSError ([DNSMessage], ByteString)

-- | Decode a buffer containing multiple encoded DNS messages each preceded
--   by a 16-bit length in network byte order. Any left-over bytes of a
--   partial message after the last complete message are returned as the
--   second element of the result tuple. DNS <i>circle-arithmetic</i>
--   timestamps (e.g. in RRSIG records) are interpreted based on a nominal
--   time in the year 2078 chosen to give correct dates for DNS timestamps
--   over a 136 year time range from the date the root zone was signed on
--   the 15th of July 2010 until the 21st of August in 2146. Outside this
--   date range the output is off by some non-zero multiple 2^32 seconds.
decodeMany :: ByteString -> Either DNSError ([DNSMessage], ByteString)

module Network.DNS.IO

-- | Receive and decode a single <a>DNSMessage</a> from a UDP
--   <a>Socket</a>. Messages longer than <a>maxUdpSize</a> are silently
--   truncated, but this should not occur in practice, since we cap the
--   advertised EDNS UDP buffer size limit at the same value. A
--   <a>DNSError</a> is raised if I/O or message decoding fails.
receive :: Socket -> IO DNSMessage

-- | Receive and decode a single <tt>DNSMesage</tt> from a virtual-circuit
--   (TCP). It is up to the caller to implement any desired timeout. An
--   <a>DNSError</a> is raised if I/O or message decoding fails.
receiveVC :: Socket -> IO DNSMessage

-- | Send an encoded <a>DNSMessage</a> datagram over UDP. The message
--   length is implicit in the size of the UDP datagram. With TCP you must
--   use <a>sendVC</a>, because TCP does not have message boundaries, and
--   each message needs to be prepended with an explicit length. The socket
--   must be explicitly connected to the destination nameserver.
send :: Socket -> ByteString -> IO ()

-- | Send a single encoded <a>DNSMessage</a> over TCP. An explicit length
--   is prepended to the encoded buffer before transmission. If you want to
--   send a batch of multiple encoded messages back-to-back over a single
--   TCP connection, and then loop to collect the results, use
--   <a>encodeVC</a> to prefix each message with a length, and then use
--   <a>sendAll</a> to send a concatenated batch of the resulting
--   encapsulated messages.
sendVC :: Socket -> ByteString -> IO ()

-- | Send one or more encoded <a>DNSMessage</a> buffers over TCP, each
--   allready encapsulated with an explicit length prefix (perhaps via
--   <a>encodeVC</a>) and then concatenated into a single buffer. DO NOT
--   use <a>sendAll</a> with UDP.
sendAll :: Socket -> ByteString -> IO ()

-- | The encoded <a>DNSMessage</a> has the specified request ID. The
--   default values of the RD, AD, CD and DO flag bits, as well as various
--   EDNS features, can be adjusted via the <a>QueryControls</a> parameter.
--   
--   The caller is responsible for generating the ID via a securely seeded
--   CSPRNG.
encodeQuestion :: Identifier -> Question -> QueryControls -> ByteString

-- | Encapsulate an encoded <a>DNSMessage</a> buffer for transmission over
--   a TCP virtual circuit. With TCP the buffer needs to start with an
--   explicit length (the length is implicit with UDP).
encodeVC :: ByteString -> ByteString

-- | Compose a response with a single IPv4 RRset. If the query had an EDNS
--   pseudo-header, a suitable EDNS pseudo-header must be added to the
--   response message, or else a <a>FormatErr</a> response must be sent.
--   The response TTL defaults to 300 seconds, and should be updated (to
--   the same value across all the RRs) if some other TTL value is more
--   appropriate.
responseA :: Identifier -> Question -> [IPv4] -> DNSMessage

-- | Compose a response with a single IPv6 RRset. If the query had an EDNS
--   pseudo-header, a suitable EDNS pseudo-header must be added to the
--   response message, or else a <a>FormatErr</a> response must be sent.
--   The response TTL defaults to 300 seconds, and should be updated (to
--   the same value across all the RRs) if some other TTL value is more
--   appropriate.
responseAAAA :: Identifier -> Question -> [IPv6] -> DNSMessage


-- | Resolver related data types.
module Network.DNS.Resolver

-- | Type for resolver configuration. Use <a>defaultResolvConf</a> to
--   create a new value.
--   
--   An example to use Google's public DNS cache instead of resolv.conf:
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvInfo = RCHostName "8.8.8.8" }
--   </pre>
--   
--   An example to use multiple Google's public DNS cache concurrently:
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvInfo = RCHostNames ["8.8.8.8","8.8.4.4"], resolvConcurrent = True }
--   </pre>
--   
--   An example to disable EDNS:
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvQueryControls = ednsEnabled FlagClear }
--   </pre>
--   
--   An example to enable query result caching:
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvCache = Just defaultCacheConf }
--   </pre>
--   
--   An example to disable requesting recursive service.
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvQueryControls = rdFlag FlagClear }
--   </pre>
--   
--   An example to set the AD bit in all queries by default.
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvQueryControls = adFlag FlagSet }
--   </pre>
--   
--   An example to set the both the AD and CD bits in all queries by
--   default.
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvQueryControls = adFlag FlagSet &lt;&gt; cdFlag FlagSet }
--   </pre>
--   
--   An example with an EDNS buffer size of 1216 bytes, which is more
--   robust with IPv6, and the DO bit set to request DNSSEC responses.
--   
--   <pre>
--   &gt;&gt;&gt; let conf = defaultResolvConf { resolvQueryControls = ednsSetUdpSize (Just 1216) &lt;&gt; doFlag FlagSet }
--   </pre>
data ResolvConf

-- | Return a default <a>ResolvConf</a>:
--   
--   <ul>
--   <li><a>resolvInfo</a> is <a>RCFilePath</a> "/etc/resolv.conf".</li>
--   <li><a>resolvTimeout</a> is 3,000,000 micro seconds.</li>
--   <li><a>resolvRetry</a> is 3.</li>
--   <li><a>resolvConcurrent</a> is False.</li>
--   <li><a>resolvCache</a> is Nothing.</li>
--   <li><a>resolvQueryControls</a> is an empty set of overrides.</li>
--   </ul>
defaultResolvConf :: ResolvConf

-- | Server information.
resolvInfo :: ResolvConf -> FileOrNumericHost

-- | Timeout in micro seconds.
resolvTimeout :: ResolvConf -> Int

-- | The number of retries including the first try.
resolvRetry :: ResolvConf -> Int

-- | Concurrent queries if multiple DNS servers are specified.
resolvConcurrent :: ResolvConf -> Bool

-- | Cache configuration.
resolvCache :: ResolvConf -> Maybe CacheConf

-- | Overrides for the default flags used for queries via resolvers that
--   use this configuration.
resolvQueryControls :: ResolvConf -> QueryControls

-- | The type to specify a cache server.
data FileOrNumericHost

-- | A path for "resolv.conf" where one or more IP addresses of DNS servers
--   should be found on Unix. Default DNS servers are automatically
--   detected on Windows regardless of the value of the file name.
RCFilePath :: FilePath -> FileOrNumericHost

-- | A numeric IP address. <i>Warning</i>: host names are invalid.
RCHostName :: HostName -> FileOrNumericHost

-- | Numeric IP addresses. <i>Warning</i>: host names are invalid.
RCHostNames :: [HostName] -> FileOrNumericHost

-- | A numeric IP address and port number. <i>Warning</i>: host names are
--   invalid.
RCHostPort :: HostName -> PortNumber -> FileOrNumericHost

-- | Cache configuration for responses.
data CacheConf

-- | Default cache configuration.
--   
--   <pre>
--   &gt;&gt;&gt; defaultCacheConf
--   CacheConf {maximumTTL = 300, pruningDelay = 10}
--   </pre>
defaultCacheConf :: CacheConf

-- | If RR's TTL is higher than this value, this value is used instead.
maximumTTL :: CacheConf -> TTL

-- | Cache pruning interval in seconds.
pruningDelay :: CacheConf -> Int

-- | Intermediate abstract data type for resolvers. IP address information
--   of DNS servers is generated according to <a>resolvInfo</a> internally.
--   This value can be safely reused for <tt>withResolver</tt>.
--   
--   The naming is confusing for historical reasons.
data ResolvSeed

-- | Make a <a>ResolvSeed</a> from a <a>ResolvConf</a>.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   </pre>
makeResolvSeed :: ResolvConf -> IO ResolvSeed

-- | Abstract data type of DNS Resolver. This includes newly seeded
--   identifier generators for all specified DNS servers and a cache
--   database.
data Resolver

-- | Giving a thread-safe <a>Resolver</a> to the function of the second
--   argument.
withResolver :: ResolvSeed -> (Resolver -> IO a) -> IO a

-- | Giving thread-safe <a>Resolver</a>s to the function of the second
--   argument. For each <a>Resolver</a>, multiple lookups must be done
--   sequentially. <a>Resolver</a>s can be used concurrently.

-- | <i>Deprecated: Use withResolver with resolvConcurrent set to True</i>
withResolvers :: [ResolvSeed] -> ([Resolver] -> IO a) -> IO a

module Network.DNS.LookupRaw

-- | Look up resource records of a specified type for a domain, collecting
--   the results from the ANSWER section of the response. See the
--   documentation of <a>lookupRaw</a> to understand the concrete behavior.
--   Cache is used if <a>resolvCache</a> is <a>Just</a>.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookup resolver "www.example.com" A
--   Right [93.184.216.34]
--   </pre>
lookup :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])

-- | Look up resource records of a specified type for a domain, collecting
--   the results from the AUTHORITY section of the response. See the
--   documentation of <a>lookupRaw</a> to understand the concrete behavior.
--   Cache is used even if <a>resolvCache</a> is <a>Just</a>.
lookupAuth :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])

-- | Look up a name and return the entire DNS Response.
--   
--   For a given DNS server, the queries are done:
--   
--   <ul>
--   <li>A new UDP socket bound to a new local port is created and a new
--   identifier is created atomically from the cryptographically secure
--   pseudo random number generator for the target DNS server. Then UDP
--   queries are tried with the limitation of <a>resolvRetry</a> (use EDNS
--   if specifiecd). If it appears that the target DNS server does not
--   support EDNS, it falls back to traditional queries.</li>
--   <li>If the response is truncated, a new TCP socket bound to a new
--   local port is created. Then exactly one TCP query is retried.</li>
--   </ul>
--   
--   If multiple DNS servers are specified <a>ResolvConf</a> ('RCHostNames
--   ') or found (<a>RCFilePath</a>), either sequential lookup or
--   concurrent lookup is carried out:
--   
--   <ul>
--   <li>In sequential lookup (<a>resolvConcurrent</a> is False), the query
--   procedure above is processed in the order of the DNS servers
--   sequentially until a successful response is received.</li>
--   <li>In concurrent lookup (<a>resolvConcurrent</a> is True), the query
--   procedure above is processed for each DNS server concurrently. The
--   first received response is accepted even if it is an error.</li>
--   </ul>
--   
--   Cache is not used even if <a>resolvCache</a> is <a>Just</a>.
--   
--   The example code:
--   
--   <pre>
--   rs &lt;- makeResolvSeed defaultResolvConf
--   withResolver rs $ \resolver -&gt; lookupRaw resolver "www.example.com" A
--   
--   </pre>
--   
--   And the (formatted) expected output:
--   
--   <pre>
--   Right (DNSMessage
--           { header = DNSHeader
--                        { identifier = 1,
--                          flags = DNSFlags
--                                    { qOrR = QR_Response,
--                                      opcode = OP_STD,
--                                      authAnswer = False,
--                                      trunCation = False,
--                                      recDesired = True,
--                                      recAvailable = True,
--                                      rcode = NoErr,
--                                      authenData = False
--                                    },
--                        },
--             question = [Question { qname = "www.example.com.",
--                                    qtype = A}],
--             answer = [ResourceRecord {rrname = "www.example.com.",
--                                       rrtype = A,
--                                       rrttl = 800,
--                                       rdlen = 4,
--                                       rdata = 93.184.216.119}],
--             authority = [],
--             additional = []})
--   
--   </pre>
--   
--   AXFR requests cannot be performed with this interface.
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupRaw resolver "mew.org" AXFR
--   Left InvalidAXFRLookup
--   </pre>
lookupRaw :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)

-- | Similar to <a>lookupRaw</a>, but the default values of the RD, AD, CD
--   and DO flag bits, as well as various EDNS features, can be adjusted
--   via the <a>QueryControls</a> parameter.
lookupRawCtl :: Resolver -> Domain -> TYPE -> QueryControls -> IO (Either DNSError DNSMessage)

-- | Messages with a non-error RCODE are passed to the supplied function
--   for processing. Other messages are translated to <a>DNSError</a>
--   instances.
--   
--   Note that <a>NameError</a> is not a lookup error. The lookup is
--   successful, bearing the sad news that the requested domain does not
--   exist. <a>NameError</a> responses may return a meaningful AD bit, may
--   contain useful data in the authority section, and even initial CNAME
--   records that lead to the ultimately non-existent domain. Applications
--   that wish to process the content of <a>NameError</a> (NXDomain)
--   messages will need to implement their own RCODE handling.
fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a


-- | Simple, high-level DNS lookup functions for clients.
--   
--   All of the lookup functions necessary run in IO since they interact
--   with the network. The return types are similar, but differ in what can
--   be returned from a successful lookup.
--   
--   We can think of the return type as either "what I asked for" or "an
--   error". For example, the <a>lookupA</a> function, if successful, will
--   return a list of <a>IPv4</a>. The <a>lookupMX</a> function will
--   instead return a list of <tt>(<a>Domain</a>,<a>Int</a>)</tt> pairs,
--   where each pair represents a hostname and its associated priority.
--   
--   The order of multiple results may not be consistent between lookups.
--   If you require consistent results, apply <a>sort</a> to the returned
--   list.
--   
--   The errors that can occur are the same for all lookups. Namely:
--   
--   <ul>
--   <li>Timeout</li>
--   <li>Wrong sequence number (foul play?)</li>
--   <li>Unexpected data in the response</li>
--   </ul>
--   
--   If an error occurs, you should be able to pattern match on the
--   <a>DNSError</a> constructor to determine which of these is the case.
--   
--   <i>Note</i>: A result of "no records" is not considered an error. If
--   you perform, say, an 'AAAA' lookup for a domain with no such records,
--   the "success" result would be <tt>Right []</tt>.
--   
--   We perform a successful lookup of "www.example.com":
--   
--   <pre>
--   &gt;&gt;&gt; let hostname = Data.ByteString.Char8.pack "www.example.com"
--   
--   &gt;&gt;&gt; 
--   
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupA resolver hostname
--   Right [93.184.216.34]
--   </pre>
--   
--   The only error that we can easily cause is a timeout. We do this by
--   creating and utilizing a <a>ResolvConf</a> which has a timeout of one
--   millisecond and a very limited number of retries:
--   
--   <pre>
--   &gt;&gt;&gt; let hostname = Data.ByteString.Char8.pack "www.example.com"
--   
--   &gt;&gt;&gt; let badrc = defaultResolvConf { resolvTimeout = 0, resolvRetry = 1 }
--   
--   &gt;&gt;&gt; 
--   
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed badrc
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupA resolver hostname
--   Left RetryLimitExceeded
--   </pre>
--   
--   As is the convention, successful results will always be wrapped in a
--   <a>Right</a> while errors will be wrapped in a <a>Left</a>.
--   
--   For convenience, you may wish to enable GHC's OverloadedStrings
--   extension. This will allow you to avoid calling <a>pack</a> on each
--   domain name. See
--   <a>https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#overloaded-string-literals</a>
--   for more information. In the following examples, we assuem this
--   extension is enabled.
--   
--   All lookup functions eventually call <a>lookupRaw</a>. See its
--   documentation to understand the concrete lookup behavior.
module Network.DNS.Lookup

-- | Look up all 'A' records for the given hostname.
--   
--   A straightforward example:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupA resolver "www.mew.org"
--   Right [210.130.207.72]
--   </pre>
--   
--   This function will also follow a CNAME and resolve its target if one
--   exists for the queries hostname:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupA resolver "www.kame.net"
--   Right [203.178.141.194]
--   </pre>
lookupA :: Resolver -> Domain -> IO (Either DNSError [IPv4])

-- | Look up all (IPv6) 'AAAA' records for the given hostname.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupAAAA resolver "www.wide.ad.jp"
--   Right [2001:200:dff:fff1:216:3eff:fe4b:651c]
--   </pre>
lookupAAAA :: Resolver -> Domain -> IO (Either DNSError [IPv6])

-- | Look up all 'MX' records for the given hostname. Two parts constitute
--   an MX record: a hostname , and an integer priority. We therefore
--   return each record as a <tt>(<a>Domain</a>, Int)</tt>.
--   
--   In this first example, we look up the MX for the domain "example.com".
--   It has no MX (to prevent a deluge of spam from examples posted on the
--   internet). But remember, "no results" is still a successful result.
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupMX resolver "example.com"
--   Right []
--   </pre>
--   
--   The domain "mew.org" does however have a single MX:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupMX resolver "mew.org"
--   Right [("mail.mew.org.",10)]
--   </pre>
--   
--   Also note that all hostnames are returned with a trailing dot to
--   indicate the DNS root.
lookupMX :: Resolver -> Domain -> IO (Either DNSError [(Domain, Int)])

-- | Look up all 'MX' records for the given hostname, and then resolve
--   their hostnames to IPv4 addresses by calling <a>lookupA</a>. The
--   priorities are not retained.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.List (sort)
--   
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; ips &lt;- withResolver rs $ \resolver -&gt; lookupAviaMX resolver "wide.ad.jp"
--   
--   &gt;&gt;&gt; fmap sort ips
--   Right [133.138.10.39,203.178.136.30]
--   </pre>
--   
--   Since there is more than one result, it is necessary to sort the list
--   in order to check for equality.
lookupAviaMX :: Resolver -> Domain -> IO (Either DNSError [IPv4])

-- | Look up all 'MX' records for the given hostname, and then resolve
--   their hostnames to IPv6 addresses by calling <a>lookupAAAA</a>. The
--   priorities are not retained.
lookupAAAAviaMX :: Resolver -> Domain -> IO (Either DNSError [IPv6])

-- | Look up all 'NS' records for the given hostname. The results are taken
--   from the ANSWER section of the response (as opposed to AUTHORITY). For
--   details, see e.g. <a>http://www.zytrax.com/books/dns/ch15/</a>.
--   
--   There will typically be more than one name server for a domain. It is
--   therefore extra important to sort the results if you prefer them to be
--   at all deterministic.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.List (sort)
--   
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; ns &lt;- withResolver rs $ \resolver -&gt; lookupNS resolver "mew.org"
--   
--   &gt;&gt;&gt; fmap sort ns
--   Right ["ns1.mew.org.","ns2.mew.org."]
--   </pre>
lookupNS :: Resolver -> Domain -> IO (Either DNSError [Domain])

-- | Look up all 'NS' records for the given hostname. The results are taken
--   from the AUTHORITY section of the response and not the usual ANSWER
--   (use <a>lookupNS</a> for that). For details, see e.g.
--   <a>http://www.zytrax.com/books/dns/ch15/</a>.
--   
--   There will typically be more than one name server for a domain. It is
--   therefore extra important to sort the results if you prefer them to be
--   at all deterministic.
--   
--   For an example, we can look up the nameservers for "example.com" from
--   one of the root servers, a.gtld-servers.net, the IP address of which
--   was found beforehand:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.List (sort)
--   
--   &gt;&gt;&gt; let ri = RCHostName "192.5.6.30" -- a.gtld-servers.net
--   
--   &gt;&gt;&gt; let rc = defaultResolvConf { resolvInfo = ri }
--   
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed rc
--   
--   &gt;&gt;&gt; ns &lt;- withResolver rs $ \resolver -&gt; lookupNSAuth resolver "example.com"
--   
--   &gt;&gt;&gt; fmap sort ns
--   Right ["a.iana-servers.net.","b.iana-servers.net."]
--   </pre>
lookupNSAuth :: Resolver -> Domain -> IO (Either DNSError [Domain])

-- | Look up all 'TXT' records for the given hostname. The results are
--   free-form <a>ByteString</a>s.
--   
--   Two common uses for 'TXT' records are
--   <a>http://en.wikipedia.org/wiki/Sender_Policy_Framework</a> and
--   <a>http://en.wikipedia.org/wiki/DomainKeys_Identified_Mail</a>. As an
--   example, we find the SPF record for "mew.org":
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupTXT resolver "mew.org"
--   Right ["v=spf1 +mx -all"]
--   </pre>
lookupTXT :: Resolver -> Domain -> IO (Either DNSError [ByteString])

-- | Look up the 'SOA' record for the given domain. The result 7-tuple
--   consists of the 'mname', 'rname', 'serial', 'refresh', 'retry',
--   'expire' and 'minimum' fields of the SOA record.
--   
--   An @ separator is used between the first and second labels of the
--   'rname' field. Since 'rname' is an email address, it often contains
--   periods within its first label. Presently, the trailing period is not
--   removed from the domain part of the 'rname', but this may change in
--   the future. Users should be prepared to remove any trailing period
--   before using the 'rname` as a contact email address.
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupSOA resolver "mew.org"
--   Right [("ns1.mew.org.","kazu@mew.org.",201406240,3600,300,3600000,3600)]
--   </pre>
lookupSOA :: Resolver -> Domain -> IO (Either DNSError [(Domain, Mailbox, Word32, Word32, Word32, Word32, Word32)])

-- | Look up all 'PTR' records for the given hostname. To perform a reverse
--   lookup on an IP address, you must first reverse its octets and then
--   append the suffix ".in-addr.arpa."
--   
--   We look up the PTR associated with the IP address 210.130.137.80,
--   i.e., 80.137.130.210.in-addr.arpa:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupPTR resolver "164.2.232.202.in-addr.arpa"
--   Right ["www.iij.ad.jp."]
--   </pre>
--   
--   The <a>lookupRDNS</a> function is more suited to this particular task.
lookupPTR :: Resolver -> Domain -> IO (Either DNSError [Domain])

-- | Convenient wrapper around <a>lookupPTR</a> to perform a reverse lookup
--   on a single IP address.
--   
--   We repeat the example from <a>lookupPTR</a>, except now we pass the IP
--   address directly:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupRDNS resolver "202.232.2.164"
--   Right ["www.iij.ad.jp."]
--   </pre>
lookupRDNS :: Resolver -> Domain -> IO (Either DNSError [Domain])

-- | Look up all 'SRV' records for the given hostname. SRV records consist
--   (see <a>https://tools.ietf.org/html/rfc2782</a>) of the following four
--   fields:
--   
--   <ul>
--   <li>Priority (lower is more-preferred)</li>
--   <li>Weight (relative frequency with which to use this record amongst
--   all results with the same priority)</li>
--   <li>Port (the port on which the service is offered)</li>
--   <li>Target (the hostname on which the service is offered)</li>
--   </ul>
--   
--   The first three are integral, and the target is another DNS hostname.
--   We therefore return a four-tuple <tt>(Int,Int,Int,<a>Domain</a>)</tt>.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupSRV resolver "_xmpp-server._tcp.jabber.ietf.org"
--   Right [(5,0,5269,"jabber.ietf.org.")]
--   </pre>
lookupSRV :: Resolver -> Domain -> IO (Either DNSError [(Word16, Word16, Word16, Domain)])


-- | Miscellaneous utility functions for processing DNS data.
module Network.DNS.Utils

-- | Perform both <a>normalizeCase</a> and <a>normalizeRoot</a> on the
--   given <a>Domain</a>. When comparing DNS names taken from user input,
--   this is often necessary to avoid unexpected results.
--   
--   <i>Examples</i>:
--   
--   <pre>
--   &gt;&gt;&gt; let domain1 = BS.pack "ExAmPlE.COM"
--   
--   &gt;&gt;&gt; let domain2 = BS.pack "example.com."
--   
--   &gt;&gt;&gt; domain1 == domain2
--   False
--   
--   &gt;&gt;&gt; normalize domain1 == normalize domain2
--   True
--   </pre>
--   
--   The <a>normalize</a> function should be idempotent:
--   
--   <pre>
--   &gt;&gt;&gt; normalize (normalize domain1) == normalize domain1
--   True
--   </pre>
--   
--   Ensure that we don't crash on the empty <a>Domain</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.ByteString.Char8 as BS
--   
--   &gt;&gt;&gt; normalize BS.empty
--   "."
--   </pre>
normalize :: Domain -> Domain

-- | Normalize the case of the given DNS name for comparisons.
--   
--   According to RFC #1035, "For all parts of the DNS that are part of the
--   official protocol, all comparisons between character strings (e.g.,
--   labels, domain names, etc.) are done in a case-insensitive manner."
--   This function chooses to lowercase its argument, but that should be
--   treated as an implementation detail if at all possible.
--   
--   <i>Examples</i>:
--   
--   <pre>
--   &gt;&gt;&gt; let domain1 = BS.pack "ExAmPlE.COM"
--   
--   &gt;&gt;&gt; let domain2 = BS.pack "exAMPle.com"
--   
--   &gt;&gt;&gt; domain1 == domain2
--   False
--   
--   &gt;&gt;&gt; normalizeCase domain1 == normalizeCase domain2
--   True
--   </pre>
--   
--   The <a>normalizeCase</a> function should be idempotent:
--   
--   <pre>
--   &gt;&gt;&gt; normalizeCase (normalizeCase domain2) == normalizeCase domain2
--   True
--   </pre>
--   
--   Ensure that we don't crash on the empty <a>Domain</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.ByteString.Char8 as BS
--   
--   &gt;&gt;&gt; normalizeCase BS.empty
--   ""
--   </pre>
normalizeCase :: Domain -> Domain

-- | Normalize the given name by appending a trailing dot (the DNS root) if
--   one does not already exist.
--   
--   Warning: this does not produce an equivalent DNS name! However, users
--   are often unaware of the effect that the absence of the root will
--   have. In user interface design, it may therefore be wise to act as if
--   the user supplied the trailing dot during comparisons.
--   
--   Per RFC #1034,
--   
--   "Since a complete domain name ends with the root label, this leads to
--   a printed form which ends in a dot. We use this property to
--   distinguish between:
--   
--   <ul>
--   <li>a character string which represents a complete domain name (often
--   called 'absolute'). For example, 'poneria.ISI.EDU.'</li>
--   <li>a character string that represents the starting labels of a domain
--   name which is incomplete, and should be completed by local software
--   using knowledge of the local domain (often called 'relative'). For
--   example, 'poneria' used in the ISI.EDU domain.</li>
--   </ul>
--   
--   Relative names are either taken relative to a well known origin, or to
--   a list of domains used as a search list. Relative names appear mostly
--   at the user interface, where their interpretation varies from
--   implementation to implementation, and in master files, where they are
--   relative to a single origin domain name."
--   
--   <i>Examples</i>:
--   
--   <pre>
--   &gt;&gt;&gt; let domain1 = BS.pack "example.com"
--   
--   &gt;&gt;&gt; let domain2 = BS.pack "example.com."
--   
--   &gt;&gt;&gt; domain1 == domain2
--   False
--   
--   &gt;&gt;&gt; normalizeRoot domain1 == normalizeRoot domain2
--   True
--   </pre>
--   
--   The <a>normalizeRoot</a> function should be idempotent:
--   
--   <pre>
--   &gt;&gt;&gt; normalizeRoot (normalizeRoot domain1) == normalizeRoot domain1
--   True
--   </pre>
--   
--   Ensure that we don't crash on the empty <a>Domain</a>:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.ByteString.Char8 as BS
--   
--   &gt;&gt;&gt; normalizeRoot BS.empty
--   "."
--   </pre>
normalizeRoot :: Domain -> Domain


-- | A thread-safe DNS library for both clients and servers written in pure
--   Haskell. The Network.DNS module re-exports all other exposed modules
--   for convenience. Applications will most likely use the high-level
--   interface, while library/daemon authors may need to use the
--   lower-level one. EDNS and TCP fallback are supported.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; rs &lt;- makeResolvSeed defaultResolvConf
--   
--   &gt;&gt;&gt; withResolver rs $ \resolver -&gt; lookupA resolver "www.mew.org"
--   Right [210.130.207.72]
--   </pre>
module Network.DNS