.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Async::Resolver 3pm"
.TH IO::Async::Resolver 3pm 2024-02-04 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
"IO::Async::Resolver" \- performing name resolutions asynchronously
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This object is used indirectly via an IO::Async::Loop:
.PP
.Vb 2
\&   use Future::AsyncAwait;
\&   use IO::Async::Loop;
\&
\&   my $loop = IO::Async::Loop\->new;
\&
\&   my @results = await $loop\->resolver\->getaddrinfo(
\&      host    => "www.example.com",
\&      service => "http",
\&   );
\&
\&   foreach my $addr ( @results ) {
\&      printf "http://www.example.com can be reached at " .
\&         "socket(%d,%d,%d) + connect(\*(Aq%v02x\*(Aq)\en",
\&         @{$addr}{qw( family socktype protocol addr )};
\&   }
\&
\&   my @pwent = await $loop\->resolve( type => \*(Aqgetpwuid\*(Aq, data => [ $< ] );
\&
\&   print "My passwd ent: " . join( "|", @pwent ) . "\en";
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module extends an IO::Async::Loop to use the system's name resolver
functions asynchronously. It provides a number of named resolvers, each one
providing an asynchronous wrapper around a single resolver function.
.PP
Because the system may not provide asynchronous versions of its resolver
functions, this class is implemented using a IO::Async::Function object
that wraps the normal (blocking) functions. In this case, name resolutions
will be performed asynchronously from the rest of the program, but will likely
be done by a single background worker process, so will be processed in the
order they were requested; a single slow lookup will hold up the queue of
other requests behind it. To mitigate this, multiple worker processes can be
used; see the \f(CW\*(C`workers\*(C'\fR argument to the constructor.
.PP
The \f(CW\*(C`idle_timeout\*(C'\fR parameter for the underlying IO::Async::Function object
is set to a default of 30 seconds, and \f(CW\*(C`min_workers\*(C'\fR is set to 0. This
ensures that there are no spare processes sitting idle during the common case
of no outstanding requests.
.SH METHODS
.IX Header "METHODS"
The following methods documented in \f(CW\*(C`await\*(C'\fR expressions return Future
instances.
.SS resolve
.IX Subsection "resolve"
.Vb 1
\&   @result = await $loop\->resolve( %params );
.Ve
.PP
Performs a single name resolution operation, as given by the keys in the hash.
.PP
The \f(CW%params\fR hash keys the following keys:
.IP "type => STRING" 8
.IX Item "type => STRING"
Name of the resolution operation to perform. See BUILT-IN RESOLVERS for the
list of available operations.
.IP "data => ARRAY" 8
.IX Item "data => ARRAY"
Arguments to pass to the resolver function. Exact meaning depends on the
specific function chosen by the \f(CW\*(C`type\*(C'\fR; see BUILT-IN RESOLVERS.
.IP "timeout => NUMBER" 8
.IX Item "timeout => NUMBER"
Optional. Timeout in seconds, after which the resolver operation will abort
with a timeout exception. If not supplied, a default of 10 seconds will apply.
.PP
On failure, the fail category name is \f(CW\*(C`resolve\*(C'\fR; the details give the
individual resolver function name (e.g. \f(CW\*(C`getaddrinfo\*(C'\fR), followed by other
error details specific to the resolver in question.
.PP
.Vb 1
\&   \->fail( $message, resolve => $type => @details )
.Ve
.SS "resolve (void)"
.IX Subsection "resolve (void)"
.Vb 1
\&   $resolver\->resolve( %params );
.Ve
.PP
When not returning a future, additional parameters can be given containing the
continuations to invoke on success or failure:
.IP "on_resolved => CODE" 8
.IX Item "on_resolved => CODE"
A continuation that is invoked when the resolver function returns a successful
result. It will be passed the array returned by the resolver function.
.Sp
.Vb 1
\&   $on_resolved\->( @result )
.Ve
.IP "on_error => CODE" 8
.IX Item "on_error => CODE"
A continuation that is invoked when the resolver function fails. It will be
passed the exception thrown by the function.
.SS getaddrinfo
.IX Subsection "getaddrinfo"
.Vb 1
\&   @addrs = await $resolver\->getaddrinfo( %args );
.Ve
.PP
A shortcut wrapper around the \f(CW\*(C`getaddrinfo\*(C'\fR resolver, taking its arguments in
a more convenient form.
.IP "host => STRING" 8
.IX Item "host => STRING"
.PD 0
.IP "service => STRING" 8
.IX Item "service => STRING"
.PD
The host and service names to look up. At least one must be provided.
.IP "family => INT or STRING" 8
.IX Item "family => INT or STRING"
.PD 0
.IP "socktype => INT or STRING" 8
.IX Item "socktype => INT or STRING"
.IP "protocol => INT" 8
.IX Item "protocol => INT"
.PD
Hint values used to filter the results.
.IP "flags => INT" 8
.IX Item "flags => INT"
Flags to control the \f(CWgetaddrinfo(3)\fR function. See the \f(CW\*(C`AI_*\*(C'\fR constants in
Socket's \f(CW\*(C`getaddrinfo\*(C'\fR function for more detail.
.IP "passive => BOOL" 8
.IX Item "passive => BOOL"
If true, sets the \f(CW\*(C`AI_PASSIVE\*(C'\fR flag. This is provided as a convenience to
avoid the caller from having to import the \f(CW\*(C`AI_PASSIVE\*(C'\fR constant from
\&\f(CW\*(C`Socket\*(C'\fR.
.IP "timeout => NUMBER" 8
.IX Item "timeout => NUMBER"
Time in seconds after which to abort the lookup with a \f(CW\*(C`Timed out\*(C'\fR exception
.PP
On success, the future will yield the result as a list of HASH references;
each containing one result. Each result will contain fields called \f(CW\*(C`family\*(C'\fR,
\&\f(CW\*(C`socktype\*(C'\fR, \f(CW\*(C`protocol\*(C'\fR and \f(CW\*(C`addr\*(C'\fR. If requested by \f(CW\*(C`AI_CANONNAME\*(C'\fR then the
\&\f(CW\*(C`canonname\*(C'\fR field will also be present.
.PP
On failure, the detail field will give the error number, which should match
one of the \f(CW\*(C`Socket::EAI_*\*(C'\fR constants.
.PP
.Vb 1
\&   \->fail( $message, resolve => getaddrinfo => $eai_errno )
.Ve
.PP
As a specific optimisation, this method will try to perform a lookup of
numeric values synchronously, rather than asynchronously, if it looks likely
to succeed.
.PP
Specifically, if the service name is entirely numeric, and the hostname looks
like an IPv4 or IPv6 string, a synchronous lookup will first be performed
using the \f(CW\*(C`AI_NUMERICHOST\*(C'\fR flag. If this gives an \f(CW\*(C`EAI_NONAME\*(C'\fR error, then
the lookup is performed asynchronously instead.
.SS "getaddrinfo (void)"
.IX Subsection "getaddrinfo (void)"
.Vb 1
\&   $resolver\->getaddrinfo( %args );
.Ve
.PP
When not returning a future, additional parameters can be given containing the
continuations to invoke on success or failure:
.IP "on_resolved => CODE" 8
.IX Item "on_resolved => CODE"
Callback which is invoked after a successful lookup.
.Sp
.Vb 1
\&   $on_resolved\->( @addrs );
.Ve
.IP "on_error => CODE" 8
.IX Item "on_error => CODE"
Callback which is invoked after a failed lookup, including for a timeout.
.Sp
.Vb 1
\&   $on_error\->( $exception );
.Ve
.SS getnameinfo
.IX Subsection "getnameinfo"
.Vb 1
\&   ( $host, $service ) = await $resolver\->getnameinfo( %args );
.Ve
.PP
A shortcut wrapper around the \f(CW\*(C`getnameinfo\*(C'\fR resolver, taking its arguments in
a more convenient form.
.IP "addr => STRING" 8
.IX Item "addr => STRING"
The packed socket address to look up.
.IP "flags => INT" 8
.IX Item "flags => INT"
Flags to control the \f(CWgetnameinfo(3)\fR function. See the \f(CW\*(C`NI_*\*(C'\fR constants in
Socket's \f(CW\*(C`getnameinfo\*(C'\fR for more detail.
.IP "numerichost => BOOL" 8
.IX Item "numerichost => BOOL"
.PD 0
.IP "numericserv => BOOL" 8
.IX Item "numericserv => BOOL"
.IP "dgram => BOOL" 8
.IX Item "dgram => BOOL"
.PD
If true, set the \f(CW\*(C`NI_NUMERICHOST\*(C'\fR, \f(CW\*(C`NI_NUMERICSERV\*(C'\fR or \f(CW\*(C`NI_DGRAM\*(C'\fR flags.
.IP "numeric => BOOL" 8
.IX Item "numeric => BOOL"
If true, sets both \f(CW\*(C`NI_NUMERICHOST\*(C'\fR and \f(CW\*(C`NI_NUMERICSERV\*(C'\fR flags.
.IP "timeout => NUMBER" 8
.IX Item "timeout => NUMBER"
Time in seconds after which to abort the lookup with a \f(CW\*(C`Timed out\*(C'\fR exception
.PP
On failure, the detail field will give the error number, which should match
one of the \f(CW\*(C`Socket::EAI_*\*(C'\fR constants.
.PP
.Vb 1
\&   \->fail( $message, resolve => getnameinfo => $eai_errno )
.Ve
.PP
As a specific optimisation, this method will try to perform a lookup of
numeric values synchronously, rather than asynchronously, if both the
\&\f(CW\*(C`NI_NUMERICHOST\*(C'\fR and \f(CW\*(C`NI_NUMERICSERV\*(C'\fR flags are given.
.SS "getnameinfo (void)"
.IX Subsection "getnameinfo (void)"
.Vb 1
\&   $resolver\->getnameinfo( %args );
.Ve
.PP
When not returning a future, additional parameters can be given containing the
continuations to invoke on success or failure:
.IP "on_resolved => CODE" 8
.IX Item "on_resolved => CODE"
Callback which is invoked after a successful lookup.
.Sp
.Vb 1
\&   $on_resolved\->( $host, $service );
.Ve
.IP "on_error => CODE" 8
.IX Item "on_error => CODE"
Callback which is invoked after a failed lookup, including for a timeout.
.Sp
.Vb 1
\&   $on_error\->( $exception );
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS register_resolver
.IX Subsection "register_resolver"
.Vb 1
\&   register_resolver( $name, $code );
.Ve
.PP
Registers a new named resolver function that can be called by the \f(CW\*(C`resolve\*(C'\fR
method. All named resolvers must be registered before the object is
constructed.
.ie n .IP $name 8
.el .IP \f(CW$name\fR 8
.IX Item "$name"
The name of the resolver function; must be a plain string. This name will be
used by the \f(CW\*(C`type\*(C'\fR argument to the \f(CW\*(C`resolve\*(C'\fR method, to identify it.
.ie n .IP $code 8
.el .IP \f(CW$code\fR 8
.IX Item "$code"
A CODE reference to the resolver function body. It will be called in list
context, being passed the list of arguments given in the \f(CW\*(C`data\*(C'\fR argument to
the \f(CW\*(C`resolve\*(C'\fR method. The returned list will be passed to the
\&\f(CW\*(C`on_resolved\*(C'\fR callback. If the code throws an exception at call time, it will
be passed to the \f(CW\*(C`on_error\*(C'\fR continuation. If it returns normally, the list of
values it returns will be passed to \f(CW\*(C`on_resolved\*(C'\fR.
.SH "BUILT-IN RESOLVERS"
.IX Header "BUILT-IN RESOLVERS"
The following resolver names are implemented by the same-named perl function,
taking and returning a list of values exactly as the perl function does:
.PP
.Vb 6
\&   getpwnam getpwuid
\&   getgrnam getgrgid
\&   getservbyname getservbyport
\&   gethostbyname gethostbyaddr
\&   getnetbyname getnetbyaddr
\&   getprotobyname getprotobynumber
.Ve
.PP
The following three resolver names are implemented using the Socket module.
.PP
.Vb 3
\&   getaddrinfo
\&   getaddrinfo_array
\&   getnameinfo
.Ve
.PP
The \f(CW\*(C`getaddrinfo\*(C'\fR resolver takes arguments in a hash of name/value pairs and
returns a list of hash structures, as the \f(CW\*(C`Socket::getaddrinfo\*(C'\fR function
does. For neatness it takes all its arguments as named values; taking the host
and service names from arguments called \f(CW\*(C`host\*(C'\fR and \f(CW\*(C`service\*(C'\fR respectively;
all the remaining arguments are passed into the hints hash. This name is also
aliased as simply \f(CW\*(C`getaddrinfo\*(C'\fR.
.PP
The \f(CW\*(C`getaddrinfo_array\*(C'\fR resolver behaves more like the \f(CW\*(C`Socket6\*(C'\fR version of
the function. It takes hints in a flat list, and mangles the result of the
function, so that the returned value is more useful to the caller. It splits
up the list of 5\-tuples into a list of ARRAY refs, where each referenced array
contains one of the tuples of 5 values.
.PP
As an extra convenience to the caller, both resolvers will also accept plain
string names for the \f(CW\*(C`family\*(C'\fR argument, converting \f(CW\*(C`inet\*(C'\fR and possibly
\&\f(CW\*(C`inet6\*(C'\fR into the appropriate \f(CW\*(C`AF_*\*(C'\fR value, and for the \f(CW\*(C`socktype\*(C'\fR argument,
converting \f(CW\*(C`stream\*(C'\fR, \f(CW\*(C`dgram\*(C'\fR or \f(CW\*(C`raw\*(C'\fR into the appropriate \f(CW\*(C`SOCK_*\*(C'\fR value.
.PP
The \f(CW\*(C`getnameinfo\*(C'\fR resolver returns its result in the same form as \f(CW\*(C`Socket\*(C'\fR.
.PP
Because this module simply uses the system's \f(CW\*(C`getaddrinfo\*(C'\fR resolver, it will
be fully IPv6\-aware if the underlying platform's resolver is. This allows
programs to be fully IPv6\-capable.
.SH EXAMPLES
.IX Header "EXAMPLES"
The following somewhat contrieved example shows how to implement a new
resolver function. This example just uses in-memory data, but a real function
would likely make calls to OS functions to provide an answer. In traditional
Unix style, a pair of functions are provided that each look up the entity by
either type of key, where both functions return the same type of list. This is
purely a convention, and is in no way required or enforced by the
IO::Async::Resolver itself.
.PP
.Vb 2
\&   @numbers = qw( zero  one   two   three four
\&                  five  six   seven eight nine  );
\&
\&   register_resolver getnumberbyindex => sub {
\&      my ( $index ) = @_;
\&      die "Bad index $index" unless $index >= 0 and $index < @numbers;
\&      return ( $index, $numbers[$index] );
\&   };
\&
\&   register_resolver getnumberbyname => sub {
\&      my ( $name ) = @_;
\&      foreach my $index ( 0 .. $#numbers ) {
\&         return ( $index, $name ) if $numbers[$index] eq $name;
\&      }
\&      die "Bad name $name";
\&   };
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>