Network.DNS.Resolver

DNS Resolver and generic (lower-level) lookup functions.

Documentation

Configuration for resolver

data FileOrNumericHost

Union type for FilePath and HostName. Specify FilePath to "resolv.conf" or numeric IP address in String form.

Warning: Only numeric IP addresses are valid RCHostNames.

Example (using Google's public DNS cache):

>>> let cache = RCHostName "8.8.8.8"

Constructors

RCFilePath FilePath

A path for "resolv.conf"

RCHostName HostName

A numeric IP address

RCHostPort HostName PortNumber

A numeric IP address and port number

data ResolvConf

Type for resolver configuration. The easiest way to construct a ResolvConf object is to modify the defaultResolvConf.

Constructors

ResolvConf

Fields

resolvInfo :: FileOrNumericHost

resolvTimeout :: Int

Timeout in micro seconds.

resolvRetry :: Int

The number of retries including the first try.

resolvBufsize :: Integer

This field was obsoleted.

defaultResolvConf :: ResolvConf

Return a default ResolvConf:

• resolvInfo is RCFilePath "/etc/resolv.conf".
• resolvTimeout is 3,000,000 micro seconds.
• resolvRetry is 3.
• resolvBufsize is 512. (obsoleted)

Example (use Google's public DNS cache instead of resolv.conf):

>>> let cache = RCHostName "8.8.8.8"
>>> let rc = defaultResolvConf { resolvInfo = cache }

Intermediate data type for resolver

data ResolvSeed

Abstract data type of DNS Resolver seed. When implementing a DNS cache, this should be re-used.

makeResolvSeed :: ResolvConf -> IO ResolvSeed

Make a ResolvSeed from a ResolvConf.

Examples:

>>> rs <- makeResolvSeed defaultResolvConf

Type and function for resolver

data Resolver

Abstract data type of DNS Resolver When implementing a DNS cache, this MUST NOT be re-used.

Constructors

Resolver

Fields

genId :: IO Int

dnsSock :: Socket

dnsTimeout :: Int

dnsRetry :: Int

dnsBufsize :: Integer

withResolver :: ResolvSeed -> (Resolver -> IO a) -> IO a

Giving a thread-safe Resolver to the function of the second argument. A socket for UDP is opened inside and is surely closed.

withResolvers :: [ResolvSeed] -> ([Resolver] -> IO a) -> IO a

Giving thread-safe Resolvers to the function of the second argument. Sockets for UDP are opened inside and are surely closed.

Looking up functions

lookup :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RDATA])

Look up resource records for a domain, collecting the results from the ANSWER section of the response.

We repeat an example from Network.DNS.Lookup:

>>> let hostname = Data.ByteString.Char8.pack "www.example.com"
>>> rs <- makeResolvSeed defaultResolvConf
>>> withResolver rs $ \resolver -> lookup resolver hostname A
Right [93.184.216.119]

lookupAuth :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RDATA])

Look up resource records for a domain, collecting the results from the AUTHORITY section of the response.

Raw looking up function

lookupRaw :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSFormat)

Look up a name and return the entire DNS Response. Sample output is included below, however it is not tested -- the sequence number is unpredictable (it has to be!).

The example code:

   let hostname = Data.ByteString.Char8.pack "www.example.com"
   rs <- makeResolvSeed defaultResolvConf
   withResolver rs $ resolver -> lookupRaw resolver hostname A

And the (formatted) expected output:

   Right (DNSFormat
           { header = DNSHeader
                        { identifier = 1,
                          flags = DNSFlags
                                    { qOrR = QR_Response,
                                      opcode = OP_STD,
                                      authAnswer = False,
                                      trunCation = False,
                                      recDesired = True,
                                      recAvailable = True,
                                      rcode = NoErr },
                          qdCount = 1,
                          anCount = 1,
                          nsCount = 0,
                          arCount = 0},
             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 (RD ByteString)))

Like lookupRaw except that no unknown RDATA records are not split up into Ints.

fromDNSFormat :: DNSFormat -> (DNSFormat -> a) -> Either DNSError a

Extract necessary information from DNSFormat