Apache2::HookRun - Perl API for Invoking Apache HTTP phases
# httpd.conf
PerlProcessConnectionHandler MyApache2::PseudoHTTP::handler
#file:MyApache2/PseudoHTTP.pm
#---------------------------
package MyApache2::PseudoHTTP;
use Apache2::HookRun ();
use Apache2::RequestUtil ();
use Apache2::RequestRec ();
use Apache2::Const -compile => qw(OK DECLINED DONE SERVER_ERROR);
# implement the HTTP protocol cycle in protocol handler
sub handler {
my $c = shift;
my $r = Apache2::RequestRec->new($c);
# register any custom callbacks here, e.g.:
# $r->push_handlers(PerlAccessHandler => \&my_access);
$rc = $r->run_post_read_request();
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_translate_name;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_map_to_storage;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
# this must be run all a big havoc will happen in the following
# phases
$r->location_merge($path);
$rc = $r->run_header_parser;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
my $args = $r->args || '';
if ($args eq 'die') {
$r->die(Apache2::Const::SERVER_ERROR);
return Apache2::Const::DONE;
}
$rc = $r->run_access_checker;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_auth_checker;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_check_user_id;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_type_checker;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_fixups;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
# $r->run_handler is called internally by $r->invoke_handler,
# invoke_handler sets all kind of filters, and does a few other
# things but it's possible to call $r->run_handler, bypassing
# invoke_handler
$rc = $r->invoke_handler;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
$rc = $r->run_log_transaction;
return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
return Apache2::Const::OK;
}
Apache2::HookRun exposes parts of the Apache HTTP protocol
implementation, responsible for invoking callbacks for each HTTP
Request cycle
phase.
Armed with that API, you could run some of the http protocol framework parts when implementing your own protocols. For example see how HTTP AAA (access, auth and authz) hooks are called from a protocol handler, implementing a command server, which has nothing to do with HTTP. Also you can see in Synopsis how to re-implement Apache HTTP cycle in the protocol handler.
Using this API you could probably also change the normal Apache behavior (e.g. invoking some hooks earlier than normal, or later), but before doing that you will probably need to spend some time reading through the Apache C code. That's why some of the methods in this document, point you to the specific functions in the Apache source code. If you just try to use the methods from this module, without understanding them well, don't be surprised if you will get some nasty crashes, from which mod_perl can't protect you.
Apache2::HookRun provides the following functions and/or methods:
die
Kill the current request
$r->die($type);
$r
( Apache2::RequestRec object )
$type ( integer )
This method doesn't really abort the request, it just handles the
sending of the error response, logging the error and such. You want
to take a look at the internals of ap_die() in
httpd-2.0/modules/http/http_request.c for more details.
invoke_handler
Run the response phase.
$rc = $r->invoke_handler();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::HTTP_...
invoke_handler() allows modules to insert filters, sets a default
handler if none is set, runs run_handler() and
handles some errors.
For more details see ap_invoke_handler() in
httpd-2.0/server/config.c.
run_access_checker
Run the resource access control phase.
$rc = $r->run_access_checker();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
This phase runs before a user is authenticated, so this hook is really
to apply additional restrictions independent of a user. It also runs
independent of 'Require' directive usage.
run_auth_checker
Run the authentication phase.
$rc = $r->run_auth_checker();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
This phase is used to check to see if the resource being requested is
available for the authenticated user ($r->user and
$r->ap_auth_type).
It runs after the access_checker and check_user_id hooks.
Note that it will only be called if Apache determines that access
control has been applied to this resource (through a 'Require'
directive).
run_check_user_id
Run the authorization phase.
$rc = $r->run_check_user_id();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
This hook is used to analyze the request headers, authenticate the
user, and set the user information in the request record
($r->user and $r->ap_auth_type).
This hook is only run when Apache determines that
authentication/authorization is required for this resource (as
determined by the 'Require' directive).
It runs after the access_checker hook, and before the auth_checker hook.
run_fixups
Run the fixup phase.
$rc = $r->run_fixups();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
This phase allows modules to perform module-specific fixing of HTTP header fields. This is invoked just before the response phase.
run_handler
Run the response phase.
$rc = $r->run_handler();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
run_handler() is called internally by
invoke_handler(). Use run_handler() only
if you want to bypass the extra functionality provided by
invoke_handler().
run_header_parser
Run the header parser phase.
$rc = $r->run_header_parser();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK or Apache2::Const::DECLINED.
run_log_transaction
Run the logging phase.
$rc = $r->run_log_transaction();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_...
This hook allows modules to perform any module-specific logging activities over and above the normal server things.
run_map_to_storage
Run the map_to_storage phase.
$rc = $r->run_map_to_storage();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::DONE (or Apache2::HTTP_*) if this contextless request was
just fulfilled (such as TRACE), Apache2::Const::OK if this is not a
file, and Apache2::Const::DECLINED if this is a file. The core
map_to_storage (Apache2::HOOK_RUN_LAST) will directory_walk() and
file_walk() the $r->filename (all internal C functions).
This phase allows modules to set the per_dir_config based on their own
context (such as <Proxy> sections) and responds to
contextless requests such as TRACE that need no security or
filesystem mapping based on the filesystem.
run_post_read_request
Run the post_read_request phase.
$rc = $r->run_post_read_request();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK or
Apache2::Const::DECLINED.
This phase is run right after read_request() or
internal_redirect(), and not run during any subrequests. This hook
allows modules to affect the request immediately after the request has
been read, and before any other phases have been processes. This
allows modules to make decisions based upon the input header fields
run_translate_name
Run the translate phase.
$rc = $r->run_translate_name();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
This phase gives modules an opportunity to translate the URI into an actual filename. If no modules do anything special, the server's default rules will be applied.
run_type_checker
Run the type_checker phase.
$rc = $r->run_type_checker();
$r
( Apache2::RequestRec object )
$rc ( integer )
Apache2::Const::OK,
Apache2::Const::DECLINED, Apache2::HTTP_....
This phase is used to determine and/or set the various document type
information bits, like Content-type (via $r->content_type),
language, etc.
mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.