-- 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 3.0.4

-- | Data types for DNS Query and Response. For more information, see
--   http://www.ietf.org/rfc/rfc1035.
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 for domain.
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

-- | A request for all records the server/cache has available
pattern ANY :: 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

-- | A null RR (EXPERIMENTAL). Anything can be in a NULL record, for now we
--   just drop this data.
RD_NULL :: 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_RRSIG RD_NSEC
RD_DS :: Word16 -> Word8 -> Word8 -> ByteString -> RData

-- | DNSKEY (RFC4034) RD_NSEC3
RD_DNSKEY :: Word16 -> Word8 -> Word8 -> ByteString -> RData
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

-- | Raw data format for DNS Query and Response.
data DNSMessage
DNSMessage :: DNSHeader -> [Question] -> [ResourceRecord] -> [ResourceRecord] -> [ResourceRecord] -> DNSMessage

-- | Header
[header] :: DNSMessage -> DNSHeader

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

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

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

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

-- | Default query.
defaultQuery :: DNSMessage

-- | Default response.
defaultResponse :: DNSMessage

-- | For backward compatibility.

-- | Deprecated: Use DNSMessage instead
type DNSFormat = DNSMessage

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

-- | An identifier.
[identifier] :: DNSHeader -> Identifier

-- | The second 16bit word.
[flags] :: DNSHeader -> DNSFlags

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

-- | Query or response.
data QorR

-- | Query.
QR_Query :: QorR

-- | Response.
QR_Response :: QorR

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

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

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

-- | Authoritative Answer - 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

-- | TrunCation - specifies that this message was truncated due to length
--   greater than that permitted on the transmission channel.
[trunCation] :: DNSFlags -> Bool

-- | 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. Recursive query support is optional.
[recDesired] :: DNSFlags -> Bool

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

-- | Response code.
[rcode] :: DNSFlags -> RCODE

-- | Authentic Data (RFC4035).
[authenData] :: DNSFlags -> Bool

-- | Kind of query.
data OPCODE

-- | A standard query.
OP_STD :: OPCODE

-- | An inverse query.
OP_INV :: OPCODE

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

-- | Response code including EDNS0's 12bit ones.
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 (RFC 6891) or TSIG Signature Failure (RFC2845).
pattern BadOpt :: RCODE

-- | From rcode to number.
fromRCODE :: RCODE -> Word16

-- | From number to rcode.
toRCODE :: Word16 -> RCODE

-- | From rcode to number for header (4bits only).
fromRCODEforHeader :: RCODE -> Word16

-- | From number in header to rcode (4bits only).
toRCODEforHeader :: Word16 -> RCODE

-- | 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 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 detected a malformed OPT RR.
BadOptRecord :: DNSError

-- | Configuration is wrong.
BadConfiguration :: DNSError

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

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

-- | EDNS0 infromation defined in RFC 6891.
data EDNS0

-- | Default information for EDNS0.
--   
--   
--   >>> defaultEDNS0
--   EDNS0 {udpSize = 4096, extRCODE = NoError, dnssecOk = False, options = []}
--   
defaultEDNS0 :: EDNS0

-- | Maximum UDP size. If udpSize of EDNS0 is larger than
--   this, fromEDNS0 uses this value instead.
--   
--   
--   >>> maxUdpSize
--   16384
--   
maxUdpSize :: Word16

-- | Minimum UDP size. If udpSize of EDNS0 is smaller than
--   this, fromEDNS0 uses this value instead.
--   
--   
--   >>> minUdpSize
--   512
--   
minUdpSize :: Word16

-- | UDP payload size.
udpSize :: EDNS0 -> Word16

-- | Extended RCODE.
extRCODE :: EDNS0 -> RCODE

-- | Is DNSSEC OK?
dnssecOk :: EDNS0 -> Bool

-- | EDNS0 option data.
options :: EDNS0 -> [OData]

