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