RFC: Apache::PAR

[Nathan Byrd <na...@byrd.net>]

Hi all,

Below is a suggestion for a new set of modules, Apache::PAR,
Apache::PAR::Static, Apache::PAR::Registry, and Apache::PAR::PerlRun.  I
have initial coding and testing complete on these (except for some pod
documentation and test scripts), but wanted to post before moving
forward with CPAN, etc.

NAME: Apache::PAR
AUTHOR: Nathan Byrd <na...@byrd.net>
MODULES: Apache::PAR, Apache::PAR::Static, Apache::PAR::Registry,
Apache::PAR::PerlRun
DESCRIPTION:
Apache::PAR is a framework for including Perl ARchive files in a
mod_perl environment.  It allows an author to package up a web
application, including configuration, static files, Perl modules, and
Registry and PerlRun scripts to include in a single file.  This archive
can then be moved to other locations on the same system or distributed,
and loaded with a single set of configuration options in the Apache
configuration.  Scripts, modules, and content should continue to run
without modifications (see TODO below for current exception.)

These modules are based on PAR.pm by Autrijus Tang and Archive::Zip by
Ned Konz, as well as the mod_perl modules.  They extend the concept of
PAR files to mod_perl, similar to how WAR archives work for Java. An
archive (which is really a zip file), contains one or more elements
which can be served to clients making requests to an Apache web server. 
Below is a more complete description of each module:

MODULE: Apache::PAR
DESCRIPTION:
Performs the work of specifying the location of PAR archives and
allowing the loading of modules from these archives.  The files and
paths can be specified at load time.  Once an archive has been located,
an optional web.conf (filename configurable) is then loaded and included
into the main web configuration.  Once Apache::PAR has been loaded, Perl
Apache modules within these .par files can then be loaded (all the heavy
lifting for this is performed by PAR.pm.)  A sample Apache configuration
and web.conf is below:

httpd.conf (or mod_perl.conf):
PARDir /path/to/par/archive/directory
PARDir /path/to/another/archive/directory
...
PARFile /path/to/a/par/file.par
...
PerlModule Apache::PAR

web.conf (inside a .par file):
Alias /myapp/cgi-perl/ ##PARFILE##/
<Location /myapp/cgi-perl>
Options +ExecCGI
SetHandler perl-script
PerlHandler Apache::PAR::Registry
</Location>

PerlModule MyApp::TestMod
Alias /myapp/mod/ ##PARFILE##/
<Location /myapp/mod>
SetHandler perl-script
PerlHandler TestMod
</Location>

...

The web.conf is then included into the main Apache configuration at load
time (with appropriate substitutions for ##PARFILE##, etc)

MODULE: Apache::PAR::Static
DESCRIPTION:
The Apache::PAR::Static module allows a .par file creator to place any
static content into a .par archive (under a configurable directory in
the .par file) to be served directly to clients.  Currently, it supports
mime lookup with MIME::Types, byte range requests, customizable indexes
(with PARStaticDirectoryIndex), default mime types, etc.  A sample
configuration entry is below:
web.conf:
Alias /myapp/static/ ##PARFILE##/
<Location /myapp/static>
SetHandler perl-script
PerlHandler Apache::PAR::Static
PerlSetVar PARStaticDirectoryIndex index.htm
PerlAddVar PARStaticDirectoryIndex index.html
PerlSetVar PARStaticDefaultMIME text/html
</Location>

A page could then be accessed with a URL similar to the following:
http://127.0.0.1/myapp/static/
or
http://127.0.0.1/myapp/static/docs/docs.pdf

which would pull either an index.htm (or index.html), or docs/docs.pdf
file from the /static directory (configurable) within the .par file


MODULE: Apache::PAR::Registry
DESCRIPTION:
Apache::Registry (actually, Apache::RegistryNG) subclass which serves
Apache::Registry scripts to clients.  Current features include: The
configuration can require .par archive to be executable (with Options
+ExecCGI), file modification time testing, path_info rewriting (Registry
scripts can still use path_info as normal), and Module loading from
within the .par archive (via PAR).  A sample configuration is below:
Alias /myapp/cgi-perl/ ##PARFILE##/
<Location /myapp/cgi-perl>
Options +ExecCGI
SetHandler perl-script
PerlHandler Apache::PAR::Registry
</Location>

A registry script could then be accessed with a URL similar to the
following:
http://127.0.0.1/myapp/cgi-perl/startreg.pl
or
http://127.0.0.1/myapp/cgi-perl/startreg.pl/extra/path/info

which would execute the startreg.pl script from the scripts/ directory
(configurable), and optionally set path_info to /extra/path/info

MODULE: Apache::PAR::PerlRun
DESCRIPTION:
Apache::PAR::PerlRun functions in the same way as Apache::PAR::Registry,
but is a child of Apache::PerlRun, and has the same
advantages/disadvantages as Apache::PerlRun, like cleaning up the
namespace after execution, etc.  A sample configuration is below:
Alias /myapp/cgi-run/ ##PARFILE##/
<Location /myapp/cgi-run>
Options +ExecCGI
SetHandler perl-script
PerlHandler Apache::PAR::PerlRun
</Location>
 registry script could then be accessed with a URL similar to the
following:
http://127.0.0.1/myapp/cgi-run/startrun.pl
or
http://127.0.0.1/myapp/cgi-perl/startrun.pl/extra/path/info

which would execute the startrun.pl script from the scripts/ directory
(configurable), and optionally set path_info to /extra/path/info

LICENSE: Same terms as Perl (GPL or Artistic License)

TODO:
Many things, including:
* Getting Apache::PAR::Static to read defaults from mod_dir
* More security testing
* Making it possible for other files to be loaded from within a .par
archive by Registry and PerlRun scripts (without coding changes to the
scripts?!)
* Platform testing - currently only tested on x86 linux, but should run
on any platform that supports PAR.pm and Archive::Zip
* Support for Apache 2/mod_perl 2
* Ability to limit configuration options available in web.conf files
* etc.

Please let me know what you think.  If the response is favorable, I will
attempt to get a .01 uploaded to CPAN as soon as possible.  Thank you,

-- 
Nathan Byrd <na...@byrd.net>