-- | Generating a resource record for the additional section based on
--   EDNS0. DNSFlags is not generated. Just set the same
--   RCODE to DNSFlags.
fromEDNS0 :: EDNS0 -> ResourceRecord

-- | Generating EDNS0 information from the OPT RR.
toEDNS0 :: DNSFlags -> ResourceRecord -> Maybe EDNS0

-- | Optional resource data.
data OData

-- | Client subnet (RFC7871)
OD_ClientSubnet :: Word8 -> Word8 -> IP -> OData

-- | Unknown optional type
UnknownOData :: OptCode -> ByteString -> OData

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

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

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

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

-- | Type for a mailbox encoded on the wire as a DNS name, but the first
--   label is conceptually the user name, and sometimes has contains
--   internal periods that are not label separators. Therefore, in
--   mailboxes @ is used as the separator between the first and second
--   labels.
type Mailbox = ByteString
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.EDNS0
instance GHC.Classes.Eq Network.DNS.Types.EDNS0
instance GHC.Classes.Ord Network.DNS.Types.OData
instance GHC.Show.Show 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.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.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.Show.Show Network.DNS.Types.RData
instance GHC.Show.Show Network.DNS.Types.OptCode
instance GHC.Enum.Enum Network.DNS.Types.RCODE
instance GHC.Show.Show Network.DNS.Types.RCODE
instance GHC.Exception.Type.Exception Network.DNS.Types.DNSError
instance GHC.Show.Show Network.DNS.Types.TYPE

-- | Encoders for DNS.
module Network.DNS.Encode

-- | Encoding DNS query or response.
encode :: DNSMessage -> ByteString

-- | Encoding resource record.
encodeResourceRecord :: ResourceRecord -> ByteString

-- | Encoding DNS header.
encodeDNSHeader :: DNSHeader -> ByteString

-- | Encoding DNS flags.
encodeDNSFlags :: DNSFlags -> ByteString

-- | Encoding domain.
encodeDomain :: Domain -> ByteString

-- | Encoding mailbox.
encodeMailbox :: Mailbox -> ByteString

-- | Decoders for DNS.
module Network.DNS.Decode

-- | Decoding DNS query or response.
decode :: ByteString -> Either DNSError DNSMessage

-- | Parse many length-encoded DNS records, for example, from TCP traffic.
decodeMany :: ByteString -> Either DNSError ([DNSMessage], ByteString)

-- | Decoding resource record.
decodeResourceRecord :: ByteString -> Either DNSError ResourceRecord

-- | Decoding DNS header.
decodeDNSHeader :: ByteString -> Either DNSError DNSHeader

-- | Decoding DNS flags.
decodeDNSFlags :: ByteString -> Either DNSError DNSFlags

-- | Decoding domain.
decodeDomain :: ByteString -> Either DNSError Domain

-- | Decoding mailbox.
decodeMailbox :: ByteString -> Either DNSError Mailbox

module Network.DNS.IO

-- | Receiving DNS data from Socket and parse it.
receive :: Socket -> IO DNSMessage

-- | Receive and parse a single virtual-circuit (TCP) query or response. It
--   is up to the caller to implement any desired timeout.
receiveVC :: Socket -> IO DNSMessage

-- | Sending composed query or response to Socket.
send :: Socket -> ByteString -> IO ()

-- | Sending composed query or response to a single virtual-circuit (TCP).
sendVC :: Socket -> ByteString -> IO ()

-- | Creating query.
encodeQuestions :: Identifier -> [Question] -> [ResourceRecord] -> Bool -> ByteString

-- | Composing query without EDNS0.

-- | Deprecated: Use encodeQuestions instead
composeQuery :: Identifier -> [Question] -> ByteString

-- | Composing query with authentic data flag set without EDNS0.

-- | Deprecated: Use encodeQuestions instead
composeQueryAD :: Identifier -> [Question] -> ByteString

-- | Composing a response from IPv4 addresses
responseA :: Identifier -> Question -> [IPv4] -> DNSMessage

-- | Composing a response from IPv6 addresses
responseAAAA :: Identifier -> Question -> [IPv6] -> DNSMessage

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

