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.34]

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 DNSMessage)

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 (DNSMessage
          { header = DNSHeader
                       { identifier = 1,
                         flags = DNSFlags
                                   { qOrR = QR_Response,
                                     opcode = OP_STD,
                                     authAnswer = False,
                                     trunCation = False,
                                     recDesired = True,
                                     recAvailable = True,
                                     rcode = NoErr },
                       },
            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 = []})
 

fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a

Extract necessary information from DNSMessage

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

For backward compatibility.