gitpan / io-async-resolver-dns Goto Github PK

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 <[email protected]>