-- | Type for resolver configuration. Use defaultResolvConf to
--   create a new value.
--   
--   An example to use Google's public DNS cache instead of resolv.conf:
--   
--   
--   >>> let conf = defaultResolvConf { resolvInfo = RCHostName "8.8.8.8" }
--   
--   
--   An example to use multiple Google's public DNS cache concurrently:
--   
--   
--   >>> let conf = defaultResolvConf { resolvInfo = RCHostNames ["8.8.8.8","8.8.4.4"], resolvConcurrent = True }
--   
--   
--   An example to disable EDNS0:
--   
--   
--   >>> let conf = defaultResolvConf { resolvEDNS = [] }
--   
--   
--   An example to enable EDNS0 with a 1,280-bytes buffer:
--   
--   
--   >>> let conf = defaultResolvConf { resolvEDNS = [fromEDNS0 defaultEDNS0 { udpSize = 1280 }] }
--   
--   
--   An example to enable cache:
--   
--   
--   >>> let conf = defaultResolvConf { resolvCache = Just defaultCacheConf }
--   
data ResolvConf

-- | Return a default ResolvConf:
--   
--   
--   
- resolvInfo is RCFilePath "/etc/resolv.conf".
--   
- resolvTimeout is 3,000,000 micro seconds.
--   
- resolvRetry is 3.
--   
- resolvEDNS is EDNS0 with a 4,096-bytes buffer.
--   
- resolvConcurrent is False.
--   
- resolvCache is Nothing.
--   
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

-- | Additional resource records to specify EDNS.
resolvEDNS :: ResolvConf -> [ResourceRecord]

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

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

-- | 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. Warning: host names are invalid.
RCHostName :: HostName -> FileOrNumericHost

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

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

-- | Cache configuration for responses.
data CacheConf

-- | Default cache configuration.
--   
--   
--   >>> defaultCacheConf
--   CacheConf {maximumTTL = 300, pruningDelay = 10}
--   
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 resolvInfo internally.
--   This value can be safely reused for withResolver.
--   
--   The naming is confusing for historical reasons.
data ResolvSeed

-- | Make a ResolvSeed from a ResolvConf.
--   
--   Examples:
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
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 Resolver to the function of the second
--   argument.
withResolver :: ResolvSeed -> (Resolver -> IO a) -> IO a

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

-- | Deprecated: Use withResolver with resolvConcurrent set to True
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 manual the
--   manual of lookupRaw to understand the concrete behavior. Cache
--   is used if resolvCache is Just.
--   
--   Example:
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookup resolver "www.example.com" A
--   Right [93.184.216.34]
--   
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 manual the
--   manual of lookupRaw to understand the concrete behavior. Cache
--   is used even if resolvCache is Just.
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:
--   
--   
--   
- 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 resolvRetry (use EDNS0
--   if specifiecd). If it appear that the target DNS server does not
--   support EDNS0, it falls back to traditional queries.
--   
- If the response is truncated, a new TCP socket bound to a new
--   locla port is created. Then exactly one TCP query is retried.
--   
--   
--   If multiple DNS server are specified ResolvConf ('RCHostNames
--   ') or found (RCFilePath), either sequential lookup or
--   concurrent lookup is carried out:
--   
--   
--   
- In sequential lookup (resolvConcurrent is False), the query
--   procedure above is processed in the order of the DNS servers
--   sequentially until a successful response is received.
--   
- In concurrent lookup (resolvConcurrent 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.
--   
--   
--   Cache is not used even if resolvCache is Just.
--   
--   The example code:
--   
--   
--   rs <- makeResolvSeed defaultResolvConf
--   withResolver rs $ \resolver -> lookupRaw resolver "www.example.com" A
--   
--   
--   
--   And the (formatted) expected output:
--   
--   
--   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 = []})
--   
--   
lookupRaw :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)

