The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache2-CondProxy-0.17
River stage zero No dependents
++
/ Apache2::CondProxy

NAME

Apache2::CondProxy - Intelligent reverse proxy for missing resources

VERSION

Version 0.17

SYNOPSIS

    # httpd.conf
    PerlFixupHandler Apache2::CondProxy
    PerlSetVar ProxyTarget http://another.host/
    PerlSetVar RequestBodyCache /tmp
    PerlSetVar MatchScheme on

DESCRIPTION

This module performs the logic required to achieve what is implied by the following Apache configuration:

    # httpd.conf
    RewriteEngine On
    RewriteCond %{REQUEST_URI} !-U
    RewriteRule (.*) http://another.host$1 [P,NS]

Which says if I can't respond to a given request, try another.host. Unfortunately, the architecture of mod_rewrite, as well as the design of Apache's handler model itself, prohibits this. In the first case, all RewriteCond directives are evaluated after the associated RewriteRule. In the second, the response code is initialized to 200 and remains that way until it is changed, most likely by a response handler which never gets run. This confluence of behaviour makes the above configuration not do what we imagine it would.

This module works by running the request all the way through in a subrequest. Before doing so, a filter is installed to trap the subrequest's response. If the response is unsuccessful, specifically if it is a 403 or 404, the filter disposes of the error body, and the request is forwarded to the proxy target. The proxy URI scheme is matched to the original request URI scheme, so make sure you have SSLProxyEngine on.

If a proxy response contains a Location header, and its host is the same as the proxy target, that header will be rewritten to point to the source host.

DIRECTIVES

Configuration directives are currently carried out using PerlSetVar. Yep, I know. Consider them provisional. You will almost certainly need to reconfigure this module with proper Apache directives by the time I get to 0.20.

ProxyTarget

    ProxyTarget http://some.other.site/

This is the prefix of the location where requests go when they can't be served by the site where the request was originated. Note the path of the original request is appended relative to the path of this URI, as if its initial / was pruned off, so craft this URI accordingly.

RequestBodyCache

    RequestBodyCache /tmp/cond-proxy

In order to work with request content (e.g. POST, PUT), we have to stash it somewhere so we can replay it into the pipe. This means the contents of this directory are potentially sensitive. So if you're going to put it in /tmp, make sure to at least make it only readable to the server. Or you can have this module do that automatically, just make sure it can write to the parent.

MatchScheme

    MatchScheme on

This will cause the URI scheme in proxy requests (and Location headers from proxied responses) to match that of the originating request, be it http or https.

RemoteFirst

    RemoteFirst on

This will try to serve the resource at ProxyTarget first and then the local resource in case the remote resource responds with a 404. Note: Under the hood, this still checks the local resource first, due to a limitation of mod_proxy's handling of subrequests.

AUTHOR

Dorian Taylor, <dorian at cpan.org>

BUGS

Please report any bugs or feature requests to bug-apache2-filterfun at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache2-CondProxy. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Apache2::CondProxy

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2013 Dorian Taylor.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 .

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.