view release on metacpan or  search on metacpan

lib/AnyEvent/DNS/EtcHosts.pm  view on Meta::CPAN

package AnyEvent::DNS::EtcHosts;

=head1 NAME

AnyEvent::DNS::EtcHosts - Use /etc/hosts before DNS

=head1 SYNOPSIS

=for markdown ```perl

    use AnyEvent::DNS::EtcHosts;

    use AnyEvent::DNS;
    my $cv = AE::cv;
    AnyEvent::DNS::any 'example.com', sub {
        say foreach map { $_->[4] } grep { $_->[1] =~ /^(a|aaaa)$/ } @_;
        $cv->send;
    };

    use AnyEvent::Socket;
    my $cv = AE::cv;
    AnyEvent::Socket::resolve_sockaddr $domain, $service, $proto, $family, undef, sub {
        say foreach map { format_address((AnyEvent::Socket::unpack_sockaddr($_->[3]))[1]) } @_;
        $cv->send;
    };

=for markdown ```

=head1 DESCRIPTION

AnyEvent::DNS::EtcHosts changes AnyEvent::DNS behavior. The F</etc/hosts> file
is searched before DNS, so it is possible to override DNS entries.

The DNS lookups are emulated. This resolver returns the standard DNS reply
based on F</etc/hosts> file rather than real DNS.

You can choose a different file by changing C<PERL_ANYEVENT_HOSTS> environment
variable.

This module also disables the original L<AnyEvent::Socket>'s helper function
which reads F</etc/hosts> file after the DNS entry was not found. It prevents
reading this file twice.

The L<AnyEvent::Socket> resolver searches IPv4 and IPv6 addresses separately.
If you don't want to check the addresses in DNS, both IPv4 and IPv6 addresses
should be placed in F</etc/hosts> or the protocol family should be set
explicitly for C<resolve_sockaddr> function.

=for readme stop

=cut

use 5.008_001;

use strict;
use warnings;

our $VERSION = '0.0105';

use base 'AnyEvent::DNS';

use AnyEvent         ();
use AnyEvent::Socket ();

use constant DEBUG => $ENV{PERL_ANYEVENT_DNS_ETCHOSTS_DEBUG};
use if DEBUG, 'Data::Dumper';

our $GUARD;

=head1 IMPORTS

=head2 use AnyEvent::DNS::EtcHosts %args

=for markdown ```perl

use AnyEvent::DNS::EtcHosts server => '8.8.8.8';

$ perl -MAnyEvent::DNS::EtcHosts script.pl

=for markdown ```

Enables this module globally. Additional arguments will be passed to
L<AnyEvent::DNS> constructor.