File Coverage

blib/lib/Future/IO/Resolver.pm

Criterion	Covered	Total	%
statement	31	32	96.8
branch	1	2	50.0
condition	1	3	33.3
subroutine	12	12	100.0
pod	4	5	80.0
total	49	54	90.7

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2026 -- [e-mail]

package Future::IO::Resolver 0.04;

use v5.20;
use warnings;

use feature qw( postderef signatures );
no warnings qw( experimental::postderef experimental::signatures );

use meta;
no warnings 'meta::experimental';

use Carp;

=head1 NAME

C - name resolver methods for L

=head1 SYNOPSIS

=for highlighter language=perl

   use Future::IO;
   use Future::IO::Resolver;

   use Socket qw( SOCK_STREAM );

   my $f = Future::IO::Resolver->getaddrinfo(
      host     => "metacpan.org",
      service  => "http",
      socktype => SOCK_STREAM,
   );
   # when complete, $f will yield socket address structures

=head1 DESCRIPTION

This package contains a selection of methods for performing name resolver
queries, running asynchronously via L. These are the sorts of
things typically performed as part of C attempts or other operations
where names have to be turned into numerical address structures, which may
involve communication with the outside world.

=head2 Implementation Details

This module can optionally use L to offload the name resolver
operations asynchronously. If this is unavailable, it will instead use the
regular resolver functions found in L, made asynchronous by calling
those functions from a forked side-car process. This is Implementated by a
flexible plugin system that allows other backends to be provided as well, as
may be found in other CPAN modules.

=cut

our @BACKENDS;

sub ADD_BACKEND
{
   shift;
   my ( $backend ) = @_;

   my $prio = $backend->RESOLVER_PRIORITY;

   my $idx = 0;
   $idx++ while $idx < scalar @BACKENDS and $prio > $BACKENDS[$idx]->RESOLVER_PRIORITY;

   splice @BACKENDS, $idx, 0, ( $backend );
}

# Attempt to load the distribution-supplied modules
require Future::IO::Resolver::Using::Socket;
require Future::IO::Resolver::Using::LibAsyncNS;

=head1 METHODS

=cut

my $metapkg = meta::get_this_package;

foreach my $method (qw( getaddrinfo getnameinfo res_query res_search )) {
   $metapkg->add_named_sub( $method => sub ( $, %args ) {
      foreach my $be ( @BACKENDS ) {
         $be->can( $method ) and
            return $be->$method( %args );
      }

      croak "Cannot find a Future::IO::Resolver backend to handle ->$method";
   } );
}

=head2 getaddrinfo

   @res = await Future::IO::Resolver->getaddrinfo( %args );

Perform a C resolve operation, which converts human-readable
descriptions of network addresses into socket-layer parameters and address
structures.

C<%args> should contain a C and C key, and may optionally also
specify C, C, C, C.

The returned list will contain HASH reference structures. Each will provide
C, C, C, C and optionally C.

=cut

=head2 getnameinfo

   ( $host, $service ) = await Future::IO::Resolver->getnameinfo( %args );

Perform a C resolve operation, which converts socket-layer
address structures into human-readable description strings containing names
or numbers.

C<%args> should contain a C key and may optionally also specify
C.

=cut

=head2 res_query

   $answer = Future::IO::Resolver->res_query( %args );

Perform a C resolve operation, which looks up DNS records of
various types, returning an answer in the form of a packed byte record. Code
using this method will need to understand how to unpack a DNS record from this
format.

C<%args> should contain a C and C key and may optionally also
specify C; though a default of the C class is applied.

=cut

=head2 res_search

   $answer = Future::IO::Resolver->res_search( %args );

Perform a C resolve operation, which looks up DNS records of
various types, returning an answer in the form of a packed byte record. Code
using this method will need to understand how to unpack a DNS record from this
format.

C<%args> should contain a C and C key and may optionally also
specify C; though a default of the C class is applied.

=cut

=head1 TODO

=over 4

=item *

Some wrapping of other resolvers, like the POSIX C family.

=item *

Add support for direct DNS-based resolving behaviour; possibly in its own
CPAN distribution.

=back

=head1 AUTHOR

Paul Evans

=cut

0x55AA;