The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

LWP::UserAgent::DNS::Hosts - Override LWP HTTP/HTTPS request's host like /etc/hosts

SYNOPSIS

  use LWP::UserAgent;
  use LWP::UserAgent::DNS::Hosts;

  # add entry
  LWP::UserAgent::DNS::Hosts->register_host(
      'www.cpan.org' => '127.0.0.1',
  );

  # add entries
  LWP::UserAgent::DNS::Hosts->register_hosts(
      'search.cpan.org' => '192.168.0.100',
      'pause.perl.org'  => '192.168.0.101',
  );

  # read hosts file
  LWP::UserAgent::DNS::Hosts->read_hosts('/path/to/my/hosts');

  LWP::UserAgent::DNS::Hosts->enable_override;

  # override request hosts with peer addr defined above
  my $ua  = LWP::UserAgent->new;
  my $res = $ua->get("http://www.cpan.org/");
  print $res->content; # is same as "http://127.0.0.1/" content

DESCRIPTION

LWP::UserAgent::DNS::Hosts is a module to override HTTP/HTTPS request peer addresses that uses LWP::UserAgent.

This module concept was got from LWP::Protocol::PSGI.

METHODS

register_host($host, $peer_addr)
  LWP::UserAgent::DNS::Hosts->register_host($host, $peer_addr);

Registers a pair of hostname and peer ip address.

  # /etc/hosts
  127.0.0.1    example.com

equals to:

  LWP::UserAgent::DNS::Hosts->register_hosts('example.com', '127.0.0.1');
register_hosts(%host_addr_pairs)
  LWP::UserAgent::DNS::Hosts->register_hosts(
      'example.com' => '192.168.0.1',
      'example.org' => '192.168.0.2',
      ...
  );

Registers pairs of hostname and peer ip address.

read_hosts($file_or_string)
  LWP::UserAgent::DNS::Hosts->read_hosts('hosts.my');

  LWP::UserAgent::DNS::Hosts->read_hosts(<<'__HOST__');
      127.0.0.1      example.com
      192.168.0.1    example.net example.org
  __HOST__

Registers "/etc/hosts" syntax entries.

clear_hosts

Clears registered pairs.

enable_override
  LWP::UserAgent::DNS::Hosts->enable_override;
  my $guard = LWP::UserAgent::DNS::Hosts->enable_override;

Enables to override hook.

If called in a non-void context, returns a Guard object that automatically resets the override when it goes out of context.

disable_override
  LWP::UserAgent::DNS::Hosts->disable_override;

Disables to override hook.

If you use the guard interface described above, it will be automatically called for you.

AUTHOR

NAKAGAWA Masaki <masaki@cpan.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

LWP::Protocol, LWP::Protocol::http, LWP::Protocol::https