-- | Same as lookupRaw but the query sets the AD bit, which solicits
--   the the authentication status in the server reply. In most
--   applications (other than diagnostic tools) that want authenticated
--   data It is unwise to trust the AD bit in the responses of non-local
--   servers, this interface should in most cases only be used with a
--   loopback resolver.
lookupRawAD :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)

-- | Extract necessary information from DNSMessage
fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a

-- | For backward compatibility.

-- | Deprecated: Use fromDNSMessage instead
fromDNSFormat :: 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 lookupA function, if successful, will
--   return a list of IPv4. The lookupMX function will
--   instead return a list of (Domain,Int) 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 sort to the returned
--   list.
--   
--   The errors that can occur are the same for all lookups. Namely:
--   
--   
--   
- Timeout
--   
- Wrong sequence number (foul play?)
--   
- Unexpected data in the response
--   
--   
--   If an error occurs, you should be able to pattern match on the
--   DNSError constructor to determine which of these is the case.
--   
--   Note: 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 Right [].
--   
--   We perform a successful lookup of "www.example.com":
--   
--   
--   >>> let hostname = Data.ByteString.Char8.pack "www.example.com"
--   
--   >>> 
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupA resolver hostname
--   Right [93.184.216.34]
--   
--   
--   The only error that we can easily cause is a timeout. We do this by
--   creating and utilizing a ResolvConf which has a timeout of one
--   millisecond and a very limited number of retries:
--   
--   
--   >>> let hostname = Data.ByteString.Char8.pack "www.example.com"
--   
--   >>> let badrc = defaultResolvConf { resolvTimeout = 0, resolvRetry = 1 }
--   
--   >>> 
--   
--   >>> rs <- makeResolvSeed badrc
--   
--   >>> withResolver rs $ \resolver -> lookupA resolver hostname
--   Left RetryLimitExceeded
--   
--   
--   As is the convention, successful results will always be wrapped in a
--   Right while errors will be wrapped in a Left.
--   
--   For convenience, you may wish to enable GHC's OverloadedStrings
--   extension. This will allow you to avoid calling pack on each
--   domain name. See
--   https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#overloaded-string-literals
--   for more information. In the following examples, we assuem this
--   extension is enabled.
--   
--   All lookup functions eventually call lookupRaw. See its manual
--   to understand the concrete lookup behavior.
module Network.DNS.Lookup

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

-- | Look up all (IPv6) 'AAAA' records for the given hostname.
--   
--   Examples:
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupAAAA resolver "www.wide.ad.jp"
--   Right [2001:200:dff:fff1:216:3eff:fe4b:651c]
--   
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 (Domain, Int).
--   
--   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.
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupMX resolver "example.com"
--   Right []
--   
--   
--   The domain "mew.org" does however have a single MX:
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupMX resolver "mew.org"
--   Right [("mail.mew.org.",10)]
--   
--   
--   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 lookupA. The
--   priorities are not retained.
--   
--   Examples:
--   
--   
--   >>> import Data.List (sort)
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> ips <- withResolver rs $ \resolver -> lookupAviaMX resolver "wide.ad.jp"
--   
--   >>> fmap sort ips
--   Right [133.138.10.39,203.178.136.30]
--   
--   
--   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 lookupAAAA. 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. http://www.zytrax.com/books/dns/ch15/.
--   
--   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:
--   
--   
--   >>> import Data.List (sort)
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> ns <- withResolver rs $ \resolver -> lookupNS resolver "mew.org"
--   
--   >>> fmap sort ns
--   Right ["ns1.mew.org.","ns2.mew.org."]
--   
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 lookupNS for that). For details, see e.g.
--   http://www.zytrax.com/books/dns/ch15/.
--   
--   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:
--   
--   
--   >>> import Data.List (sort)
--   
--   >>> let ri = RCHostName "192.5.6.30" -- a.gtld-servers.net
--   
--   >>> let rc = defaultResolvConf { resolvInfo = ri }
--   
--   >>> rs <- makeResolvSeed rc
--   
--   >>> ns <- withResolver rs $ \resolver -> lookupNSAuth resolver "example.com"
--   
--   >>> fmap sort ns
--   Right ["a.iana-servers.net.","b.iana-servers.net."]
--   
lookupNSAuth :: Resolver -> Domain -> IO (Either DNSError [Domain])

