You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2005/04/27 02:28:54 UTC
svn commit: r164925 - in
/perl/modperl/docs/trunk/src/docs/2.0/user/handlers: http.pod protocols.pod
Author: stas
Date: Tue Apr 26 17:28:54 2005
New Revision: 164925
URL: http://svn.apache.org/viewcvs?rev=164925&view=rev
Log:
various corrections and polish
Modified:
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod?rev=164925&r1=164924&r2=164925&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod Tue Apr 26 17:28:54 2005
@@ -49,6 +49,10 @@
is ended with C<1;> 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
@@ -136,6 +140,18 @@
Now let's discuss each of the mentioned handlers in detail.
+
+
+
+
+
+
+
+
+
+
+
+
=head2 PerlPostReadRequestHandler
The I<post_read_request> phase is the first request phase and happens
@@ -156,8 +172,8 @@
Now, let's look at an example. Consider the following registry script:
- touch.pl
- --------
+ #file:touch.pl
+ #-------------
use strict;
use warnings;
@@ -197,8 +213,8 @@
be executed as the very first thing of each requests, comes handy
here:
- file:MyApache2/TimeReset.pm
- --------------------------
+ #file:MyApache2/TimeReset.pm
+ #--------------------------
package MyApache2::TimeReset;
use strict;
@@ -267,13 +283,13 @@
is now handled by:
- http://example.com/perl/news.pl?date=20021031&id=09&page=index.html
+ http://example.com/perl/news.pl?date=20021031;id=09;page=index.html
the following handler can do the rewriting work transparent to
I<news.pl>, so you can still use the former URI mapping:
- file:MyApache2/RewriteURI.pm
- ---------------------------
+ #file:MyApache2/RewriteURI.pm
+ #---------------------------
package MyApache2::RewriteURI;
use strict;
@@ -288,7 +304,7 @@
my($date, $id, $page) = $r->uri =~ m|^/news/(\d+)/(\d+)/(.*)|;
$r->uri("/perl/news.pl");
- $r->args("date=$date&id=$id&page=$page");
+ $r->args("date=$date;id=$id;page=$page");
return Apache2::Const::DECLINED;
}
@@ -296,8 +312,8 @@
The handler matches the URI and assigns a new URI via C<$r-E<gt>uri()>
and the query string via C<$r-E<gt>args()>. It then returns
-C<Apache2::Const::DECLINED>, so the next translation handler will get invoked,
-if more rewrites and translations are needed.
+C<Apache2::Const::DECLINED>, so the next translation handler will get
+invoked, if more rewrites and translations are needed.
Of course if you need to do a more complicated rewriting, this handler
can be easily adjusted to do so.
@@ -335,8 +351,8 @@
using the following code:
- file:MyApache2/NoTranslation.pm
- ------------------------------
+ #file:MyApache2/NoTranslation.pm
+ #------------------------------
package MyApache2::NoTranslation;
use strict;
@@ -356,8 +372,8 @@
shortcut it, C<TRACE> calls will be not handled. In case you need to
handle such, you may rewrite it as:
- file:MyApache2/NoTranslation2.pm
- -------------------------------
+ #file:MyApache2/NoTranslation2.pm
+ #-------------------------------
package MyApache2::NoTranslation2;
use strict;
@@ -370,7 +386,8 @@
sub handler {
my $r = shift;
- return Apache2::Const::DECLINED if $r->method_number == Apache2::Const::M_TRACE;
+ return Apache2::Const::DECLINED
+ if $r->method_number == Apache2::Const::M_TRACE;
# skip ap_directory_walk stat() calls
return Apache2::Const::OK;
@@ -411,8 +428,8 @@
C<L<PerlPostReadRequestHandler|/PerlPostReadRequestHandler>> and turn
it into C<L<PerlHeaderParserHandler|/PerlHeaderParserHandler>> by
simply changing the directive name in I<httpd.conf> and moving it
-inside the container where it should be executed. Moreover, because
-of this similarity mod_perl provides a special directive
+inside the container where it should be executed. Moreover, because of
+this similarity mod_perl provides a special directive
C<L<PerlInitHandler|/PerlInitHandler>> which if found outside resource
containers behaves as
C<L<PerlPostReadRequestHandler|/PerlPostReadRequestHandler>>,
@@ -434,8 +451,8 @@
and here is the C<MyApache2::SendEmail> handler:
- file:MyApache2/SendEmail.pm
- --------------------------
+ #file:MyApache2/SendEmail.pm
+ #--------------------------
package MyApache2::SendEmail;
use strict;
@@ -535,14 +552,9 @@
Next it tells Apache that this new method is a valid one and that the
C<perl-script> handler will do the processing.
- Apache2::RequestUtil::method_register($r->server->process->pconf,
- METHOD);
+ $r->server->method_register(METHOD);
$r->handler("perl-script");
-Notice that we use the C<pconf> pool which persists through the server
-life, and not C<$r-E<gt>pool> whose life span will end at the end of
-the request.
-
Finally it pushes the function C<send_email_handler()> to the
C<PerlResponseHandler> list of handlers:
@@ -584,8 +596,8 @@
client that uses C<LWP::UserAgent> to issue an C<EMAIL> method request
over HTTP protocol:
- file:send_http_email.pl
- -----------------------
+ #file:send_http_email.pl
+ #-----------------------
#!/usr/bin/perl
use strict;
@@ -624,6 +636,8 @@
+
+
=head2 PerlInitHandler
When configured inside any container directive, except
@@ -639,10 +653,10 @@
C<L<RUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL>>.
The best example here would be to use
-C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>>
-which takes the benefit of this directive. Usually
-C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> is
-configured as:
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> which takes the
+benefit of this directive. Usually
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> is configured
+as:
PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
@@ -662,11 +676,12 @@
Options +ExecCGI
</Location>
-C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> will
-reload the modified modules, only when a request to the I</devel>
-namespace is issued, because C<L<PerlInitHandler|/PerlInitHandler>>
-plays the role of
-C<L<PerlHeaderParserHandler|/PerlHeaderParserHandler>> here.
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> will reload the
+modified modules, only when a request to the I</devel> namespace is
+issued, because C<L<PerlInitHandler|/PerlInitHandler>> plays the role
+of C<L<PerlHeaderParserHandler|/PerlHeaderParserHandler>> here.
+
+
@@ -687,14 +702,14 @@
C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
The concept behind access checker handler is very simple, return
-C<Apache2::Const::FORBIDDEN> if the access is not allowed, otherwise return
-C<Apache2::Const::OK>.
+C<Apache2::Const::FORBIDDEN> if the access is not allowed, otherwise
+return C<Apache2::Const::OK>.
The following example handler denies requests made from IPs on the
blacklist.
- file:MyApache2/BlockByIP.pm
- --------------------------
+ #file:MyApache2/BlockByIP.pm
+ #--------------------------
package MyApache2::BlockByIP;
use strict;
@@ -745,6 +760,10 @@
</Location>
+
+
+
+
=head2 PerlAuthenHandler
The I<check_user_id> (I<authen>) phase is called whenever the
@@ -754,11 +773,11 @@
This phase is usually used to verify a user's identification
credentials. If the credentials are verified to be correct, the
-handler should return C<Apache2::Const::OK>. Otherwise the handler returns
-C<Apache2::Const::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.
+handler should return C<Apache2::Const::OK>. Otherwise the handler
+returns C<Apache2::Const::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.
This phase is of type
C<L<RUN_FIRST|docs::2.0::user::handlers::intro/item_RUN_FIRST>>.
@@ -771,8 +790,8 @@
the supplied username and password and a single space equals to the
secret length, specified by the constant C<SECRET_LENGTH>.
- file:MyApache2/SecretLengthAuth.pm
- ---------------------------------
+ #file:MyApache2/SecretLengthAuth.pm
+ #---------------------------------
package MyApache2::SecretLengthAuth;
use strict;
@@ -801,11 +820,11 @@
1;
First the handler retrieves the status of the authentication and the
-password in plain text. The status will be set to C<Apache2::Const::OK> only
-when the user has supplied the username and the password
-credentials. If the status is different, we just let Apache handle
-this situation for us, which will usually challenge the client so
-it'll supply the credentials.
+password in plain text. The status will be set to
+C<Apache2::Const::OK> only when the user has supplied the username and
+the password credentials. If the status is different, we just let
+Apache handle this situation for us, which will usually challenge the
+client so it'll supply the credentials.
Note that C<get_basic_auth_pw()> does a few things behind the scenes,
which are important to understand if you plan on implementing your own
@@ -840,10 +859,11 @@
storing passwords in clear is a bad idea.
Finally if our authentication fails the handler calls
-note_basic_auth_failure() and returns C<Apache2::Const::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.
+note_basic_auth_failure() and returns
+C<Apache2::Const::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.
It's not enough to enable this handler for the authentication to
work. You have to tell Apache what authentication scheme to use
@@ -885,6 +905,10 @@
+
+
+
+
=head2 PerlAuthzHandler
The I<auth_checker> (I<authz>) phase is used for authorization
@@ -895,10 +919,11 @@
As this phase is tightly connected to the authentication phase, the
handlers registered for this phase are only called when the requested
resource is password protected, similar to the auth phase. The handler
-is expected to return C<Apache2::Const::DECLINED> to defer the decision,
-C<Apache2::Const::OK> to indicate its acceptance of the user's authorization,
-or C<Apache2::Const::HTTP_UNAUTHORIZED> to indicate that the user is not
-authorized to access the requested document.
+is expected to return C<Apache2::Const::DECLINED> to defer the
+decision, C<Apache2::Const::OK> to indicate its acceptance of the
+user's authorization, or C<Apache2::Const::HTTP_UNAUTHORIZED> to
+indicate that the user is not authorized to access the requested
+document.
This phase is of type
C<L<RUN_FIRST|docs::2.0::user::handlers::intro/item_RUN_FIRST>>.
@@ -910,8 +935,8 @@
access to certain resources only to certain users who have already
properly authenticated:
- file:MyApache2/SecretResourceAuthz.pm
- ------------------------------------
+ #file:MyApache2/SecretResourceAuthz.pm
+ #------------------------------------
package MyApache2::SecretResourceAuthz;
use strict;
@@ -1032,9 +1057,9 @@
depending on which type of response handler is wanted.
Writing a C<PerlTypeHandler> handler which sets the content-type value
-and returns C<Apache2::Const::DECLINED> so that the default handler will do
-the rest of the work, is not a good idea, because mod_mime will
-probably override this and other settings.
+and returns C<Apache2::Const::DECLINED> so that the default handler
+will do the rest of the work, is not a good idea, because mod_mime
+will probably override this and other settings.
Therefore it's the easiest to leave this stage alone and do any
desired settings in the I<fixups> phase.
@@ -1060,8 +1085,8 @@
handler and callback should be used to process the request based on
the file extension of the request's URI.
- file:MyApache2/FileExtDispatch.pm
- --------------------------------
+ #file:MyApache2/FileExtDispatch.pm
+ #--------------------------------
package MyApache2::FileExtDispatch;
use strict;
@@ -1161,6 +1186,8 @@
+
+
=head2 PerlResponseHandler
The I<handler> (I<response>) phase is used for generating the
@@ -1196,8 +1223,8 @@
content. This time let's do something more interesting than printing
I<"Hello world">. Let's write a handler that prints itself:
- file:MyApache2/Deparse.pm
- ------------------------
+ #file:MyApache2/Deparse.pm
+ #------------------------
package MyApache2::Deparse;
use strict;
@@ -1244,6 +1271,10 @@
+
+
+
+
=head2 PerlLogHandler
The I<log_transaction> phase happens no matter how the previous phases
@@ -1268,8 +1299,8 @@
I</users/username/>, so it's easy to categorize requests by the second
URI path component. Here is the log handler that does that:
- file:MyApache2/LogPerUser.pm
- ---------------------------
+ #file:MyApache2/LogPerUser.pm
+ #---------------------------
package MyApache2::LogPerUser;
use strict;
@@ -1307,8 +1338,8 @@
First the handler tries to figure out what username the request is
issued for, if it fails to match the URI, it simply returns
C<Apache2::Const::DECLINED>, letting other log handlers to do the
-logging. Though it could return C<Apache2::Const::OK> since all other log
-handlers will be run anyway.
+logging. Though it could return C<Apache2::Const::OK> since all other
+log handlers will be run anyway.
Next it builds the log entry, similar to the default I<access_log>
entry. It's comprised of remote IP, the current time, the uri, the
@@ -1362,6 +1393,11 @@
Since the C<PerlLogHandler> phase is of type
C<L<RUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL>>, all other
logging handlers will be called as well.
+
+
+
+
+
=head2 PerlCleanupHandler
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod?rev=164925&r1=164924&r2=164925&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod Tue Apr 26 17:28:54 2005
@@ -186,6 +186,12 @@
brigades|docs::2.0::user::handlers::intro/Bucket_Brigades> to
accomplish the same and allow for connection filters to do their work.
+
+
+
+
+
+
=head3 Socket-based Protocol Module
To demonstrate the workings of a protocol module, we'll take a look at
@@ -225,8 +231,8 @@
Here is the code:
- file:MyApache2/EchoSocket.pm
- ---------------------------
+ #file:MyApache2/EchoSocket.pm
+ #----------------------------
package MyApache2::EchoSocket;
use strict;
@@ -236,7 +242,7 @@
use APR::Socket ();
use Apache2::Const -compile => 'OK';
- use APR::Const -compile => 'SO_NONBLOCK';
+ use APR::Const -compile => 'SO_NONBLOCK';
use constant BUFF_LEN => 1024;
@@ -264,8 +270,8 @@
direct access to the client socket via C<Apache2::Connection>'s
I<client_socket> method. This returns an object, blessed into the
C<APR::Socket> class. Before using the socket, we make sure that it's
-set to perform blocking IO, by using the C<APR::Const::SO_NONBLOCK> constant,
-compiled earlier.
+set to perform blocking IO, by using the C<APR::Const::SO_NONBLOCK>
+constant, compiled earlier.
Inside the recv/send loop, the handler attempts to read C<BUFF_LEN>
bytes from the client socket into the C<$buff> buffer. The handler
@@ -282,6 +288,11 @@
+
+
+
+
+
=head3 Bucket Brigades-based Protocol Module
Now let's look at the same module, but this time implemented by
@@ -290,8 +301,9 @@
their lowercase equivalents.
The following configuration defines a virtual host listening on port
-8011 and which enables the C<MyApache2::EchoBB> connection handler, which
-will run its output through C<MyApache2::EchoBB::lowercase_filter> filter:
+8011 and which enables the C<MyApache2::EchoBB> connection handler,
+which will run its output through
+C<MyApache2::EchoBB::lowercase_filter> filter:
Listen 8011
<VirtualHost _default_:8011>
@@ -324,8 +336,8 @@
And here is the implementation of the connection and the filter
handlers.
- file:MyApache2/EchoBB.pm
- -----------------------
+ #file:MyApache2/EchoBB.pm
+ #------------------------
package MyApache2::EchoBB;
use strict;
@@ -337,7 +349,7 @@
use APR::Brigade ();
use APR::Error ();
- use APR::Const -compile => qw(SUCCESS EOF SO_NONBLOCK);
+ use APR::Const -compile => qw(SUCCESS EOF SO_NONBLOCK);
use Apache2::Const -compile => qw(OK MODE_GETLINE);
sub handler {
@@ -358,6 +370,8 @@
while (!$bb_in->is_empty) {
my $b = $bb_in->first;
+ $b->remove;
+
if ($b->is_eos) {
$bb_out->insert_tail($b);
last;
@@ -369,7 +383,6 @@
$b = APR::Bucket->new($bb_out->bucket_alloc, $data);
}
- $b->remove;
$bb_out->insert_tail($b);
}
@@ -441,10 +454,10 @@
If you look at the complete handler, the loop is terminated when one
of the following conditions occurs: an error happens, the end of
-stream status code (C<APR::Const::EOF>) has been received (no more input at
-the connection) or when the received data contains nothing but new
-line characters which we used to to tell the server to terminate the
-connection.
+stream status code (C<APR::Const::EOF>) has been received (no more
+input at the connection) or when the received data contains nothing
+but new line characters which we used to to tell the server to
+terminate the connection.
Now that you've learned how to move buckets from one brigade to
another, let's see how the presented handler can be reimplemented
@@ -469,7 +482,7 @@
if ($b->read(my $data)) {
last if $data =~ /^[\r\n]+$/;
- my $nb = APR::Bucket->new($bb->bucket_alloc, uc $data);
+ my $nb = APR::Bucket->new($bb->bucket_alloc, $data);
# head->...->$nb->$b ->...->tail
$b->insert_before($nb);
$b->remove;
@@ -786,13 +799,15 @@
C<run_check_user_id()> and C<run_auth_checker()>. These methods will
call directly into the Apache functions that invoke module handlers
for these phases and will return an integer status code, such as
-C<Apache2::Const::OK>, C<Apache2::Const::DECLINED> or C<Apache2::Const::FORBIDDEN>. If
-I<run_access_check> returns something other than C<Apache2::Const::OK> or
-C<Apache2::Const::DECLINED>, that status will be propagated up to the handler
-routine and then back up to Apache. Otherwise, the access check
-passed and the loop will break unless C<some_auth_required()> returns
-true. This would be false given the previous configuration example,
-but would be true in the presence of a C<require> directive, such as:
+C<Apache2::Const::OK>, C<Apache2::Const::DECLINED> or
+C<Apache2::Const::FORBIDDEN>. If I<run_access_check> returns
+something other than C<Apache2::Const::OK> or
+C<Apache2::Const::DECLINED>, that status will be propagated up to the
+handler routine and then back up to Apache. Otherwise, the access
+check passed and the loop will break unless C<some_auth_required()>
+returns true. This would be false given the previous configuration
+example, but would be true in the presence of a C<require> directive,
+such as:
<Location MyApache2::CommandServer>
Order Deny,Allow
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org