view release on metacpan or  search on metacpan

lib/DNS/Unbound.pm  view on Meta::CPAN

Synchronous queries:

    my $res_hr = $dns->resolve( 'cpan.org', 'NS' );

    # See below about encodings in “data”.
    my @ns = map { $dns->decode_name($_) } @{ $res_hr->data() };

Asynchronous queries use L<the “Promise” pattern|https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises>. Assuming you’re using
an off-the-shelf event loop, you can do something like:

    my $dns = DNS::Unbound::AnyEvent->new();

    my $query1 = $dns->resolve_async( 'usa.gov', 'A' )->then(
        sub { my $data = shift()->data(); ... },  # success handler
        sub { ... },                              # failure handler
    );

    my $query2 = $dns->resolve_async( 'in-addr.arpa', 'NS' )->then(
        sub { ... },
        sub { ... },
    );

You can also integrate with a custom event loop; see L</"EVENT LOOPS"> below.

=cut

=head1 DESCRIPTION

Typical DNS lookups involve a request to a local server that caches
information from DNS. The caching makes it fast, but it also means
updates to DNS aren’t always available via that local server right away.
Most applications don’t need to care and so can enjoy the speed of
cached results.

Applications that need up-to-date DNS query results, though, need
I<fully-recursive> DNS queries. NLnet Labs’s
L<libunbound|https://www.nlnetlabs.nl/documentation/unbound/libunbound/>
is a popular solution for such queries; the present Perl module is an
interface to that library.

=head1 CHARACTER ENCODING

DNS doesn’t know about character encodings, so neither does Unbound.
Thus, all strings given to this module must be B<byte> B<strings>.
All returned strings will be byte strings as well.

=head1 EVENT LOOPS

This distribution includes the classes L<DNS::Unbound::AnyEvent>,
L<DNS::Unbound::IOAsync>, and L<DNS::Unbound::Mojo>, which provide
out-of-the-box compatibility with those popular event loop interfaces.
You should probably use one of these.

You can also integrate with a custom event loop via the C<fd()> method
of this class: wait for that file descriptor to be readable, then
call this class’s C<perform()> method.

=head1 MEMORY LEAK DETECTION

Objects in this namespace will, if left alive at global destruction,
throw a warning about memory leaks. To silence these warnings, either
allow all queries to complete, or cancel queries you no longer care about.

=head1 ERRORS

This library throws 3 kinds of errors:

=over

=item * Plain strings. Generally thrown in “simple” failure cases,
e.g., invalid inputs.

=item * L<DNS::Unbound::X::Unbound> instances. Thrown whenever
Unbound gives an error.

=item * L<DNS::Unbound::X::ResolveError> instances. A subclass
of the last kind, for (Unbound-reported) resolution failures.
(This is B<NOT> for DNS-reported failures.)

=back

=cut

#----------------------------------------------------------------------

use DNS::Unbound::Result ();
use DNS::Unbound::X      ();

# Load the default async query implementation.
# This may change when non-default implementations
# leave experimental status.
use DNS::Unbound::AsyncQuery::PromiseES6 ();

# Retain this to avoid having to load Net::DNS::Parameters
# except in unusual cases.
use constant _COMMON_RR => {
    A          => 1,
    AAAA       => 28,
    AFSDB      => 18,
    ANY        => 255,
    APL        => 42,
    CAA        => 257,
    CDNSKEY    => 60,
    CDS        => 59,
    CERT       => 37,
    CNAME      => 5,
    DHCID      => 49,
    DLV        => 32769,
    DNAME      => 39,
    DNSKEY     => 48,
    DS         => 43,
    HIP        => 55,
    HINFO      => 13,
    IPSECKEY   => 45,
    KEY        => 25,
    KX         => 36,
    LOC        => 29,
    MX         => 15,
    NAPTR      => 35,
    NS         => 2,