NAME

ParaDNS - a DNS lookup class for the Danga::Socket framework

SYNOPSIS

  ParaDNS->new(
    callback => sub { print "Got result $_[0] for query $_[1]\n" },
    host     => 'google.com',
  );

DESCRIPTION

This module performs asynchronous DNS lookups, making use of a single UDP socket (unlike Net::DNS's bgsend/bgread combination). It uses the Danga::Socket framework for high performance.

Currently this module will only perform A or PTR lookups. A rDNS (PTR) lookup will be performed if the host matches the regexp: /^\d+\.\d+\.\d+.\d+$/.

The lookups time out after 15 seconds.

API

ParaDNS->new( %options )

Create a new DNS query. You do not need to store the resulting object as this class is all done with callbacks.

Example:

  ParaDNS->new(
    callback => sub { print "Got result: $_[0]\n" },
    host => 'google.com',
    );

[required] callback

The callback to call when results come in. This should be a reference to a subroutine. The callback receives three parameters - the result of the DNS lookup, the host that was looked up, and the TTL (in seconds).

host

A host name to lookup. Note that if the hostname is a dotted quad of numbers then a reverse DNS (PTR) lookup is performend.

hosts

An array-ref list of hosts to lookup.

NOTE: One of either host or hosts is required.

client

It is possible to specify a client object which you wish to "pause" for reading until your DNS result returns. The client will be issued the ->pause_read method when the query is issued, and the ->continue_read method when the query returns.

This is used in Qpsmtpd where we want to wait until the DNS query returns before accepting more data from the client.

type

You can specify one of: "A", "AAAA", "PTR", "CNAME", "NS" or "TXT" here. Other types may be supported in the future. See %type_to_host in Resolver.pm for details, though more complex queries (e.g. SRV) may require a slightly more complex solution.

A PTR query is automatically issued if the host looks like an IP address.

nameservers

Normally, this module uses the name servers that are default for your system. You can specify an array-ref list of name servers to query.

Environment Variables

PARADNS_TIMEOUT

Default: 10

Number of seconds to wait for a query to come back.

PARADNS_REQUERY

Default: 2

Number of times to re-send a query when it times out.

PARADNS_NO_CACHE

Provides the ability to turn off the in-memory cache. Set to 1 to disable.

PARADNS_DEBUG

Provides internal debugging sent to STDERR. Set to 1 or higher to see more debugging output.

Stand-alone Use

Normal usage of ParaDNS is within another application that already uses the Danga::Socket framework. However if you wish to use this as a script to just issue thousands of DNS queries then you need to do a little more work. First, you need to set the SetPostLoopCallback, then issue the appropriate ParaDNS->new() call with your queries, and then launch the Danga event loop.

Eg:

    Danga::Socket->SetPostLoopCallback(
        sub {
            my $dmap = shift;
            for my $fd (keys %$dmap) {
                my $pob = $dmap->{$fd};
                if ($pob->isa('ParaDNS::Resolver')) {
                    return 1 if $pob->pending;
                }
            }
            return 0; # causes EventLoop to exit
        });

     # Call ParaDNS->new() with your parameters

     Danga::Socket->EventLoop();

LICENSE

This module is licensed under the same terms as perl itself.

AUTHOR

Matt Sergeant, <matt@sergeant.org>.