NAME
    Mail::SpamAssassin::DnsResolver - DNS resolution engine

DESCRIPTION
    This is a DNS resolution engine for SpamAssassin, implemented in order
    to reduce file descriptor usage by Net::DNS and avoid a response
    collision bug in that module.

METHODS
    $res->load_resolver()
        Load the "Net::DNS::Resolver" object. Returns 0 if Net::DNS cannot
        be used, 1 if it is available.

    $resolver = $res->get_resolver()
        Return the "Net::DNS::Resolver" object.

    $res->configured_nameservers()
        Get a list of nameservers as configured by dns_server directives or
        as provided by Net::DNS, typically from /etc/resolv.conf

    $res->available_nameservers()
        Get or set a list of currently available nameservers, which is
        typically a known-to-be-good subset of configured nameservers

    $res->connect_sock()
        Re-connect to the first nameserver listed in "/etc/resolv.conf" or
        similar platform-dependent source, as provided by "Net::DNS".

    $res->get_sock()
        Return the "IO::Socket::INET" object used to communicate with the
        nameserver.

    $packet = new_dns_packet ($domain, $type, $class)
        A wrapper for "Net::DNS::Packet::new()" which traps a die thrown by
        it.

        To use this, change calls to "Net::DNS::Resolver::bgsend" from:

            $res->bgsend($domain, $type);

        to:

            $res->bgsend(Mail::SpamAssassin::DnsResolver::new_dns_packet($domain, $type, $class));

    $id = $res->bgsend($domain, $type, $class, $cb)
        Quite similar to "Net::DNS::Resolver::bgsend", except that when a
        reply packet eventually arrives, and "poll_responses" is called, the
        callback sub reference $cb will be called.

        Note that $type and $class may be "undef", in which case they will
        default to "A" and "IN", respectively.

        The callback sub will be called with three arguments -- the packet
        that was delivered, and an id string that fingerprints the query
        packet and the expected reply. The third argument is a timestamp
        (Unix time, floating point), captured at the time the packet was
        collected. It is expected that a closure callback be used, like so:

          my $id = $self->{resolver}->bgsend($domain, $type, undef, sub {
                my ($reply, $reply_id, $timestamp) = @_;
                $self->got_a_reply ($reply, $reply_id);
              });

        The callback can ignore the reply as an invalid packet sent to the
        listening port if the reply id does not match the return value from
        bgsend.

    $id = $res->bgread()
        Similar to "Net::DNS::Resolver::bgread". Reads a DNS packet from a
        supplied socket, decodes it, and returns a Net::DNS::Packet object
        if successful. Dies on error.

    $nfound = $res->poll_responses()
        See if there are any "bgsend" reply packets ready, and return the
        number of such packets delivered to their callbacks.

    $res->bgabort()
        Call this to release pending requests from memory, when aborting
        backgrounded requests, or when the scan is complete.
        "Mail::SpamAssassin::PerMsgStatus::check" calls this before
        returning.

    $packet = $res->send($name, $type, $class)
        Emulates "Net::DNS::Resolver::send()".

        This subroutine is a simple synchronous leftover from SpamAssassin
        version 3.3 and does not participate in packet query caching and
        callback grouping as implemented by
        AsyncLoop::bgsend_and_start_lookup(). As such it should be avoided
        for mainstream usage. Currently used through Mail::SPF::Server by
        the SPF plugin.

    $res->errorstring()
        Little more than a stub for callers expecting this from
        "Net::DNS::Resolver".

        If called immediately after a call to $res->send this will return
        "query timed out" if the $res->send DNS query timed out. Otherwise
        "unknown error or no error" will be returned.

        No other errors are reported.

    $res->finish_socket()
        Reset socket when done with it.

    $res->finish()
        Clean up for destruction.