1NAME
2    `IO::Async::Resolver::DNS' - resolve DNS queries using `IO::Async'
3
4SYNOPSIS
5     use IO::Async::Loop;
6     use IO::Async::Resolver::DNS;
7
8     my $loop = IO::Async::Loop->new;
9     my $resolver = $loop->resolver;
10
11     $resolver->res_query(
12        dname => "cpan.org",
13        type  => "MX",
14     )->then( sub {
15        my ( $pkt ) = @_;
16
17        foreach my $mx ( $pkt->answer ) {
18           next unless $mx->type eq "MX";
19
20           printf "preference=%d exchange=%s\n",
21              $mx->preference, $mx->exchange;
22        }
23     })->get;
24
25DESCRIPTION
26    This module extends the IO::Async::Resolver class with extra methods and
27    resolver functions to perform DNS-specific resolver lookups. It does not
28    directly provide any methods or functions of its own.
29
30    These functions are provided for performing DNS-specific lookups, to
31    obtain `MX' or `SRV' records, for example. For regular name resolution,
32    the usual `getaddrinfo' and `getnameinfo' methods on the standard
33    `IO::Async::Resolver' should be used.
34
35    If Net::LibResolv is installed then it will be used for actually sending
36    and receiving DNS packets, in preference to a internally-constructed
37    Net::DNS::Resolver object. `Net::LibResolv' will be more efficient and
38    shares its implementation with the standard resolver used by the rest of
39    the system. `Net::DNS::Resolver' reimplements the logic itself, so it
40    may have differences in behaviour from that provided by libresolv. The
41    ability to use the latter is provided to allow for an XS-free dependency
42    chain, or for other situations where `Net::LibResolv' is not available.
43
44  Record Extraction
45    If certain record type queries are made, extra information is returned
46    to the `on_resolved' continuation, containing the results from the DNS
47    packet in a more useful form. This information will be in a list of
48    extra values following the packet value.
49
50     my ( $pkt, @data ) = $f->get;
51
52     $on_resolved->( $pkt, @data )
53
54    The type of the elements in `@data' will depend on the DNS record query
55    type:
56
57    * A and AAAA
58        The `A' or `AAAA' records will be unpacked and returned in a list of
59        strings.
60
61         @data = ( "10.0.0.1",
62                   "10.0.0.2" );
63
64         @data = ( "fd00:0:0:0:0:0:0:1" );
65
66    * PTR
67        The `PTR' records will be unpacked and returned in a list of domain
68        names.
69
70         @data = ( "foo.example.com" );
71
72    * MX
73        The `MX' records will be unpacked, in order of `preference', and
74        returned in a list of HASH references. Each HASH reference will
75        contain keys called `exchange' and `preference'. If the exchange
76        domain name is included in the DNS `additional' data, then the HASH
77        reference will also include a key called `address', its value
78        containing a list of `A' and `AAAA' record `address' fields.
79
80         @data = ( { exchange   => "mail.example.com",
81                     preference => 10,
82                     address    => [ "10.0.0.1", "fd00:0:0:0:0:0:0:1" ] } );
83
84    * SRV
85        The `SRV' records will be unpacked and sorted first by order of
86        priority, then by a weighted shuffle by weight, and returned in a
87        list of HASH references. Each HASH reference will contain keys
88        called `priority', `weight', `target' and `port'. If the target
89        domain name is included in the DNS `additional' data, then the HASH
90        reference will also contain a key called `address', its value
91        containing a list of `A' and `AAAA' record `address' fields.
92
93         @data = ( { priority => 10,
94                     weight   => 10,
95                     target   => "server1.service.example.com",
96                     port     => 1234,
97                     address  => [ "10.0.1.1" ] } );
98
99Error Reporting
100    The two possible back-end modules that implement the resolver query
101    functions provided here differ in their semantics for error reporting.
102    To account for this difference and to lead to more portable user code,
103    errors reported by the back-end modules are translated to one of the
104    following (exported) constants.
105
106     ERR_NO_HOST        # The specified host name does not exist
107     ERR_NO_ADDRESS     # The specified host name does not provide answers for the
108                          given query type
109     ERR_TEMPORARY      # A temporary failure that may disappear on retry
110     ERR_UNRECOVERABLE  # Any other error
111
112RESOLVER METHODS
113    The following methods documented with a trailing call to `->get' return
114    Future instances.
115
116  res_query
117       ( $pkt, @data ) = $resolver->res_query( %params )->get
118
119    Performs a resolver query on the name, class and type, and invokes a
120    continuation when a result is obtained.
121
122    Takes the following named parameters:
123
124    dname => STRING
125            Domain name to look up
126
127    type => STRING
128            Name of the record type to look up (e.g. `MX')
129
130    class => STRING
131            Name of the record class to look up. Defaults to `IN' so
132            normally this argument is not required.
133
134    On failure on `IO::Async' versions that support extended failure results
135    (0.68 and later), the extra detail will be an error value matching one
136    of the `ERR_*' constants listed above.
137
138     ->fail( $message, resolve => res_query => $errnum )
139
140    Note that due to the two possible back-end implementations it is not
141    guaranteed that messages have any particular format; they are intended
142    for human consumption only, and the `$errnum' value should be used for
143    making decisions in other code.
144
145    When not returning a `Future', the following extra arguments are used as
146    callbacks instead:
147
148    on_resolved => CODE
149            Continuation which is invoked after a successful lookup. Will be
150            passed a Net::DNS::Packet object containing the result.
151
152             $on_resolved->( $pkt )
153
154            For certain query types, this continuation may also be passed
155            extra data in a list after the `$pkt'
156
157             $on_resolved->( $pkt, @data )
158
159            See the Record Extraction section above for more detail.
160
161    on_error => CODE
162            Continuation which is invoked after a failed lookup.
163
164  res_search
165    Performs a resolver query on the name, class and type, and invokes a
166    continuation when a result is obtained. Identical to `res_query' except
167    that it additionally implements the default domain name search
168    behaviour.
169
170AUTHOR
171    Paul Evans <leonerd@leonerd.org.uk>
172
173