-- | Look up all 'TXT' records for the given hostname. The results are
--   free-form ByteStrings.
--   
--   Two common uses for 'TXT' records are
--   http://en.wikipedia.org/wiki/Sender_Policy_Framework and
--   http://en.wikipedia.org/wiki/DomainKeys_Identified_Mail. As an
--   example, we find the SPF record for "mew.org":
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupTXT resolver "mew.org"
--   Right ["v=spf1 +mx -all"]
--   
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.
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupSOA resolver "mew.org"
--   Right [("ns1.mew.org.","kazu@mew.org.",201406240,3600,300,3600000,3600)]
--   
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:
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupPTR resolver "164.2.232.202.in-addr.arpa"
--   Right ["www.iij.ad.jp."]
--   
--   
--   The lookupRDNS function is more suited to this particular task.
lookupPTR :: Resolver -> Domain -> IO (Either DNSError [Domain])

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

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

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

-- | Perform both normalizeCase and normalizeRoot on the
--   given Domain. When comparing DNS names taken from user input,
--   this is often necessary to avoid unexpected results.
--   
--   Examples:
--   
--   
--   >>> let domain1 = BS.pack "ExAmPlE.COM"
--   
--   >>> let domain2 = BS.pack "example.com."
--   
--   >>> domain1 == domain2
--   False
--   
--   >>> normalize domain1 == normalize domain2
--   True
--   
--   
--   The normalize function should be idempotent:
--   
--   
--   >>> normalize (normalize domain1) == normalize domain1
--   True
--   
--   
--   Ensure that we don't crash on the empty Domain:
--   
--   
--   >>> import qualified Data.ByteString.Char8 as BS ( empty )
--   
--   >>> normalize BS.empty
--   "."
--   
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.
--   
--   Examples:
--   
--   
--   >>> let domain1 = BS.pack "ExAmPlE.COM"
--   
--   >>> let domain2 = BS.pack "exAMPle.com"
--   
--   >>> domain1 == domain2
--   False
--   
--   >>> normalizeCase domain1 == normalizeCase domain2
--   True
--   
--   
--   The normalizeCase function should be idempotent:
--   
--   
--   >>> normalizeCase (normalizeCase domain2) == normalizeCase domain2
--   True
--   
--   
--   Ensure that we don't crash on the empty Domain:
--   
--   
--   >>> import qualified Data.ByteString.Char8 as BS ( empty )
--   
--   >>> normalizeCase BS.empty
--   ""
--   
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:
--   
--   
--   
- a character string which represents a complete domain name (often
--   called 'absolute'). For example, 'poneria.ISI.EDU.'
--   
- 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.
--   
--   
--   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."
--   
--   Examples:
--   
--   
--   >>> let domain1 = BS.pack "example.com"
--   
--   >>> let domain2 = BS.pack "example.com."
--   
--   >>> domain1 == domain2
--   False
--   
--   >>> normalizeRoot domain1 == normalizeRoot domain2
--   True
--   
--   
--   The normalizeRoot function should be idempotent:
--   
--   
--   >>> normalizeRoot (normalizeRoot domain1) == normalizeRoot domain1
--   True
--   
--   
--   Ensure that we don't crash on the empty Domain:
--   
--   
--   >>> import qualified Data.ByteString.Char8 as BS ( empty )
--   
--   >>> normalizeRoot BS.empty
--   "."
--   
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. EDNS0 and TCP fallback are supported.
--   
--   Examples:
--   
--   
--   >>> rs <- makeResolvSeed defaultResolvConf
--   
--   >>> withResolver rs $ \resolver -> lookupA resolver "www.mew.org"
--   Right [210.130.207.72]
--   
module Network.DNS
