dns-4.2.0: DNS library in Haskell

Safe Haskell | Safe-Inferred
Language | Haskell2010

Network.DNS.LookupRaw

Contents

- Lookups returning requested RData
- Lookups returning DNS Messages
- DNS Message procesing

Synopsis

- lookup :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])
- lookupAuth :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData])
- lookupRaw :: Resolver -> Domain -> TYPE -> IO (Either DNSError DNSMessage)
- lookupRawCtl :: Resolver -> Domain -> TYPE -> QueryControls -> IO (Either DNSError DNSMessage)
- lookupRawCtlRecv :: Resolver -> Domain -> TYPE -> QueryControls -> (Socket -> IO DNSMessage) -> IO (Either DNSError DNSMessage)
- fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a

# Lookups returning requested RData

lookup :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData]) Source #

Look up resource records of a specified type for a domain, collecting the results from the ANSWER section of the response. See the documentation 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]

lookupAuth :: Resolver -> Domain -> TYPE -> IO (Either DNSError [RData]) Source #

Look up resource records of a specified type for a domain, collecting the results from the AUTHORITY section of the response. See the documentation of `lookupRaw` to understand the concrete behavior. Cache is used even if `resolvCache` is `Just`.

# Lookups returning DNS Messages

lookupRaw Source #

Arguments

:: Resolver | Resolver obtained via `withResolver`
-> Domain | Query domain
-> TYPE | Query RRtype
-> IO (Either DNSError DNSMessage) |

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 EDNS if specifiecd). If it appears that the target DNS server does not support EDNS, it falls back to traditional queries.
- If the response is truncated, a new TCP socket bound to a new local port is created. Then exactly one TCP query is retried.

If multiple DNS servers 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 = []})

AXFR requests cannot be performed with this interface.

    >>> rs <- makeResolvSeed defaultResolvConf
    >>> withResolver rs $ \resolver -> lookupRaw resolver "mew.org" AXFR
    Left InvalidAXFRLookup

lookupRawCtl Source #

Arguments

:: Resolver | Resolver obtained via `withResolver`
-> Domain | Query domain
-> TYPE | Query RRtype
-> QueryControls | Query flag and EDNS overrides
-> IO (Either DNSError DNSMessage) |

Similar to `lookupRaw`, but the default values of the RD, AD, CD and DO flag bits, as well as various EDNS features, can be adjusted via the `QueryControls` parameter.

lookupRawCtlRecv Source #

Arguments

:: Resolver | Resolver obtained via `withResolver`
-> Domain | Query domain
-> TYPE | Query RRtype
-> QueryControls | Query flag and EDNS overrides
-> (Socket -> IO DNSMessage) | Action to receive message from socket
-> IO (Either DNSError DNSMessage) |

Similar to `lookupRawCtl`, but the recv action can be replaced with something other than `receive`. For example, in an environment where frequent retrieval of the current time is a performance issue, you can pass the time from outside instead of having `receive` retrieve the current time.

# DNS Message procesing

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

Messages with a non-error RCODE are passed to the supplied function for processing. Other messages are translated to `DNSError` instances.

Note that `NameError` is not a lookup error. The lookup is successful, bearing the sad news that the requested domain does not exist. `NameError` responses may return a meaningful AD bit, may contain useful data in the authority section, and even initial CNAME records that lead to the ultimately non-existent domain. Applications that wish to process the content of `NameError` (NXDomain) messages will need to implement their own RCODE handling.