POE::Component::Client::DNS - non-blocking, concurrent DNS requests

  use POE qw(Component::Client::DNS);

  my $named = POE::Component::Client::DNS->spawn(
    Alias => "named"
  );

  POE::Session->create(
    inline_states  => {
      _start   => \&start_tests,
      response => \&got_response,
    }
  );

  POE::Kernel->run();
  exit;

  sub start_tests {
    my $response = $named->resolve(
      event   => "response",
      host    => "localhost",
      context => { },
    );
    if ($response) {
      $_[KERNEL]->yield(response => $response);
    }
  }

  sub got_response {
    my $response = $_[ARG0];
    my @answers = $response->{response}->answer();

    foreach my $answer (@answers) {
      print(
        "$response->{host} = ",
        $answer->type(), " ",
        $answer->rdatastr(), "\n"
      );
    }
  }

POE::Component::Client::DNS provides a facility for non-blocking, concurrent DNS requests. Using POE, it allows other tasks to run while waiting for name servers to respond.

spawn

A program must spawn at least one POE::Component::Client::DNS instance before it can perform background DNS lookups. Each instance represents a connection to a name server, or a pool of them. If a program only needs to request DNS lookups from one server, then you only need one POE::Component::Client::DNS instance. As of version 0.98 you can override the default timeout per request. From this point forward there is no need to spawn multiple instances o affect different timeouts for each request. PoCo::Client::DNS's CWspawn method takes a few named parameters: Alias sets the component's alias. Requests will be posted to this alias. The component's alias defaults to resolver if one is not provided. Programs spawning more than one DNS client component must specify aliases for N-1 of them, otherwise alias collisions will occur.

  Alias => $session_alias,  # defaults to "resolver"

Timeout sets the component's default timeout. The timeout may be overridden per request. See the request event, later on. If no Timeout is set, the component will wait 90 seconds per request by default. Timeouts may be set to real numbers. Timeouts are more accurate if you have Time::HiRes installed. POE (and thus this component) will use Time::HiRes automatically if it's available.

  Timeout => $seconds_to_wait,  # defaults to 90

Nameservers holds a reference to a list of name servers to try. The list is passed directly to Net::DNS::Resolver's nameservers() method. By default, POE::Component::Client::DNS will query the name servers that appear in /etc/resolv.conf or its equivalent.

  Nameservers => \@name_servers,  # defaults to /etc/resolv.conf's

HostsFile (optional) holds the name of a specific hosts file to use for resolving hardcoded addresses. By default, it looks for a file named /etc/hosts. On Windows systems, it may look in the following other places:

  $ENV{SystemRoot}\System32\Drivers\Etc\hosts
  $ENV{SystemRoot}\System\Drivers\Etc\hosts
  $ENV{SystemRoot}\hosts

resolve

resolve() requests the component to resolve a host name. It will return a hash reference (described in RESPONSE MESSAGES, below) if it can honor the request immediately (perhaps from a cache). Otherwise it returns undef if a resolver must be consulted asynchronously. Requests are passed as a list of named fields.

  $resolver->resolve(
    class   => $dns_record_class,  # defaults to "IN"
    type    => $dns_record_type,   # defaults to "A"
    host    => $request_host,      # required
    context => $request_context,   # required
    event   => $response_event,    # required
    timeout => $request_timeout,   # defaults to spawn()'s Timeout
  );

The class and type fields specify what kind of information to return about a host. Most of the time internet addresses are requested for host names, so the class and type default to IN (internet) and A (address), respectively. The host field designates the host to look up. It is required. The event field tells the component which event to send back when a response is available. It is required, but it will not be used if resolve() can immediately return a cached response. timeout tells the component how long to wait for a response to this request. It defaults to the Timeout given at spawn() time. context includes some external data that links responses back to their requests. The context data is provided by the program that uses POE::Component::Client::DNS. The component will pass the context back to the program without modification. The context parameter is required, and may contain anything that fits in a scalar.

shutdown

shutdown() causes the component to terminate gracefully. It will finish serving pending requests then close down.

POE::Component::Client::DNS responds in one of two ways. Its resolve() method will return a response immediately if it can be found in the component's cache. Otherwise the component posts the response back in CW$_[ARG0]. In either case, the response is a hash reference containing the same fields:

  host     => $request_host,
  type     => $request_type,
  class    => $request_class,
  context  => $request_context,
  response => $net_dns_packet,
  error    => $net_dns_error,

POE - POE::Component::Client::DNS builds heavily on POE. Net::DNS - This module uses Net::DNS internally. Net::DNS::Packet - Responses are returned as Net::DNS::Packet objects.

This component does not yet expose the full power of Net::DNS. Timeouts have not been tested extensively. Please contact the author if you know of a reliable way to test DNS timeouts.

The older, list-based interfaces are no longer documented as of version 0.98. They are being phased out. The method-based interface, first implementedin version 0.98, will replace the deprecated interfaces after a six-month phase-out period. Version 0.98 was released in October of 2004. The deprecated interfaces will continue to work without warnings until January 2005. As of January 2005, programs that use the deprecated interfaces will continue to work, but they will generate mandatory warnings. Those warnings will persist until April 2005. As of April 2005 the mandatory warnings will be upgraded to mandatory errors. Support for the deprecated interfaces will be removed entirely.

POE::Component::Client::DNS is Copyright 1999-2004 by Rocco Caputo. All rights are reserved. POE::Component::Client::DNS is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Postback arguments were contributed by tag. Rocco may be contacted by e-mail via rcaputo@cpan.org.