NAME

Any::Daemon::HTTP::Proxy - proxy request to a remote server

INHERITANCE

Any::Daemon::HTTP::Proxy
  is a Any::Daemon::HTTP::Source

SYNOPSIS

my $proxy = Any::Daemon::HTTP::Proxy->new
  ( path => '/forward'
  );

my $vh = Any::Daemon::HTTP::VirtualHost->new(proxies => $proxy);

DESCRIPTION

[Available since v0.24] Warning: new code, not intensively tested.

There are two kinds of proxies:

Each Any::Daemon::HTTP::VirtualHost may define as many proxies as it needs, selected by location inside a server namespace, just like other directories.
The HTTP daemon itself collects proxies which use forward_map's; mapping incoming requests for many domains to many destination.

The current implementation does not support all features of proxies. For instance, reverse proxies are not yet implemented. Besides, it does not combine incoming connections into new outgoing connections.

Proxy loop detection is used by adding Via header fields (which can be removed explicitly).

See documentation in the base class.

METHODS

See documentation in the base class.

Constructors

See documentation in the base class.

Any::Daemon::HTTP::Proxy->new(OPTIONS|HASH-of-OPTIONS)

A proxy has either a path various, in which case it is part of a single VirtualHost, or has a forward_map when it becomes a child of the http daemon itself.

-Option            --Defined in               --Default
 add_req_headers                                []
 add_resp_headers                               []
 allow               Any::Daemon::HTTP::Source  <undef>
 change_request                                 undef
 change_response                                undef
 deny                Any::Daemon::HTTP::Source  <undef>
 forward_map                                    <undef>
 name                Any::Daemon::HTTP::Source  path
 path                Any::Daemon::HTTP::Source  '/'
 remote_proxy                                   undef
 reverse                                        true
 strip_req_headers                              []
 strip_resp_headers                             []
 user_agent                                     undef
 via                                            "$host:$port"

add_req_headers => ARRAY|CODE

add_resp_headers => ARRAY|CODE

allow => CIDR|HOSTNAME|DOMAIN|CODE|ARRAY

change_request => CODE

After adding and deleting headers, you may make other changes to the request. The CODE is called with the proxy object, request and (rewritten) uri as parameters.

change_response => CODE

After adding and deleting headers, you may make other changes to the request. The CODE is called with the proxy object, request and (rewritten) uri as parameters.

deny => CIDR|HOSTNAME|DOMAIN|CODE|ARRAY

forward_map => CODE|'RELAY'

When there is a forward_map, you can only add this proxy object to the daemon. The map describes how incoming domains need to be handled.

The special constant RELAY will make all requests being accepted and forwarded without uri rewrite.

name => STRING

path => PATH

remote_proxy => PROXY|CODE

When this proxy speak to an other PROXY. This can either be a fixed address or name, or computed for each request via a CODE reference.

reverse => BOOLEAN

Enable reverse proxy behavior as well, which means that redirection responses from the remote will be modified to have the redirected passing through this proxy as well.

strip_req_headers => NAME|REGEX|ARRAY|CODE

See stripHeaders().

strip_resp_headers => NAME|REGEX|ARRAY|CODE

See stripHeaders().

user_agent => LWP::UserAgent

via => WORD

To be included in the "Via" header line, which detects proxy loops.

Attributes

See documentation in the base class.

$obj->name(): See "Attributes" in Any::Daemon::HTTP::Source
$obj->path(): See "Attributes" in Any::Daemon::HTTP::Source
$obj->remoteProxy(SESSION, REQUEST): Returns the remote proxy to be used for REQUEST. If not set, then there is direct connection to the destination.
$obj->userAgent()
$obj->via()

Permissions

See documentation in the base class.

$obj->allow(SESSION, REQUEST, URI): See "Permissions" in Any::Daemon::HTTP::Source
$obj->collect(VHOST, SESSION, REQUEST, URI): See "Permissions" in Any::Daemon::HTTP::Source

Actions

See documentation in the base class.

Action

$obj->addHeaders(MESSAGE, PAIRS|ARRAY|CODE)

Add header lines to the request or response MESSAGE. Existing headers with the same name are retained.

add_req_headers   => [ Server => 'MSIE' ]
add_req_headers   => sub { my ($proxy,$msg,$uri) = @_; ... }

$obj->forwardRequest(SESSION, REQUEST, URI)

$obj->forwardRewrite(SESSION, REQUEST, URI)

$obj->proxify(REQUEST, URI)

The URI is the result of a rewrite of the destination mentioned in the REQUEST. To be able to forward the REQUEST to the next server, we need to rewrite its headers.

It is also possible the the original request originates from browser which is not configured for proxying. That will be repared as well.

$obj->stripHeaders(MESSAGE, NAME|REGEX|ARRAY|CODE|LIST)

Convert a specification about which headers should be stripped into a singled CODE reference to remove the specified fields from a request (to a proxy) or response (by the proxy).

strip_req_headers => 'ETag'
strip_req_headers => qr/^X-/
strip_req_headers => [ 'ETag', qr/^X-/ ]

strip_req_headers => sub { my ($proxy,$msg,$uri) = @_; ... }

DETAILS

See documentation in the base class.

Resource restrictions

See documentation in the base class.

Using the proxy-map

The proxy map will only be used when the access rules permit the client to access this source. When the map returns a new URI as result, that will be the new destination of the request. When undef is returned, there may be an other proxy specification which will accept it.

A typical usage could be:

Any::Daemon::HTTP::Proxy->new(forward_map => \&mapper);

sub mapper($$$)
{   my ($proxy, $session, $request, $uri) = @_;

    if(lc $uri->authority eq 'my.example.com')
    {   my $new = $uri->clone;
        $new->authority('somewhere.else.org');
        return $new;
    }

    undef;
}

You can do anything you need: build lookup tables, rewrite parameter lists, and more. However: the final URI needs to be an absolute URI. Please create regression tests for your mapper function.

Proxy to a proxy

An open forwarding proxy can be made with

Any::Daemon::HTTP::Proxy->new
  ( forward_map  => 'RELAY'
  , remote_proxy => 'proxy.firewall.me'
  );

LICENSE

Copyrights 2013-2014 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

To install Any::Daemon::HTTP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Any::Daemon::HTTP

CPAN shell

perl -MCPAN -e shell
install Any::Daemon::HTTP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

METHODS

Constructors

Attributes

Permissions

Actions

Action

DETAILS

Resource restrictions

Using the proxy-map

Proxy to a proxy

SEE ALSO

LICENSE

Module Install Instructions