Paul Evans

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>