view release on metacpan or  search on metacpan

Gateway.pm  view on Meta::CPAN

=head1 NAME

Apache::Gateway - A Bloated Gateway Module

=head1 SYNOPSIS

Example B<Apache> configuration:

  <Location /CPAN/>
  SetHandler perl-script
  PerlHandler Apache::Gateway
  PerlSetVar GatewayConfig /etc/apache/gateway/CPAN
  PerlSetupEnv Off
  </Location>

Example GatewayConfig file:

  GatewayRoot /CPAN/
  
  <LocationMatch ".*">
  Site    ftp://ftp.perl.org/pub/perl/CPAN/
  MuxSite ftp://ftp.cdrom.com/pub/perl/CPAN/
  MuxSite ftp://ftp.digital.com/pub/plan/perl/CPAN/
  Site 	  ftp://ftp.orst.edu/pub/packages/CPAN/
  Site 	  ftp://ftp.funet.fi/pub/languages/perl/CPAN/
  </LocationMatch>
  
  ClockBroken ftp://ftp.cdrom.com	EET	PST8PDT
  ClockBroken ftp://ftp.digital.com	EET	PST8PDT
  ClockBroken ftp://ftp.orst.edu	EET	PST8PDT
  ClockBroken ftp://ftp.perl.org	CST	CST6CDT

See the examples directory for commented examples.

=head1 DESCRIPTION

The C<Apache::Gateway> module implements a gateway with assorted
optional features.

=head1 FEATURES

=over 4

=item Standard Gateway Features

C<Apache::Gateway> services requests using C<LWP> and, hence, can
gateway to any protocol that C<LWP> understands.  It also makes
foreign URIs appear to be local URIs.

C<Apache::Gateway> does not include a cache, but it can be used in
combination with a proxy cache to cache what the gateway retrieves.
For example, B<Apache> can provide caching for the gateway by setting
up a proxy cache virtual host and a gateway virtual host and then
using the proxy to access the gateway.

=item Automatic Failover with Mirrored Instances

Multiple mirrors can provide an instance.  Requests which fail will
automatically be retried with the next mirror.  This capability is
very useful when some mirrors are busy or erratic.

=item Multiplexing

Like the CPAN multiplexer, C<Apache::Gateway> can multiplex requests
amongst several mirrors.

=item Pattern-dependent Gatewaying

The origin server to contact can vary depending upon the URL.  This
capability is particularly useful when dealing with partial mirrors.
A common situation is that some files may be available at all mirrors,
but less commonly used files will only be available at a few mirrors.

=item FTP Directory Gatewaying

(Need to think of a better name for this feature.)  Remote FTP
directory listings can be modified to refer to the gateway.  This
feature is somewhat similar to the ProxyPassReverse directive.

This feature was especially complicated and problematical.  It has now
been removed.

=item Timestamp Correction

C<Apache::Gateway> can try to correct incorrect timestamps generated
by popular mirroring software.  In particular, it can try to
compensate for the way the Perl B<mirror> program sets timestamps.

=back

=head1 CONFIGURATION

Most configuration is done in the GatewayConfig files.  The regular
B<Apache> configuration files only need to include the handler
directives and set the C<GatewayConfig> filename.  Environment
variables are not used, so C<PerlSetupEnv> can be Off.

GatewayConfig directives purposely look like Apache config directives
so that the syntax will be familiar.  However, GatewayConfig
directives are not Apache config directives.  They cannot be used in
Apache config files (and vice versa)!

=over 4

=item GatewayRoot path

Sets the root of the gatewayed area on the local server.  Generally
matches the C<Location> setting in the B<Apache> config files.
Defaults to "/".

=item GatewayTimeout timeout

Passes timeout (in seconds) to C<LWP::UserAgent>.

=item LocationMatch regexp

Begins a LocationMatch section.  Works similarly to the ApacheLocation
match directive except that the pattern is a Perl regexp.  Note: there
are no C<Location> or other style sections, only C<LocationMatch>.