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->loop_stop;
        },
        on_error => sub { die "Cannot resolve - $_[-1]\n" },
     );
 
     $loop->loop_forever;

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:

    *   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>