Network.DNS.Resolver

dns-2.0.1: 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)
- 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. 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.