cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2004/08/08 20:04:23
Modified:src/docs/2.0/user/handlers http.pod
Log:
document the issues with Content-length and HEAD requests
Revision ChangesPath
1.43 +94 -5 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -u -r1.42 -r1.43
--- http.pod 16 Jul 2004 01:11:03 - 1.42
+++ http.pod 9 Aug 2004 03:04:23 - 1.43
@@ -1593,25 +1593,114 @@
-=head1 Handling HEAD Requests
+
+
+
+
+=head1 Miscellaneous Issues
+
+
+=head2 Handling HEAD Requests
In order to avoid the overhead of sending the data to the client when
the request is of type HEAD in mod_perl 1.0 we Lused to return
early|docs::1.0::guide::porting/Generating_correct_HTTP_Headers from
the handler:
- return OK if $r-header_only;
+ return Apache::OK if $r-header_only;
+
+This logic should not be used in mod_perl 2.0, because Apache 2.0
+automatically discards the response body for HEAD requests. It expects
+the full body to generate the correct set of response headers, if you
+don't send the body you may encounter problems.
-This logic is no longer needed in mod_perl 2.0, because Apache 2.0
-automatically discards the response body for HEAD requests. (You can
-also read the comment in for Cap_http_header_filter() in
+(You can also read the comment in for Cap_http_header_filter() in
Imodules/http/http_protocol.c in the Apache 2.0 source.)
+
+
+
+
+=head2 CContent-Length Response Header
+
+You may encounter some issues with the C-L (CContent-Length)
+header. Some of them are discussed here.
+
+=over
+
+=item * The special case of CContent-Length: 0
+
+Since Apache proclaims itself governor of the C-L header via the C-L
+filter (ap_content_length_filter at Fhttpd-2.0/server/protocol.c),
+for the most part CGET and CHEAD behave exactly the same.
+However, when Apache sees a CHEAD request with a C-L header of zero
+it takes special action and removes the C-L header. This is done to
+protect against handlers that called C$r-Egtheader_only (Lwhich
+was ok in 1.3 but is not in 2.0|/Handling_HEAD_Requests). Therefore,
+CGET and CHEAD behave indentically, except when the content
+handler (and/or filters) end up sending no content. For more details
+refer to the lengthy comments in Cap_http_header_filter() in
+Fhttpd-2.0/modules/http/http_protocol.c).
+
+For more discussion on why it is important to get HEAD requests right,
+see these threads from the mod_perl list:
+
+ http://marc.theaimsgroup.com/?l=apache-modperlm=108647669726915w=2
+ http://marc.theaimsgroup.com/?t=10912298461r=1w=2
+
+as well as this bug report from mozilla, which shows how CHEAD
+requests are used in the wild:
+
+ http://bugzilla.mozilla.org/show_bug.cgi?id=245447
+
+=item * Not getting CContent-Length header with CHEAD requests
+
+Even though the spec says that content handlers should send an
+identical response for GET and HEAD requests, some folks try to
+Lavoid the overhead of generating the response
+body|/Handling_HEAD_Requests, which Apache is going to discard anyway
+for HEAD requests. The following discussion assumes that we deal with
+a HEAD request.
+
+When Apache sees EOS and no headers and no response body were sent,
+Cap_content_length_filter() (Fhttpd-2.0/server/protocol.c) sets
+C-L to 0. Later on Cap_http_header_filter()
+(Fhttpd-2.0/modules/http/http_protocol.c) removes the C-L header for
+the HEAD requests.
+
+The workaround is to force the sending of the response headers, before
+CEOS was sent (which happens when the response handler returns). The
+simplest solution is to use rflush():
+
+ if ($r-header_only) { # HEAD
+ $body_len = calculate_body_len();
+ $r-set_content_length($body_len);
+ $r-rflush;
+ }
+ else { # GET
+ # generate and send the body
+ }
+
+now if the handler sets the C-L header it'll be delivered to the
+client unmodified.
+
+=back
+
+
+
+
+
+
+
=head1 Extending HTTP Protocol
Extending HTTP under mod_perl is a trivial task. Look at Lthe
example of adding a new method CEMAIL|/PerlHeaderParserHandler for
details.
+
+
+
+
=head1 Maintainers
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2004/07/03 17:55:01 Modified:src/docs/2.0/user/handlers http.pod Log: remove dup Submitted by: David Arnold [EMAIL PROTECTED] Revision ChangesPath 1.37 +0 -2 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.36 retrieving revision 1.37 diff -u -u -r1.36 -r1.37 --- http.pod 10 Jun 2004 15:02:21 - 1.36 +++ http.pod 4 Jul 2004 00:55:01 - 1.37 @@ -773,8 +773,6 @@ use Apache::RequestUtil (); use Apache::Const -compile = qw(OK DECLINED HTTP_UNAUTHORIZED); - - use Apache::Access(); use constant SECRET_LENGTH = 14; - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2004/06/09 10:06:55
Modified:src/docs/2.0/user/handlers http.pod
Log:
fill in the PerlMapToStorageHandler gap
Revision ChangesPath
1.35 +67 -20modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -u -r1.34 -r1.35
--- http.pod 9 Jun 2004 16:17:42 - 1.34
+++ http.pod 9 Jun 2004 17:06:55 - 1.35
@@ -238,16 +238,14 @@
=head2 PerlTransHandler
-The Itranslate phase is used to perform the translation of a
-request's URI into an corresponding filename. If no custom handler is
-provided, the server's standard translation rules (e.g., CAlias
-directives, mod_rewrite, etc.) will continue to be used. A
-CPerlTransHandler handler can alter the default translation
-mechanism or completely override it.
-
-In addition to doing the translation, this stage can be used to modify
-the URI itself and the request method. This is also a good place to
-register new handlers for the following phases based on the URI.
+The Itranslate phase is used to perform the manipulation of a
+request's URI. If no custom handler is provided, the server's standard
+translation rules (e.g., CAlias directives, mod_rewrite, etc.) will
+be used. A CPerlTransHandler handler can alter the default
+translation mechanism or completely override it. This is also a good
+place to register new handlers for the following phases based on the
+URI. CLPerlMapToStorageHandler|/PerlMapToStorageHandler is to be
+used to override the URI to filename translation.
This phase is of type
CLRUN_FIRST|docs::2.0::user::handlers::intro/item_RUN_FIRST.
@@ -316,17 +314,11 @@
=head2 PerlMapToStorageHandler
The Imap_to_storage phase is used to perform the translation of a
-
-
-
-
request's URI into an corresponding filename. If no custom handler is
-provided, the server's standard translation rules (e.g., CAlias
-directives, mod_rewrite, etc.) will continue to be used. A
-CPerlTransHandler handler can alter the default translation
-mechanism or completely override it.
-
-META: add something here
+provided, the server will try to walk the filesystem trying to find
+what file or directory corresponds to the request's URI. Since usually
+mod_perl handler don't have corresponding files on the filesystem, you
+will want to shortcut this phase and save quite a few CPU cycles.
This phase is of type
CLRUN_FIRST|docs::2.0::user::handlers::intro/item_RUN_FIRST.
@@ -335,6 +327,61 @@
CLSRV|docs::2.0::user::config::config/item_SRV, because at this
phase the request has not yet been associated with a particular
filename or directory.
+
+For example if you don't want Apache to try to attempt to translate
+URI into a filename, just add a handler:
+
+ PerlMapToStorageHandler MyApache::NoTranslation
+
+using the following code:
+
+ file:MyApache/NoTranslation.pm
+ --
+ package MyApache::NoTranslation;
+
+ use strict;
+ use warnings FATAL = 'all';
+
+ use Apache::Const -compile = qw(OK);
+
+ sub handler {
+ my $r = shift;
+
+ # skip ap_directory_walk stat() calls
+ return Apache::OK;
+ }
+ 1;
+
+Apache also uses this phase to handle CTRACE requests. So if you
+shortcut it, CTRACE calls will be not handled. In case you need to
+handle such, you may rewrite it as:
+
+ file:MyApache/NoTranslation2.pm
+ ---
+ package MyApache::NoTranslation2;
+
+ use strict;
+ use warnings FATAL = 'all';
+
+ use Apache::RequestRec ();
+
+ use Apache::Const -compile = qw(DECLINED OK M_TRACE);
+
+ sub handler {
+ my $r = shift;
+
+ return Apache::DECLINED if $r-method_number == Apache::M_TRACE;
+
+ # skip ap_directory_walk stat() calls
+ return Apache::OK;
+ }
+ 1;
+
+Another way to prevent the core translation is to set
+C$r-Egtfilename() to some value, which can also be done in the
+CLPerlTransHandler|/PerlTransHandler, if you are already using it.
+
+
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2004/03/03 19:00:29 Modified:src/docs/2.0/user/handlers http.pod Log: CPerlCleanupHandler may fail to be completed on server shutdown/graceful restart since Apache will kill the registered handlers via SIGTERM, before they had a chance to run or even in the middle of its execution. Revision ChangesPath 1.31 +11 -0 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.30 retrieving revision 1.31 diff -u -u -r1.30 -r1.31 --- http.pod 10 Feb 2004 01:20:04 - 1.30 +++ http.pod 4 Mar 2004 03:00:29 - 1.31 @@ -1475,6 +1475,17 @@ temporary files get cleaned up as well. +=head3 Possible Caveats + +CPerlCleanupHandler may fail to be completed on server +shutdown/graceful restart since Apache will kill the registered +handlers via SIGTERM, before they had a chance to run or even in the +middle of its execution. See: +http://marc.theaimsgroup.com/?t=10638784523r=1w=2 +http://marc.theaimsgroup.com/?l=apache-modperl-devm=106427616108596w=2 + + + =head1 Handling HEAD Requests In order to avoid the overhead of sending the data to the client when - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2004/01/11 20:32:08 Modified:src/docs/2.0/user/handlers http.pod Log: add a link to stacked handlers Revision ChangesPath 1.26 +4 -4 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.25 retrieving revision 1.26 diff -u -u -r1.25 -r1.26 --- http.pod 1 Dec 2003 17:56:30 - 1.25 +++ http.pod 12 Jan 2004 04:32:08 - 1.26 @@ -68,10 +68,10 @@ about filters in detail later in this chapter. Before discussing each handler in detail remember that if you use -stacked handlers feature (META: add link to where it's discussed [go -read 1.0 docs for now, as it works the same]) all handlers in the -chain will be run as long as they return CApache::OK or -CApache::DECLINED. Because stacked handlers is a special case. So +Lthe stacked handlers +feature|docs::2.0::user::handlers::intro/Stacked_Handlers all +handlers in the chain will be run as long as they return CApache::OK +or CApache::DECLINED. Because stacked handlers is a special case. So don't be surprised if you've returned CApache::OK and the next handler was still executed. This is a feature, not a bug. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2004/01/12 00:49:38
Modified:src/docs/2.0/user/handlers http.pod
Log:
new section: HTTP Request Handler Skeleton
Revision ChangesPath
1.27 +41 -0 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -u -r1.26 -r1.27
--- http.pod 12 Jan 2004 04:32:08 - 1.26
+++ http.pod 12 Jan 2004 08:49:38 - 1.27
@@ -8,6 +8,47 @@
mod_perl.
+=head1 HTTP Request Handler Skeleton
+
+All HTTP Request handlers have the following structure:
+
+ package MyApache::MyHandlerName;
+
+ # load modules that are going to be used
+ use ...;
+
+ # compile (or import) constants
+ use Apache::Const -compile = qw(OK);
+
+ sub handler {
+ my $r = shift;
+
+ # handler code comes here
+
+ return Apache::OK; # or another status constant
+ }
+ 1;
+
+First, the package is declared. Next, the modules that are going to be
+used are loaded and constants compiled.
+
+The handler itself coming next and usually it receives the only
+argument: the
+CLApache::RequestRec|docs::2.0::api::Apache::RequestRec object.
+If the handler is declared as La method handler
+|docs::2.0::user::coding::coding/Method_Handlers:
+
+ sub handler : method {
+ my($class, $r) = @_;
+
+the handler receives two arguments: the class name and the
+CLApache::RequestRec|docs::2.0::api::Apache::RequestRec object.
+
+The handler ends with La return
+code|docs::2.0::user::handlers::intro/Stacked_Handlers and the file
+is ended with C1; to return true when it gets loaded.
+
+
=head1 HTTP Request Cycle Phases
Those familiar with mod_perl 1.0 will find the HTTP request cycle in
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
geoff 2003/12/01 09:56:30
Modified:src/docs/2.0/api/APR Const.pod
src/docs/2.0/api/Apache Const.pod
src/docs/2.0/user/coding coding.pod
src/docs/2.0/user/handlers http.pod
Log:
updates for :filetype, :mpmq, and Apache::MPM-is_threaded()
Revision ChangesPath
1.4 +36 -0 modperl-docs/src/docs/2.0/api/APR/Const.pod
Index: Const.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/APR/Const.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Const.pod 25 Aug 2003 01:17:13 - 1.3
+++ Const.pod 1 Dec 2003 17:56:30 - 1.4
@@ -294,6 +294,42 @@
+=head2 C:filetype
+
+ use APR::Const -compile = qw(:filetype);
+
+The C:filetype group is for XXX constants.
+
+=head3 CAPR::NOFILE
+
+
+=head3 CAPR::REG
+
+
+=head3 CAPR::DIR
+
+
+=head3 CAPR::CHR
+
+
+=head3 CAPR::BLK
+
+
+=head3 CAPR::PIPE
+
+
+=head3 CAPR::LNK
+
+
+=head3 CAPR::SOCK
+
+
+=head3 CAPR::UNKFILE
+
+
+
+
+
=head2 C:finfo
use APR::Const -compile = qw(:finfo);
1.4 +55 -0 modperl-docs/src/docs/2.0/api/Apache/Const.pod
Index: Const.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Const.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Const.pod 2 Oct 2003 13:33:29 - 1.3
+++ Const.pod 1 Dec 2003 17:56:30 - 1.4
@@ -438,6 +438,61 @@
+=head2 C:mpmq
+
+ use Apache::Const -compile = qw(:mpmq);
+
+The C:mpmq group is for querying MPM properties.
+
+=head3 CApache::MPMQ_NOT_SUPPORTED
+
+
+=head3 CApache::MPMQ_STATIC
+
+
+=head3 CApache::MPMQ_DYNAMIC
+
+
+=head3 CApache::MPMQ_MAX_DAEMON_USED
+
+
+=head3 CApache::MPMQ_IS_THREADED
+
+
+=head3 CApache::MPMQ_IS_FORKED
+
+
+=head3 CApache::MPMQ_HARD_LIMIT_DAEMONS
+
+
+=head3 CApache::MPMQ_HARD_LIMIT_THREADS
+
+
+=head3 CApache::MPMQ_MAX_THREADS
+
+
+=head3 CApache::MPMQ_MIN_SPARE_DAEMONS
+
+
+=head3 CApache::MPMQ_MIN_SPARE_THREADS
+
+
+=head3 CApache::MPMQ_MAX_SPARE_DAEMONS
+
+
+=head3 CApache::MPMQ_MAX_SPARE_THREADS
+
+
+=head3 CApache::MPMQ_MAX_REQUESTS_DAEMON
+
+
+=head3 CApache::MPMQ_MAX_DAEMONS
+
+
+
+
+
+
=head2 C:options
use Apache::Const -compile = qw(:options);
1.27 +3 -2 modperl-docs/src/docs/2.0/user/coding/coding.pod
Index: coding.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/coding/coding.pod,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- coding.pod8 Aug 2003 00:46:55 - 1.26
+++ coding.pod1 Dec 2003 17:56:30 - 1.27
@@ -75,10 +75,11 @@
If the code needs to behave differently depending on whether it's
running under one of the threaded MPMs, or not, the
-CApache::MPM_IS_THREADED constant can be used. For example:
+CApache::MPM-Egtis_threaded method can be used. For example:
+ use Apache::MPM ();
use APR::OS ();
- if (Apache::MPM_IS_THREADED) {
+ if (Apache::MPM-is_threaded) {
my $id = APR::OS::thread_current();
print current thread id: $id;
}
1.25 +2 -1 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- http.pod 14 Oct 2003 18:36:56 - 1.24
+++ http.pod 1 Dec 2003 17:56:30 - 1.25
@@ -1345,8 +1345,9 @@
names across threads and processes:
sub unique_id {
+ require Apache::MPM;
require APR::OS;
- return Apache::MPM_IS_THREADED
+ return Apache::MPM-is_threaded
? $$. . ${ APR::OS::thread_current() }
: $$;
}
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2003/06/18 01:35:29 Modified:src/docs/2.0/user/handlers http.pod Log: s/Apache::AUTH_REQUIRED/Apache::HTTP_UNAUTHORIZED/, the previous one is deprecated Submitted by: Shannon Eric Peevey [EMAIL PROTECTED] Revision ChangesPath 1.22 +8 -8 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.21 retrieving revision 1.22 diff -u -r1.21 -r1.22 --- http.pod 6 Jun 2003 09:24:46 - 1.21 +++ http.pod 18 Jun 2003 08:35:29 - 1.22 @@ -592,7 +592,7 @@ This phase is usually used to verify a user's identification credentials. If the credentials are verified to be correct, the handler should return CApache::OK. Otherwise the handler returns -CApache::AUTH_REQUIRED to indicate that the user has not +CApache::HTTP_UNAUTHORIZED to indicate that the user has not authenticated successfully. When Apache sends the HTTP header with this code, the browser will normally pop up a dialog box that prompts the user for login information. @@ -618,7 +618,7 @@ use Apache::Access (); use Apache::RequestUtil (); - use Apache::Const -compile = qw(OK DECLINED AUTH_REQUIRED); + use Apache::Const -compile = qw(OK DECLINED HTTP_UNAUTHORIZED); use Apache::Access(); @@ -634,7 +634,7 @@ if SECRET_LENGTH == length join , $r-user, $password; $r-note_basic_auth_failure; - return Apache::AUTH_REQUIRED; + return Apache::HTTP_UNAUTHORIZED; } 1; @@ -679,7 +679,7 @@ storing passwords in clear is a bad idea. Finally if our authentication fails the handler calls -note_basic_auth_failure() and returns CApache::AUTH_REQUIRED, which +note_basic_auth_failure() and returns CApache::HTTP_UNAUTHORIZED, which sets the proper HTTP response headers that tell the client that its user that the authentication has failed and the credentials should be supplied again. @@ -736,7 +736,7 @@ resource is password protected, similar to the auth phase. The handler is expected to return CApache::DECLINED to defer the decision, CApache::OK to indicate its acceptance of the user's authorization, -or CApache::AUTH_REQUIRED to indicate that the user is not +or CApache::HTTP_UNAUTHORIZED to indicate that the user is not authorized to access the requested document. This phase is of type @@ -759,7 +759,7 @@ use Apache::Access (); use Apache::RequestUtil (); - use Apache::Const -compile = qw(OK AUTH_REQUIRED); + use Apache::Const -compile = qw(OK HTTP_UNAUTHORIZED); use Apache::Access (); @@ -784,7 +784,7 @@ } $r-note_basic_auth_failure; - return Apache::AUTH_REQUIRED; + return Apache::HTTP_UNAUTHORIZED; } 1; @@ -804,7 +804,7 @@ authentication fails, i.e, calls: $r-note_basic_auth_failure; - return Apache::AUTH_REQUIRED; + return Apache::HTTP_UNAUTHORIZED; The configuration is similar to the one in Lthe previous section|/PerlAuthenHandler, this time we just add the - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2003/05/29 20:18:03
Modified:src/docs/2.0/user/handlers http.pod
Log:
add cleanup handler / pool cleanup handler examples and discussions
Revision ChangesPath
1.18 +196 -4modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- http.pod 6 Mar 2003 04:32:06 - 1.17
+++ http.pod 30 May 2003 03:18:03 - 1.18
@@ -1012,7 +1012,7 @@
Location /perl
SetHandler perl-script
- PerlResponseHandler ModPerl::Registry
+ PerlResponseHandler MyApache::WorldDomination
/Location
CSetHandler set to
@@ -1202,8 +1202,15 @@
=head2 PerlCleanupHandler
-The cleanup stage is used to execute some code when the request has
-been served.
+The cleanup stage is used to execute some code immediately after the
+request has been served (the client went away).
+
+There are several usages for this use phase. The obvious one is to run
+a cleanup code, for example removing temporarily created files. The
+less obvious is to use this phase instead of
+CLPerlLogHandler|/PerlLogHandler if the logging operation is time
+consuming. This approach allows to free the client as soon as the
+response is sent.
This phase is of type
CLRUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL.
@@ -1211,7 +1218,192 @@
The handler's configuration scope is
CLDIR|docs::2.0::user::config::config/item_DIR.
-META: examples are needed (for now mod_perl 1.0 docs apply)
+There are two different ways a cleanup handler can be registered:
+
+=over
+
+=item 1 Using the CPerlCleanupHandler phase
+
+ PerlCleanupHandler MyApache::Cleanup
+
+or:
+
+ $r-push_handlers(PerlCleanupHandler = \cleanup);
+
+This method is identical to all other handlers.
+
+In this technique the Ccleanup() callback accepts C$r as its only
+argument.
+
+=item 2 Using cleanup_register() method acting on the request object pool
+
+Since a request object pool is destroyed at the end of each request,
+we can register a cleanup callback which will be executed just before
+the pool is destroyed. For example:
+
+$r-pool-cleanup_register(\cleanup, $arg);
+
+The important difference from using the CPerlCleanupHandler handler,
+is that here you can pass any argument to the callback function, and
+no C$r argument is passed by default. Therefore if you need to pass
+any data other than C$r you may want to use this technique.
+
+=back
+
+Here is an example where the cleanup handler is used to delete a
+temporary file. The response handler is running Cls -l and stores
+the output in temporary file, which is then used by
+C$r-Egtsendfile to send the file's contents. We use
+Cpush_handlers() to push CPerlCleanupHandler to do unlink the file
+at the end of the request.
+
+ package MyApache::Cleanup1;
+
+ use strict;
+ use warnings FATAL = 'all';
+
+ use File::Spec::Functions qw(catfile);
+
+ use Apache::RequestRec ();
+ use Apache::RequestIO ();
+ use Apache::RequestUtil ();
+
+ use Apache::Const -compile = qw(OK DECLINED);
+ use APR::Const-compile = 'SUCCESS';
+
+ my $file = catfile /tmp, data;
+
+ sub handler {
+ my $r = shift;
+
+ $r-content_type('text/plain');
+
+ local @ENV{qw(PATH BASH_ENV)};
+ qx(/bin/ls -l $file);
+
+ my $status = $r-sendfile($file);
+ die sendfile has failed unless $status == APR::SUCCESS;
+
+ $r-push_handlers(PerlCleanupHandler = \cleanup);
+
+ return Apache::OK;
+ }
+
+ sub cleanup {
+ my $r = shift;
+
+ die Can't find file: $file unless -e $file;
+ unlink $file or die failed to unlink $file;
+
+ return Apache::OK;
+ }
+
+Next we add the following configuration:
+
+ Location /cleanup1
+ SetHandler modperl
+ PerlResponseHandler MyApache::Cleanup1
+ /Location
+
+Now when a request to I/cleanup1 is made, the contents of the
+current directory will be printed and once the request is over the
+temporary file is deleted.
+
+This response handler has a problem of running in a multiprocess
+environment, since it uses the same file, and several processes may
+try to read/write/delete that file at the same time, wrecking
+havoc. We could have appended the process id C$$ to the file's name,
+but remember that mod_perl 2.0 code may run in the threaded
+environment, meaning that there will be many threads running in the
+same process and the C$$ trick won't work any longer. Therefore one
+really has to use this code to create unique, but predictable, file
+names across threads and
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2003/02/17 21:33:23 Modified:src/docs/2.0/user/handlers http.pod Log: Handling HEAD Requests Revision ChangesPath 1.14 +14 -0 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.13 retrieving revision 1.14 diff -u -r1.13 -r1.14 --- http.pod 18 Feb 2003 04:29:41 - 1.13 +++ http.pod 18 Feb 2003 05:33:23 - 1.14 @@ -1193,6 +1193,20 @@ META: examples are needed (for now mod_perl 1.0 docs apply) +=head1 Handling HEAD Requests + +In order to avoid the overhead of sending the data to the client when +the request is of type HEAD in mod_perl 1.0 we Lused to return +early|docs::1.0::guide::porting/Generating_correct_HTTP_Headers from +the handler: + + return OK if $r-header_only; + +This logic is no longer needed in mod_perl 2.0, because Apache 2.0 +automatically discards the response body for HEAD requests. (You can +also read the comment in for Cap_http_header_filter() in +Imodules/http/http_protocol.c in the Apache 2.0 source.) + =head1 Extending HTTP Protocol Extending HTTP under mod_perl is a trivial task. Look at Lthe - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2003/01/28 23:13:04 Modified:src/docs/2.0/user/handlers http.pod Log: add a note about stacked handlers being different from single handlers in the handling of their return status Revision ChangesPath 1.12 +8 -0 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.11 retrieving revision 1.12 diff -u -r1.11 -r1.12 --- http.pod 27 Jan 2003 04:05:13 - 1.11 +++ http.pod 29 Jan 2003 07:13:03 - 1.12 @@ -63,6 +63,14 @@ connection output filters before it's sent to the client. We will talk about filters in detail later in this chapter. +Before discussing each handler in detail remember that if you use +stacked handlers feature (META: add link to where it's discussed [go +read 1.0 docs for now, as it works the same]) all handlers in the +chain will be run as long as they return CApache::OK or +CApache::DECLINED. Because stacked handlers is a special case. So +don't be surprised if you've returned CApache::OK and the next +handler was still executed. This is a feature, not a bug. + Now let's discuss each of the mentioned handlers in detail. =head2 PerlPostReadRequestHandler - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2003/01/09 20:26:57
Modified:src/docs/2.0/user/config config.pod
src/docs/2.0/user/handlers http.pod
Log:
use PerlResponseHandler rather than backcompat PerlHandler
Revision ChangesPath
1.32 +1 -1 modperl-docs/src/docs/2.0/user/config/config.pod
Index: config.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/config.pod,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- config.pod15 Dec 2002 17:32:04 - 1.31
+++ config.pod10 Jan 2003 04:26:57 - 1.32
@@ -533,7 +533,7 @@
Location /perl
PerlSetEnv TEST hi
SetHandler perl-script
-PerlHandler ModPerl::Registry
+PerlResponseHandler ModPerl::Registry
Options +ExecCGI
/Location
1.10 +4 -4 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- http.pod 5 Dec 2002 07:40:51 - 1.9
+++ http.pod 10 Jan 2003 04:26:57 - 1.10
@@ -310,7 +310,7 @@
Apache::method_register($r-pool, METHOD);
$r-handler(perl-script);
- $r-push_handlers(PerlHandler = \send_email_handler);
+ $r-push_handlers(PerlResponseHandler = \send_email_handler);
return Apache::OK;
}
@@ -485,7 +485,7 @@
PerlSetVar ReloadAll Off
PerlSetVar ReloadModules MyApache::*
SetHandler perl-script
- PerlHandler ModPerl::Registry
+ PerlResponseHandler ModPerl::Registry
Options +ExecCGI
/Location
@@ -904,7 +904,7 @@
$r-handler($exts{$ext}-[HANDLER]);
if (defined $exts{$ext}-[CALLBACK]) {
- $r-set_handlers(PerlHandler = $exts{$ext}-[CALLBACK]);
+ $r-set_handlers(PerlResponseHandler = $exts{$ext}-[CALLBACK]);
}
return Apache::OK;
@@ -951,7 +951,7 @@
and the callback if needed:
if (defined $exts{$ext}-[CALLBACK]) {
- $r-set_handlers(PerlHandler = $exts{$ext}-[CALLBACK]);
+ $r-set_handlers(PerlResponseHandler = $exts{$ext}-[CALLBACK]);
}
In this simple example the callback functions don't do much but
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2002/12/04 23:38:42 Modified:src/docs/2.0/user/handlers http.pod Log: add notes/examples that httpd handlers can be used without mod_perl response handler Revision ChangesPath 1.8 +43 -2 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.7 retrieving revision 1.8 diff -u -r1.7 -r1.8 --- http.pod 4 Dec 2002 03:00:33 - 1.7 +++ http.pod 5 Dec 2002 07:38:42 - 1.8 @@ -561,6 +561,14 @@ Options +ExecCGI /Location +It's important to notice that CPerlAccessHandler can be configured +for any subsection of the site, no matter whether it's served by +mod_perl or not. For example to run the handler from our example for +all requests to the server simply add to Ihttpd.conf: + + Location / + PerlAccessHandler MyApache::BlockByIP + /Location =head2 PerlAuthenHandler @@ -672,6 +680,19 @@ Require valid-user /Location +Just like CPerlAccessHandler and other mod_perl handlers, +CPerlAuthenHandler can be configured for any subsection of the site, +no matter whether it's served by mod_perl or not. For example to use +the authentication handler from the last example for any requests to +the site, simply use: + + Location / + PerlAuthenHandler MyApache::SecretLengthAuth + AuthType Basic + AuthName The Gate + Require valid-user + /Location + =head2 PerlAuthzHandler @@ -773,9 +794,16 @@ Require valid-user /Location +And if you want to run the authentication and authorization for the +whole site, simply add: - - + Location / + PerlAuthenHandler MyApache::SecretLengthAuth + PerlAuthzHandler MyApache::SecretResourceAuthz + AuthType Basic + AuthName The Secret Gate + Require valid-user + /Location @@ -1127,6 +1155,19 @@ and to Ilogs/eric.log: 127.0.0.1 [Sat Aug 31 01:50:39 2002] /users/eric/test.pl 200 8 + +It's important to notice that CPerlLogHandler can be configured for +any subsection of the site, no matter whether it's served by mod_perl +or not. For example to run the handler from our example for all +requests to the server simply add to Ihttpd.conf: + + Location / + PerlLogHandler MyApache::LogPerUser + /Location + +Since the CPerlLogHandler phase is of type +CLRUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL, all other +logging handlers will be called as well. =head2 PerlCleanupHandler - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2002/12/04 23:40:51 Modified:src/docs/2.0/user/handlers http.pod Log: a minor clarification Revision ChangesPath 1.9 +11 -9 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- http.pod 5 Dec 2002 07:38:42 - 1.8 +++ http.pod 5 Dec 2002 07:40:51 - 1.9 @@ -562,9 +562,10 @@ /Location It's important to notice that CPerlAccessHandler can be configured -for any subsection of the site, no matter whether it's served by -mod_perl or not. For example to run the handler from our example for -all requests to the server simply add to Ihttpd.conf: +for any subsection of the site, no matter whether it's served by a +mod_perl response handler or not. For example to run the handler from +our example for all requests to the server simply add to +Ihttpd.conf: Location / PerlAccessHandler MyApache::BlockByIP @@ -682,9 +683,9 @@ Just like CPerlAccessHandler and other mod_perl handlers, CPerlAuthenHandler can be configured for any subsection of the site, -no matter whether it's served by mod_perl or not. For example to use -the authentication handler from the last example for any requests to -the site, simply use: +no matter whether it's served by a mod_perl response handler or +not. For example to use the authentication handler from the last +example for any requests to the site, simply use: Location / PerlAuthenHandler MyApache::SecretLengthAuth @@ -1157,9 +1158,10 @@ 127.0.0.1 [Sat Aug 31 01:50:39 2002] /users/eric/test.pl 200 8 It's important to notice that CPerlLogHandler can be configured for -any subsection of the site, no matter whether it's served by mod_perl -or not. For example to run the handler from our example for all -requests to the server simply add to Ihttpd.conf: +any subsection of the site, no matter whether it's served by a +mod_perl response handler or not. For example to run the handler from +our example for all requests to the server, simply add to +Ihttpd.conf: Location / PerlLogHandler MyApache::LogPerUser - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
stas2002/11/28 20:52:17 Modified:src/docs/2.0/user/handlers http.pod Log: add a section on extending HTTP Revision ChangesPath 1.6 +4 -2 modperl-docs/src/docs/2.0/user/handlers/http.pod Index: http.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- http.pod 17 Nov 2002 05:28:40 - 1.5 +++ http.pod 29 Nov 2002 04:52:17 - 1.6 @@ -1139,9 +1139,11 @@ +=head1 Extending HTTP Protocol - - +Extending HTTP under mod_perl is a trivial task. Look at Lthe +example of adding a new method CEMAIL|/PerlHeaderParserHandler for +details. =head1 Maintainers - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
