stas 2004/08/17 23:29:08
Modified: src/docs/2.0/api/Apache HookRun.pod
Log:
complete Apache::HookRun
Revision Changes Path
1.4 +310 -138 modperl-docs/src/docs/2.0/api/Apache/HookRun.pod
Index: HookRun.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/HookRun.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -u -r1.3 -r1.4
--- HookRun.pod 22 May 2004 02:03:27 -0000 1.3
+++ HookRun.pod 18 Aug 2004 06:29:07 -0000 1.4
@@ -1,22 +1,112 @@
=head1 NAME
-Apache::HookRun - Perl API for XXX
+Apache::HookRun - Perl API for Invoking Apache HTTP phases
=head1 Synopsis
+ # httpd.conf
+ PerlProcessConnectionHandler MyApache::PseudoHTTP::handler
+
+ #file:MyApache/PseudoHTTP.pm
+ #---------------------------
+ package MyApache::PseudoHTTP;
+
use Apache::HookRun ();
+ use Apache::RequestUtil ();
+ use Apache::RequestRec ();
+
+ use Apache::Const -compile => qw(OK DECLINED DONE SERVER_ERROR);
+
+ # implement the HTTP protocol cycle in protocol handler
+ sub handler {
+ my $c = shift;
+ my $r = Apache::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 == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_translate_name;
+ return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_map_to_storage;
+ return $rc unless $rc == Apache::OK or $rc == Apache::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 == Apache::OK or $rc == Apache::DECLINED;
+
+ my $args = $r->args || '';
+ if ($args eq 'die') {
+ $r->die(Apache::SERVER_ERROR);
+ return Apache::DONE;
+ }
+
+ $rc = $r->run_access_checker;
+ return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_auth_checker;
+ return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_check_user_id;
+ return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_type_checker;
+ return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_fixups;
+ return $rc unless $rc == Apache::OK or $rc == Apache::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 == Apache::OK or $rc == Apache::DECLINED;
+
+ $rc = $r->run_log_transaction;
+ return $rc unless $rc == Apache::OK or $rc == Apache::DECLINED;
+
+ return Apache::OK;
+ }
-META: to be completed
=head1 Description
-META: to be completed
+C<Apache::HookRun> exposes parts of the Apache HTTP protocol
+implementation, responsible for invoking callbacks for each L<HTTP
+Request cycle
+phase|docs::2.0::user::handlers::http/HTTP_Request_Cycle_Phases>.
+
+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 L<a command
+server|docs::2.0::user::handlers::protocols/Command_Server>, which has
+nothing to do with HTTP. Also you can see in L<Synopsis|/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.
+
+
@@ -28,9 +118,11 @@
-=head2 C<die>
-META: Autogenerated - needs to be reviewed/completed
+
+
+
+=head2 C<die>
Kill the current request
@@ -38,152 +130,178 @@
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item arg1: C<$type> (XXX)
+=item arg1: C<$type> ( integer )
-Why the request is dieing
+Why the request is dieing. Expects an Apache status constant.
=item ret: no return value
+=item since: 1.99_12
+
=back
+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 C<ap_die()> in
+F<httpd-2.0/modules/http/http_request.c> for more details.
-=head2 C<invoke_handler>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<invoke_handler>
-Run the handler phase of each module until a module accepts the
-responsibility of serving the request
+Run the
+L<response|docs::2.0::user::handlers::http/PerlResponseHandler> phase.
- $ret = $r->invoke_handler();
+ $rc = $r->invoke_handler();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
-The status of the current request
+The status of the current phase run: C<Apache::OK>,
+C<Apache::HTTP_...>
+
+=item since: 1.99_12
=back
+C<invoke_handler()> allows modules to insert filters, sets a default
+handler if none is set, runs C<L<run_handler()|/C_run_handler_>> and
+handles some errors.
+
+For more details see C<ap_invoke_handler()> in
+F<httpd-2.0/server/config.c>.
+
+
-=head2 C<run_access_checker>
-META: Autogenerated - needs to be reviewed/completed
-This hook is used to apply additional access control to this resource.
-It 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.
+=head2 C<run_access_checker>
+
+Run the resource L<access
+control|docs::2.0::user::handlers::http/PerlAccessHandler> phase.
- $ret = $r->run_access_checker();
+ $rc = $r->run_access_checker();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
the current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+=item since: 1.99_12
=back
+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 'C<Require>' directive usage.
-=head2 C<run_auth_checker>
-META: Autogenerated - needs to be reviewed/completed
-This hook is used to check to see if the resource being requested is
-available for the authenticated user (r-E<gt>user and
-r-E<gt>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).
- $ret = $r->run_auth_checker();
+=head2 C<run_auth_checker>
-=over 4
+Run the
+L<authentication|docs::2.0::user::handlers::http/PerlAuthenHandler>
+phase.
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+ $rc = $r->run_auth_checker();
-the current request
+=over 4
-=item ret: C<$ret> (integer)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+the current request
-=back
+=item ret: C<$rc> ( integer )
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
+=item since: 1.99_12
+=back
+This phase is used to check to see if the resource being requested is
+available for the authenticated user (C<$r-E<gt>user> and
+C<$r-E<gt>ap_auth_type>).
-=head2 C<run_check_user_id>
+It runs after the L<access_checker|/C_run_access_checker_> and
+L<check_user_id|/C_run_auth_checker_> hooks.
-META: Autogenerated - needs to be reviewed/completed
+Note that it will only be called if Apache determines that access
+control has been applied to this resource (through a 'C<Require>'
+directive).
-This hook is used to analyze the request headers, authenticate the
-user, and set the user information in the request record (r-E<gt>user
-and r-E<gt>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.
- $ret = $r->run_check_user_id();
-=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
-The current request
-=item ret: C<$ret> (integer)
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+=head2 C<run_check_user_id>
-=back
+Run the
+L<authorization|docs::2.0::user::handlers::http/PerlAuthzHandler>
+phase.
+ $rc = $r->run_check_user_id();
+=over 4
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
+The current request
-=head2 C<run_create_request>
+=item ret: C<$rc> ( integer )
-META: Autogenerated - needs to be reviewed/completed
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
-Gives modules a chance to create their request_config entry when the
-request is created.
+=item since: 1.99_12
- $ret = $r->run_create_request();
+=back
-=over 4
+This hook is used to analyze the request headers, authenticate the
+user, and set the user information in the request record
+(C<$r-E<gt>user> and C<$r-E<gt>ap_auth_type>).
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+This hook is only run when Apache determines that
+authentication/authorization is required for this resource (as
+determined by the 'C<Require>' directive).
-The current request
+It runs after the L<access_checker|/C_run_access_checker_> hook, and
+before the L<auth_checker|/C_run_auth_checker_> hook.
-=item ret: C<$ret> (integer)
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
-=back
@@ -191,69 +309,90 @@
=head2 C<run_fixups>
-META: Autogenerated - needs to be reviewed/completed
-
-Allows modules to perform module-specific fixing of header fields. This
-is invoked just before any content-handler
+Run the L<fixup|docs::2.0::user::handlers::http/PerlFixupHandler>
+phase.
- $ret = $r->run_fixups();
+ $rc = $r->run_fixups();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
+
+=item since: 1.99_12
=back
+This phase allows modules to perform module-specific fixing of HTTP
+header fields. This is invoked just before the
+L<response|docs::2.0::user::handlers::http/PerlResponseHandler> phase.
+
-=head2 C<run_handler>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<run_handler>
-Run the handler functions for each module
+Run the
+L<response|docs::2.0::user::handlers::http/PerlResponseHandler> phase.
- $ret = $r->run_handler();
+ $rc = $r->run_handler();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The request_rec
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
+=item since: 1.99_12
=back
-non-wildcard handlers should HOOK_MIDDLE, wildcard HOOK_LAST
+C<run_handler()> is called internally by
+C<L<invoke_handler()|/C_invoke_handler_>>. Use C<run_handler()> only
+if you want to bypass the extra functionality provided by
+C<L<invoke_handler()|/C_invoke_handler_>>.
-=head2 C<run_header_parser>
-META: Autogenerated - needs to be reviewed/completed
-Run the header parser functions for each module
- $ret = $r->run_header_parser();
+
+
+=head2 C<run_header_parser>
+
+Run the L<header
+parser|docs::2.0::user::handlers::http/PerlHeaderParserHandler> phase.
+
+ $rc = $r->run_header_parser();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
-Apache::OK or Apache::DECLINED
+C<Apache::OK> or C<Apache::DECLINED>.
+
+=item since: 1.99_12
=back
@@ -263,134 +402,167 @@
=head2 C<run_log_transaction>
-META: Autogenerated - needs to be reviewed/completed
-
-This hook allows modules to perform any module-specific logging activities
-over and above the normal server things.
+Run the L<logging|docs::2.0::user::handlers::http/PerlLogHandler>
+phase.
- $ret = $r->run_log_transaction();
+ $rc = $r->run_log_transaction();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+=item since: 1.99_12
=back
+This hook allows modules to perform any module-specific logging
+activities over and above the normal server things.
+
-=head2 C<run_map_to_storage>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<run_map_to_storage>
-This hook allow modules to set the per_dir_config based on their own
-context (such as E<lt>ProxyE<gt> sections) and responds to contextless
-requests such as TRACE that need no security or filesystem mapping.
-based on the filesystem.
+Run the
+L<map_to_storage|docs::2.0::user::handlers::http/PerlMapToStorageHandler>
+phase.
- $ret = $r->run_map_to_storage();
+ $rc = $r->run_map_to_storage();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+C<Apache::DONE> (or C<Apache::HTTP_*>) if this contextless request was
+just fulfilled (such as C<TRACE>), C<Apache::OK> if this is not a
+file, and C<Apache::DECLINED> if this is a file. The core
+map_to_storage (C<Apache::HOOK_RUN_LAST>) will C<directory_walk()> and
+C<file_walk()> the C<$r-E<gt>filename> (all internal C functions).
-Apache::DONE (or Apache::HTTP_) if this contextless request was just
-fulfilled (such as TRACE), OK if this is not a file, and
-Apache::DECLINED if this is a file. The core map_to_storage
-(HOOK_RUN_LAST) will directory_walk and file_walk the r-E<gt>filename.
+=item since: 1.99_12
=back
+This phase allows modules to set the per_dir_config based on their own
+context (such as C<E<lt>ProxyE<gt>> sections) and responds to
+contextless requests such as C<TRACE> that need no security or
+filesystem mapping based on the filesystem.
+
+
=head2 C<run_post_read_request>
-META: Autogenerated - needs to be reviewed/completed
-post_read_request --- 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 the
+L<post_read_request|docs::2.0::user::handlers::http/PerlPostReadRequestHandler>
+phase.
- $ret = $r->run_post_read_request();
+ $rc = $r->run_post_read_request();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+The status of the current phase run: C<Apache::OK> or
+C<Apache::DECLINED>.
-Apache::OK or Apache::DECLINED
+=item since: 1.99_12
=back
+This phase is run right after C<read_request()> or
+C<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
+
=head2 C<run_translate_name>
-META: Autogenerated - needs to be reviewed/completed
+Run the L<translate|docs::2.0::user::handlers::http/PerlTransHandler>
+phase.
-This hook allow modules an opportunity to translate the URI into an
-actual filename. If no modules do anything special, the server's
-default rules will be followed.
-
- $ret = $r->run_translate_name();
+ $rc = $r->run_translate_name();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
The current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+=item since: 1.99_12
=back
+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.
+
=head2 C<run_type_checker>
-META: Autogenerated - needs to be reviewed/completed
+Run the
+L<type_checker|docs::2.0::user::handlers::http/PerlTypeHandler> phase.
-This routine is called to determine and/or set the various document
-type information bits, like Content-type (via r-E<gt>content_type),
-language, etc.
-
- $ret = $r->run_type_checker();
+ $rc = $r->run_type_checker();
=over 4
-=item obj: C<$r>
(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
+=item obj: C<$r>
+( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
the current request
-=item ret: C<$ret> (integer)
+=item ret: C<$rc> ( integer )
+
+The status of the current phase run: C<Apache::OK>,
+C<Apache::DECLINED>, C<Apache::HTTP_...>.
-Apache::OK, Apache::DECLINED, or Apache::HTTP_...
+=item since: 1.99_12
=back
+
+This phase is used to determine and/or set the various document type
+information bits, like C<Content-type> (via C<$r-E<gt>content_type>),
+language, etc.
+
+
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
