# NAME

DNS::Unbound - libunbound in Perl

# SYNOPSIS

    my $dns = DNS::Unbound->new()->set_option( verbosity => 2 );

    # This appears to be safe:
    $dns->enable_threads();

    my $verbosity = $dns->get_option( 'verbosity' );

    $dns->set_option( verbosity => 1 + $verbosity );

Synchronous queries:

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

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

Asynchronous queries use [the �憕romise�� pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises). Assuming you�胩e 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 ["EVENT LOOPS"](#event-loops) below.

# DESCRIPTION

This library is a Perl interface to NLNetLabs�䏭 widely-used
[Unbound](https://nlnetlabs.nl/projects/unbound/) recursive DNS resolver.

# CHARACTER ENCODING

All strings given to this module must be **byte** **strings**.
All returned strings will be byte strings as well.

# EVENT LOOPS

This distribution includes the classes [DNS::Unbound::AnyEvent](https://metacpan.org/pod/DNS::Unbound::AnyEvent),
[DNS::Unbound::IOAsync](https://metacpan.org/pod/DNS::Unbound::IOAsync), and [DNS::Unbound::Mojo](https://metacpan.org/pod/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 `fd()` method
of this class.

# METHODS

## _CLASS_->new()

Instantiates this class.

## $result\_hr = _OBJ_->resolve( $NAME, $TYPE \[, $CLASS \] )

Runs a synchronous query for a given $NAME and $TYPE. $TYPE may be
expressed numerically or, for convenience, as a string. $CLASS is
optional and defaults to 1 (`IN`), which is probably what you want.

Returns a [DNS::Unbound::Result](https://metacpan.org/pod/DNS::Unbound::Result) instance.

**NOTE:** libunbound doesn�脌 seem to offer effective controls for
timing out a synchronous query.
If timeouts are relevant for you, you probably need
to use `resolve_async()` instead.

## $query = _OBJ_->resolve\_async( $NAME, $TYPE \[, $CLASS \] );

Like `resolve()` but starts an asynchronous query rather than a
synchronous one.

This returns an instance of [DNS::Unbound::AsyncQuery](https://metacpan.org/pod/DNS::Unbound::AsyncQuery) (a subclass
thereof, to be precise).

If you�胩e using one of the special event interface subclasses
(e.g., [DNS::Unbound::IOAsync](https://metacpan.org/pod/DNS::Unbound::IOAsync)) then the returned promise will resolve
on its own. Otherwise, [see below](#custom-event-loop-integration)
for the methods you�耱l need to use in tandem with this one.

## _OBJ_->enable\_threads()

Sets _OBJ_�䏭 asynchronous queries to use threads rather than forking.
Off by default. Throws an exception if called after an asynchronous query has
already been sent.

Returns _OBJ_.

**NOTE:** Despite Perl�䏭 iffy relationship with threads, this appears
to work without issue.

## _OBJ_->set\_option( $NAME => $VALUE )

Sets a configuration option. Returns _OBJ_.

Note that this is basically just a passthrough to the underlying
`ub_ctx_set_option()` function and is thus subject to the same limitations
as that function; for example, you can�脌 set `verbosity` after the
configuration has been �𠨑inalized��. (So use `debuglevel()` for that
instead.)

## $value = _OBJ_->get\_option( $NAME )

Gets a configuration option�䏭 value.

## _OBJ_->debuglevel( $LEVEL )

Sets the debug level (an integer). Returns _OBJ_.

As of libunbound v1.9.2, this is just a way to set the `verbosity`
option regardless of whether the configuration is finalized.

## _OBJ_->debugout( $FD\_OR\_FH )

Accepts a file descriptor or Perl filehandle and designates that
as the destination for libunbound diagnostic information.

Returns _OBJ_.

## $str = _CLASS_->unbound\_version()

Gives the libunbound version string.

# METHODS FOR ALTERING RESOLVER LOGIC

The following parallel their equivalents in libunbound.
They return _OBJ_ and throw errors on failure.

## _OBJ_->hosts( $FILENAME )



## _OBJ_->resolveconf( $FILENAME )



# CUSTOM EVENT LOOP INTEGRATION

Unless otherwise noted, the following methods correspond to their
equivalents in libunbound. They return the same values as the
libunbound equivalents.

You don�脌 need these if you use one of the event loop subclasses
(which is recommended).

## _OBJ_->poll()



## _OBJ_->fd()



## _OBJ_->wait()



## _OBJ_->process()



## _OBJ_->count\_pending\_queries()

Returns the number of outstanding asynchronous queries.

# METHODS FOR DEALING WITH DNSSEC

The following correspond to their equivalents in libunbound
and will only work if the underlying libunbound version supports them.

They return _OBJ_ and throw errors on failure.

## _OBJ_->add\_ta()



## _OBJ_->add\_ta\_autr()



## _OBJ_->add\_ta\_file()



## _OBJ_->trustedkeys()



# CONVENIENCE FUNCTIONS

The following may be called either as object methods or as static
functions (but not as class methods). In addition to these,
[Socket](https://metacpan.org/pod/Socket) provides the `inet_ntoa()` and `inet_ntop()`
functions for decoding the values of `A` and `AAAA` records.

**NOTE:** Consider parsing [DNS::Unbound::Result](https://metacpan.org/pod/DNS::Unbound::Result)�䏭 `answer_packet()`
with [Net::DNS::Packet](https://metacpan.org/pod/Net::DNS::Packet) as a more robust, albeit heavier, way to
parse query result data.

## $decoded = decode\_name($encoded)

Decodes a DNS name. Useful for, e.g., `NS`, `CNAME`, and `PTR` query
results.

Note that this function�䏭 return will normally include a trailing `.`
because of the trailing NUL byte in an encoded DNS name. This is normal
and expected.

## $strings\_ar = decode\_character\_strings($encoded)

Decodes a list of character-strings into component strings,
returned as an array reference. Useful for `TXT` query results.

# LICENSE & COPYRIGHT

Copyright 2019 Gasper Software Consulting.

This library is licensed under the same terms as Perl itself.

# REPOSITORY

[https://github.com/FGasper/p5-DNS-Unbound](https://github.com/FGasper/p5-DNS-Unbound)

# THANK YOU

Special thanks to [ATOOMIC](https://metacpan.org/author/ATOOMIC) for
making some helpful review notes.