view release on metacpan or  search on metacpan

Gateway.pm  view on Meta::CPAN

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>.

LocationMatch sections are tried in order until a regexp is matched.

=item Site URI

Sets an upstream server to contact for this URI.  In case of failure,
requests are automatically retried with successive sites in the order
they appear.  Failures can include anything from the upstream server
being down or flaky to a file not being present because the upstream
mirror is out of synch with its primary site.

=item MuxSite URI

Sets an upstream server to contact for this URI.  Adjacent C<MuxSite>
servers are tried in round robin order.

For example, here again is the default portion of the sample
GatewayConfig file above:

  <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>

With the C<Site> and C<MuxSite> directives here, the first request
will be forwarded to ftp.perl.org.  If it fails, the request will be
retried with cdrom, digital, orst, and funet, in that order.  The
next request for that process will be tried with ftp.perl.org first
again.  If it fails, retries then go to digital, cdrom, orst, and
finally funet.

A good general strategy for packages with multiple mirrors might be
to specify one or two nearby sites to try first.  Then specify some
multiplexed sites slightly further away in case the nearby sites
fail.  Finally, fall back to the primary site if all else fails.

=item ClockBroken server-URL upstream^2-TZ upstream-TZ

When caching is employed and requests can be gatewayed to multiple
mirrors, timestamp correctness becomes more important.  Unfortunately,
timestamps on mirrored files are usually wrong.  For example, the
popular Perl B<mirror> program is generally configured to match
timestamps using the local timezone both locally and on the server it
is mirroring.  This strategy is only guaranteed to work if both
servers are in the same timezone.

Example:
  ClockBroken ftp://ftp.cdrom.com	EET	PST8PDT