ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/DNS.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/DNS.pm (file contents):
Revision 1.53 by root, Fri May 30 09:40:41 2008 UTC vs.
Revision 1.60 by root, Tue Jun 3 09:02:46 2008 UTC

… …
2 2
3AnyEvent::DNS - fully asynchronous DNS resolution 3AnyEvent::DNS - fully asynchronous DNS resolution
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::DNS; 7 use AnyEvent::DNS;
8 8
9 my $cv = AnyEvent->condvar; 9 my $cv = AnyEvent->condvar;
10 AnyEvent::DNS::a "www.google.de", $cv; 10 AnyEvent::DNS::a "www.google.de", $cv;
11 # ... later 11 # ... later
12 my @addrs = $cv->recv; 12 my @addrs = $cv->recv;
13 13
14=head1 DESCRIPTION 14=head1 DESCRIPTION
15 15
16This module offers both a number of DNS convenience functions as well 16This module offers both a number of DNS convenience functions as well
17as a fully asynchronous and high-performance pure-perl stub resolver. 17as a fully asynchronous and high-performance pure-perl stub resolver.
… …
35 35
36use AnyEvent (); 36use AnyEvent ();
37use AnyEvent::Handle (); 37use AnyEvent::Handle ();
38use AnyEvent::Util qw(AF_INET6); 38use AnyEvent::Util qw(AF_INET6);
39 39
40our $VERSION = '1.0'; 40our $VERSION = 4.12;
41 41
42our @DNS_FALLBACK = (v208.67.220.220, v208.67.222.222); 42our @DNS_FALLBACK = (v208.67.220.220, v208.67.222.222);
43 43
44=item AnyEvent::DNS::a $domain, $cb->(@addrs) 44=item AnyEvent::DNS::a $domain, $cb->(@addrs)
45 45
… …
65=item AnyEvent::DNS::srv $service, $proto, $domain, $cb->(@srv_rr) 65=item AnyEvent::DNS::srv $service, $proto, $domain, $cb->(@srv_rr)
66 66
67Tries to resolve the given service, protocol and domain name into a list 67Tries to resolve the given service, protocol and domain name into a list
68of service records. 68of service records.
69 69
70Each srv_rr is an array reference with the following contents: 70Each C<$srv_rr> is an array reference with the following contents:
71C<[$priority, $weight, $transport, $target]>. 71C<[$priority, $weight, $transport, $target]>.
72 72
73They will be sorted with lowest priority first, then randomly 73They will be sorted with lowest priority first, then randomly
74distributed by weight as per RFC 2782. 74distributed by weight as per RFC 2782.
75 75
… …
265 ptr $ptr, sub { 265 ptr $ptr, sub {
266 for my $name (@_) { 266 for my $name (@_) {
267 ++$cnt; 267 ++$cnt;
268 268
269 # () around AF_INET to work around bug in 5.8 269 # () around AF_INET to work around bug in 5.8
270 resolver->resolve ($name => ($af == (AF_INET) ? "a" : "aaaa"), sub { 270 resolver->resolve ("$name." => ($af == (AF_INET) ? "a" : "aaaa"), sub {
271 for (@_) { 271 for (@_) {
272 push @res, $name 272 push @res, $name
273 if $_->[3] eq $ip; 273 if $_->[3] eq $ip;
274 } 274 }
275 $cb->(@res) unless --$cnt; 275 $cb->(@res) unless --$cnt;
… …
397 397
398Resource records are not yet encodable. 398Resource records are not yet encodable.
399 399
400Examples: 400Examples:
401 401
402 # very simple request, using lots of default values: 402 # very simple request, using lots of default values:
403 { rd => 1, qd => [ [ "host.domain", "a"] ] } 403 { rd => 1, qd => [ [ "host.domain", "a"] ] }
404 404
405 # more complex example, showing how flags etc. are named: 405 # more complex example, showing how flags etc. are named:
406 406
407 { 407 {
408 id => 10000, 408 id => 10000,
409 op => "query", 409 op => "query",
410 rc => "nxdomain", 410 rc => "nxdomain",
411 411
412 # flags 412 # flags
413 qr => 1, 413 qr => 1,
414 aa => 0, 414 aa => 0,
415 tc => 0, 415 tc => 0,
416 rd => 0, 416 rd => 0,
417 ra => 0, 417 ra => 0,
418 ad => 0, 418 ad => 0,
419 cd => 0, 419 cd => 0,
420 420
421 qd => [@rr], # query section 421 qd => [@rr], # query section
422 an => [@rr], # answer section 422 an => [@rr], # answer section
423 ns => [@rr], # authority section 423 ns => [@rr], # authority section
424 ar => [@rr], # additional records section 424 ar => [@rr], # additional records section
425 } 425 }
426 426
427=cut 427=cut
428 428
429sub dns_pack($) { 429sub dns_pack($) {
430 my ($req) = @_; 430 my ($req) = @_;
… …
533 533
534Unpacks a DNS packet into a perl data structure. 534Unpacks a DNS packet into a perl data structure.
535 535
536Examples: 536Examples:
537 537
538 # an unsuccessful reply 538 # an unsuccessful reply
539 { 539 {
540 'qd' => [ 540 'qd' => [
541 [ 'ruth.plan9.de.mach.uni-karlsruhe.de', '*', 'in' ] 541 [ 'ruth.plan9.de.mach.uni-karlsruhe.de', '*', 'in' ]
542 ], 542 ],
543 'rc' => 'nxdomain', 543 'rc' => 'nxdomain',
544 'ar' => [], 544 'ar' => [],
545 'ns' => [ 545 'ns' => [
546 [ 546 [
547 'uni-karlsruhe.de', 547 'uni-karlsruhe.de',
548 'soa', 548 'soa',
549 'in', 549 'in',
550 'netserv.rz.uni-karlsruhe.de', 550 'netserv.rz.uni-karlsruhe.de',
551 'hostmaster.rz.uni-karlsruhe.de', 551 'hostmaster.rz.uni-karlsruhe.de',
552 2008052201, 10800, 1800, 2592000, 86400 552 2008052201, 10800, 1800, 2592000, 86400
553 ] 553 ]
554 ], 554 ],
555 'tc' => '', 555 'tc' => '',
556 'ra' => 1, 556 'ra' => 1,
557 'qr' => 1, 557 'qr' => 1,
558 'id' => 45915, 558 'id' => 45915,
559 'aa' => '', 559 'aa' => '',
560 'an' => [], 560 'an' => [],
561 'rd' => 1, 561 'rd' => 1,
562 'op' => 'query' 562 'op' => 'query'
563 } 563 }
564 564
565 # a successful reply 565 # a successful reply
566 566
567 { 567 {
568 'qd' => [ [ 'www.google.de', 'a', 'in' ] ], 568 'qd' => [ [ 'www.google.de', 'a', 'in' ] ],
569 'rc' => 0, 569 'rc' => 0,
570 'ar' => [ 570 'ar' => [
571 [ 'a.l.google.com', 'a', 'in', '209.85.139.9' ], 571 [ 'a.l.google.com', 'a', 'in', '209.85.139.9' ],
572 [ 'b.l.google.com', 'a', 'in', '64.233.179.9' ], 572 [ 'b.l.google.com', 'a', 'in', '64.233.179.9' ],
573 [ 'c.l.google.com', 'a', 'in', '64.233.161.9' ], 573 [ 'c.l.google.com', 'a', 'in', '64.233.161.9' ],
574 ], 574 ],
575 'ns' => [ 575 'ns' => [
576 [ 'l.google.com', 'ns', 'in', 'a.l.google.com' ], 576 [ 'l.google.com', 'ns', 'in', 'a.l.google.com' ],
577 [ 'l.google.com', 'ns', 'in', 'b.l.google.com' ], 577 [ 'l.google.com', 'ns', 'in', 'b.l.google.com' ],
578 ], 578 ],
579 'tc' => '', 579 'tc' => '',
580 'ra' => 1, 580 'ra' => 1,
581 'qr' => 1, 581 'qr' => 1,
582 'id' => 64265, 582 'id' => 64265,
583 'aa' => '', 583 'aa' => '',
584 'an' => [ 584 'an' => [
585 [ 'www.google.de', 'cname', 'in', 'www.google.com' ], 585 [ 'www.google.de', 'cname', 'in', 'www.google.com' ],
586 [ 'www.google.com', 'cname', 'in', 'www.l.google.com' ], 586 [ 'www.google.com', 'cname', 'in', 'www.l.google.com' ],
587 [ 'www.l.google.com', 'a', 'in', '66.249.93.104' ], 587 [ 'www.l.google.com', 'a', 'in', '66.249.93.104' ],
588 [ 'www.l.google.com', 'a', 'in', '66.249.93.147' ], 588 [ 'www.l.google.com', 'a', 'in', '66.249.93.147' ],
589 ], 589 ],
590 'rd' => 1, 590 'rd' => 1,
591 'op' => 0 591 'op' => 0
592 } 592 }
593 593
594=cut 594=cut
595 595
596sub dns_unpack($) { 596sub dns_unpack($) {
597 local $pkt = shift; 597 local $pkt = shift;
… …
698been resolved. 698been resolved.
699 699
700=item reuse => $seconds 700=item reuse => $seconds
701 701
702The number of seconds (default: C<300>) that a query id cannot be re-used 702The number of seconds (default: C<300>) that a query id cannot be re-used
703after a timeout. If there as no time-out then query id's can be reused 703after a timeout. If there was no time-out then query ids can be reused
704immediately. 704immediately.
705 705
706=back 706=back
707 707
708=cut 708=cut
… …
723 server => [], 723 server => [],
724 timeout => [2, 5, 5], 724 timeout => [2, 5, 5],
725 search => [], 725 search => [],
726 ndots => 1, 726 ndots => 1,
727 max_outstanding => 10, 727 max_outstanding => 10,
728 reuse => 300, # reuse id's after 5 minutes only, if possible 728 reuse => 300,
729 %arg, 729 %arg,
730 reuse_q => [], 730 reuse_q => [],
731 }, $class; 731 }, $class;
732 732
733 # search should default to gethostname's domain 733 # search should default to gethostname's domain
… …
838 # - the registry thing needs separate code on win32 native vs. cygwin 838 # - the registry thing needs separate code on win32 native vs. cygwin
839 # - the registry layout differs between windows versions 839 # - the registry layout differs between windows versions
840 # - calling windows api functions doesn't work on cygwin 840 # - calling windows api functions doesn't work on cygwin
841 # - ipconfig uses locale-specific messages 841 # - ipconfig uses locale-specific messages
842 842
843 # we use ipconfig parsing because, despite all it's brokenness, 843 # we use ipconfig parsing because, despite all its brokenness,
844 # it seems most stable in practise. 844 # it seems most stable in practise.
845 # for good measure, we append a fallback nameserver to our list. 845 # for good measure, we append a fallback nameserver to our list.
846 846
847 if (open my $fh, "ipconfig /all |") { 847 if (open my $fh, "ipconfig /all |") {
848 # parsing strategy: we go through the output and look for 848 # parsing strategy: we go through the output and look for
… …
857 } elsif (/^\S/ || /^\s[^:]{16,}: /) { 857 } elsif (/^\S/ || /^\s[^:]{16,}: /) {
858 $dns = 0; 858 $dns = 0;
859 } 859 }
860 if ($dns && /^\s*(\S+)\s*$/) { 860 if ($dns && /^\s*(\S+)\s*$/) {
861 my $s = $1; 861 my $s = $1;
862 $s =~ s/%\d+(?!\S)//; # get rid of scope id 862 $s =~ s/%\d+(?!\S)//; # get rid of ipv6 scope id
863 if (my $ipn = AnyEvent::Socket::parse_address ($s)) { 863 if (my $ipn = AnyEvent::Socket::parse_address ($s)) {
864 push @{ $self->{server} }, $ipn; 864 push @{ $self->{server} }, $ipn;
865 } else { 865 } else {
866 push @{ $self->{search} }, $s; 866 push @{ $self->{search} }, $s;
867 } 867 }
… …
884} 884}
885 885
886=item $resolver->timeout ($timeout, ...) 886=item $resolver->timeout ($timeout, ...)
887 887
888Sets the timeout values. See the C<timeout> constructor argument (and note 888Sets the timeout values. See the C<timeout> constructor argument (and note
889that this method uses the values itselt, not an array-reference). 889that this method uses the values itself, not an array-reference).
890 890
891=cut 891=cut
892 892
893sub timeout { 893sub timeout {
894 my ($self, @timeout) = @_; 894 my ($self, @timeout) = @_;
… …
1094 } 1094 }
1095} 1095}
1096 1096
1097=item $resolver->request ($req, $cb->($res)) 1097=item $resolver->request ($req, $cb->($res))
1098 1098
1099This is the main low-level workhorse for sending DNS requests.
1100
1099Sends a single request (a hash-ref formated as specified for 1101This function sends a single request (a hash-ref formated as specified
1100C<dns_pack>) to the configured nameservers including 1102for C<dns_pack>) to the configured nameservers in turn until it gets a
1103response. It handles timeouts, retries and automatically falls back to
1104virtual circuit mode (TCP) when it receives a truncated reply.
1105
1101retries. Calls the callback with the decoded response packet if a reply 1106Calls the callback with the decoded response packet if a reply was
1102was received, or no arguments on timeout. 1107received, or no arguments in case none of the servers answered.
1103 1108
1104=cut 1109=cut
1105 1110
1106sub request($$) { 1111sub request($$) {
1107 my ($self, $req, $cb) = @_; 1112 my ($self, $req, $cb) = @_;
… …
1112 1117
1113=item $resolver->resolve ($qname, $qtype, %options, $cb->($rcode, @rr)) 1118=item $resolver->resolve ($qname, $qtype, %options, $cb->($rcode, @rr))
1114 1119
1115Queries the DNS for the given domain name C<$qname> of type C<$qtype>. 1120Queries the DNS for the given domain name C<$qname> of type C<$qtype>.
1116 1121
1117A C<$qtype> is either a numerical query type (e.g. C<1> for A recods) or 1122A C<$qtype> is either a numerical query type (e.g. C<1> for A records) or
1118a lowercase name (you have to look at the source to see which aliases are 1123a lowercase name (you have to look at the source to see which aliases are
1119supported, but all types from RFC 1035, C<aaaa>, C<srv>, C<spf> and a few 1124supported, but all types from RFC 1035, C<aaaa>, C<srv>, C<spf> and a few
1120more are known to this module). A qtype of "*" is supported and means 1125more are known to this module). A C<$qtype> of "*" is supported and means
1121"any" record type. 1126"any" record type.
1122 1127
1123The callback will be invoked with a list of matching result records or 1128The callback will be invoked with a list of matching result records or
1124none on any error or if the name could not be found. 1129none on any error or if the name could not be found.
1125 1130
… …
1132the domain name, C<$type> a type string or number, C<$class> a class name 1137the domain name, C<$type> a type string or number, C<$class> a class name
1133and @data is resource-record-dependent data. For C<a> records, this will 1138and @data is resource-record-dependent data. For C<a> records, this will
1134be the textual IPv4 addresses, for C<ns> or C<cname> records this will be 1139be the textual IPv4 addresses, for C<ns> or C<cname> records this will be
1135a domain name, for C<txt> records these are all the strings and so on. 1140a domain name, for C<txt> records these are all the strings and so on.
1136 1141
1137All types mentioned in RFC 1035, C<aaaa>, C<srv> and C<spf> are 1142All types mentioned in RFC 1035, C<aaaa>, C<srv>, C<naptr> and C<spf> are
1138decoded. All resource records not known to this module will just return 1143decoded. All resource records not known to this module will have
1139the raw C<rdata> field as fourth entry. 1144the raw C<rdata> field as fourth entry.
1140 1145
1141Note that this resolver is just a stub resolver: it requires a name server 1146Note that this resolver is just a stub resolver: it requires a name server
1142supporting recursive queries, will not do any recursive queries itself and 1147supporting recursive queries, will not do any recursive queries itself and
1143is not secure when used against an untrusted name server. 1148is not secure when used against an untrusted name server.
… …
1148 1153
1149=item search => [$suffix...] 1154=item search => [$suffix...]
1150 1155
1151Use the given search list (which might be empty), by appending each one 1156Use the given search list (which might be empty), by appending each one
1152in turn to the C<$qname>. If this option is missing then the configured 1157in turn to the C<$qname>. If this option is missing then the configured
1153C<ndots> and C<search> define its value. If the C<$qname> ends in a dot, 1158C<ndots> and C<search> values define its value (depending on C<ndots>, the
1154then the searchlist will be ignored. 1159empty suffix will be prepended or appended to that C<search> value). If
1160the C<$qname> ends in a dot, then the searchlist will be ignored.
1155 1161
1156=item accept => [$type...] 1162=item accept => [$type...]
1157 1163
1158Lists the acceptable result types: only result types in this set will be 1164Lists the acceptable result types: only result types in this set will be
1159accepted and returned. The default includes the C<$qtype> and nothing 1165accepted and returned. The default includes the C<$qtype> and nothing
… …
1324 1330
1325=back 1331=back
1326 1332
1327=head1 AUTHOR 1333=head1 AUTHOR
1328 1334
1329 Marc Lehmann <schmorp@schmorp.de> 1335 Marc Lehmann <schmorp@schmorp.de>
1330 http://home.schmorp.de/ 1336 http://home.schmorp.de/
1331 1337
1332=cut 1338=cut
1333 1339

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines