dns-2.0.10: DNS library in Haskell

Safe Haskell | None
Language | Haskell2010

Network.DNS.Resolver

Contents

- Documentation
  - Configuration for resolver
  - Intermediate data type for resolver
  - Type and function for resolver
  - Looking up functions
  - Raw looking up function

Description

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

Synopsis

- data FileOrNumericHost
  - = RCFilePath FilePath
  - | RCHostName HostName
  - | RCHostPort HostName PortNumber
- data ResolvConf = ResolvConf {
  - resolvInfo :: FileOrNumericHost
  - resolvTimeout :: Int
  - resolvRetry :: Int
  - resolvBufsize :: Integer
  }
- defaultResolvConf :: ResolvConf
- data ResolvSeed
- makeResolvSeed :: ResolvConf -> IO ResolvSeed
- data Resolver = Resolver {
  - genId :: IO Int
  - dnsSock :: Socket
  - dnsTimeout :: Int
  - dnsRetry :: Int
  - dnsBufsize :: Integer
  }
- withResolver :: ResolvSeed -> (Resolver -> IO a) -> IO a
- withResolvers :: [ResolvSeed] -> ([Resolver] -> IO a) -> IO a
- lookup :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])
- lookupAuth :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])
- lookupRaw :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)
- lookupRawAD :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)
- fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a
- fromDNSFormat :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a

# 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 `RCHostName`s.

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. Multiple `withResolver`s can be used concurrently. Multiple lookups must be done sequentially with a given `Resolver`. If multiple `Resolver`s are necessary for concurrent purpose, use `withResolvers`.

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

Giving thread-safe `Resolver`s to the function of the second argument. Sockets for UDP are opened inside and are surely closed. For each `Resolver`, multiple lookups must be done sequentially. `Resolver`s can be used concurrently.

## 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. If the initial UDP query elicits a truncated answer, the query is retried over TCP. The TCP retry may extend the total time taken by one more timeout beyond timeout * tries.

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,
                                         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 = []})

lookupRawAD :: 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.

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

Extract necessary information from `DNSMessage`

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

For backward compatibility.