NAME
`IO::Async::Resolver::DNS' - resolve DNS queries using `IO::Async'
SYNOPSIS
use IO::Async::Loop;
use IO::Async::Resolver::DNS;
my $loop = IO::Async::Loop->new;
my $resolver = $loop->resolver;
$resolver->res_query(
dname => "cpan.org",
type => "MX",
on_resolved => sub {
my ( $pkt ) = @_;
foreach my $mx ( $pkt->answer ) {
next unless $mx->type eq "MX";
printf "preference=%d exchange=%s\n",
$mx->preference, $mx->exchange;
}
$loop->stop;
},
on_error => sub { die "Cannot resolve - $_[-1]\n" },
);
$loop->run;
DESCRIPTION
This module extends the IO::Async::Resolver class with extra methods and
resolver functions to perform DNS-specific resolver lookups. It does not
directly provide any methods or functions of its own.
These functions are provided for performing DNS-specific lookups, to
obtain `MX' or `SRV' records, for example. For regular name resolution,
the usual `getaddrinfo' and `getnameinfo' methods on the standard
`IO::Async::Resolver' should be used.
If Net::LibResolv is installed then it will be used for actually sending
and receiving DNS packets, in preference to a internally-constructed
Net::DNS::Resolver object. `Net::LibResolv' will be more efficient and
shares its implementation with the standard resolver used by the rest of
the system. `Net::DNS::Resolver' reimplements the logic itself, so it
may have differences in behaviour from that provided by libresolv. The
ability to use the latter is provided to allow for an XS-free dependency
chain, or for other situations where `Net::LibResolv' is not available.
Record Extraction
If certain record type queries are made, extra information is returned
to the `on_resolved' continuation, containing the results from the DNS
packet in a more useful form. This information will be in a list of
extra values following the packet value
$on_resolved->( $pkt, @data )
The type of the elements in `@data' will depend on the DNS record query
type:
* A and AAAA
The `A' or `AAAA' records will be unpacked and returned in a list of
strings.
@data = ( "10.0.0.1",
"10.0.0.2" );
@data = ( "fd00:0:0:0:0:0:0:1" );
* PTR
The `PTR' records will be unpacked and returned in a list of domain
names.
@data = ( "foo.example.com" );
* MX
The `MX' records will be unpacked, in order of `preference', and
returned in a list of HASH references. Each HASH reference will
contain keys called `exchange' and `preference'. If the exchange
domain name is included in the DNS `additional' data, then the HASH
reference will also include a key called `address', its value
containing a list of `A' and `AAAA' record `address' fields.
@data = ( { exchange => "mail.example.com",
preference => 10,
address => [ "10.0.0.1", "fd00:0:0:0:0:0:0:1" ] } );
* SRV
The `SRV' records will be unpacked and sorted first by order of
priority, then by a weighted shuffle by weight, and returned in a
list of HASH references. Each HASH reference will contain keys
called `priority', `weight', `target' and `port'. If the target
domain name is included in the DNS `additional' data, then the HASH
reference will also contain a key called `address', its value
containing a list of `A' and `AAAA' record `address' fields.
@data = ( { priority => 10,
weight => 10,
target => "server1.service.example.com",
port => 1234,
address => [ "10.0.1.1" ] } );
RESOLVER METHODS
$resolver->res_query( %params )
Performs a resolver query on the name, class and type, and invokes a
continuation when a result is obtained.
Takes the following named parameters:
dname => STRING
Domain name to look up
type => STRING
Name of the record type to look up (e.g. `MX')
class => STRING
Name of the record class to look up. Defaults to `IN' so
normally this argument is not required.
on_resolved => CODE
Continuation which is invoked after a successful lookup. Will be
passed a Net::DNS::Packet object containing the result.
$on_resolved->( $pkt )
For certain query types, this continuation may also be passed
extra data in a list after the `$pkt'
$on_resolved->( $pkt, @data )
See the Record Extraction section above for more detail.
on_error => CODE
Continuation which is invoked after a failed lookup.
$resolver->res_search( %params )
Performs a resolver query on the name, class and type, and invokes a
continuation when a result is obtained. Identical to `res_query' except
that it additionally implements the default domain name search
behaviour.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>