=head1 NAME
Protocol Handlers
=head1 Description
This chapter explains how to implement Protocol (Connection) Handlers
in mod_perl.
=head1 Connection Cycle Phases
As we saw earlier, each child server (be it a thread or a process) is
engaged in processing connections. Each connection may be served by
different connection protocols, e.g., HTTP, POP3, SMTP, etc. Each
connection may include more than one request, e.g., several HTTP
requests can be served over a single connection, when several images
are requested for the same webpage.
The following diagram depicts the connection life cycle and highlights
which handlers are available to mod_perl 2.0:
=for html
When a connection is issued by a client, it's first run through
C and then passed to the
C, which generates the response. When
C is reading data from the client, it
can be filtered by connection input filters. The generated response
can be also filtered though connection output filters. Filters are
usually used for modifying the data flowing though them, but can be
used for other purposes as well (e.g., logging interesting
information). For example the following diagram shows the connection
cycle mapped to the time scale:
=for html
The arrows show the program control. In addition, the black-headed
arrows also show the data flow. This diagram matches an interactive
protocol, where a client send something to the server, the server
filters the input, processes it and send it out through output
filters. This cycle is repeated till the client or the server don't
tell each other to go away or abort the connection. Before the cycle
starts any registered pre_connection handlers are run.
Now let's discuss each of the C and
C handlers in detail.
=head2 PerlPreConnectionHandler
The I phase happens just after the server accepts the
connection, but before it is handed off to a protocol module to be
served. It gives modules an opportunity to modify the connection as
soon as possible and insert filters if needed. The core server uses
this phase to setup the connection record based on the type of
connection that is being used. mod_perl itself uses this phase to
register the connection input and output filters.
In mod_perl 1.0 during code development C was used to
automatically reload modified since the last request Perl modules. It
was invoked during C, the first HTTP request's
phase. In mod_perl 2.0 I is the earliest phase, so if
we want to make sure that all modified Perl modules are reloaded for
any protocols and its phases, it's the best to set the scope of the
Perl interpreter to the lifetime of the connection via:
PerlInterpScope connection
and invoke the C handler during the I
phase. However this development-time advantage can become a
disadvantage in production--for example if a connection, handled by
HTTP protocol, is configured as C and there are several
requests coming on the same connection and only one handled by
mod_perl and the others by the default images handler, the Perl
interpreter won't be available to other threads while the images are
being served.
This phase is of type
C>.
The handler's configuration scope is
C>, because it's not
known yet which resource the request will be mapped to.
B
A I handler is passed a C> as its argument:
sub handler {
my $c = shift;
# ...
return Apache2::Const::OK;
}
[META: There is another argument passed (the actual client socket), but
it is currently an undef]
B
The handler should return C>
if it completes successfully or C>
if the request is forbidden.
B
Here is a useful I phase example: provide a facility
to block remote clients by their IP, before too many resources were
consumed. This is almost as good as a firewall blocking, as it's
executed before Apache has started to do any work at all.
C retrieves client's remote IP and looks it up in
the black list (which should certainly live outside the code, e.g. dbm
file, but a hardcoded list is good enough for our example).
#file:MyApache2/BlockIP2.pm
#-------------------------
package MyApache2::BlockIP2;
use strict;
use warnings;
use Apache2::Connection ();
use Apache2::Const -compile => qw(FORBIDDEN OK);
my %bad_ips = map {$_ => 1} qw(127.0.0.1 10.0.0.4);
sub handler {
my Apache2::Connection $c = shift;
my $ip = $c->remote_ip;
if (exists $bad_ips{$ip}) {
warn "IP $ip is blocked\n";
return Apache2::Const::FORBIDDEN;
}
return Apache2::Const::OK;
}
1;
This all happens during the I phase:
PerlPreConnectionHandler MyApache2::BlockIP2
If a client connects from a blacklisted IP, Apache will simply abort
the connection without sending any reply to the client, and move on to
serving the next request.
=head2 PerlProcessConnectionHandler
The I phase is used to process incoming
connections. Only protocol modules should assign handlers for this
phase, as it gives them an opportunity to replace the standard HTTP
processing with processing for some other protocols (e.g., POP3, FTP,
etc.).
This phase is of type
C>.
The handler's configuration scope is
C>. Therefore the only
way to run protocol servers different than the core HTTP is inside
dedicated virtual hosts.
B
A I handler is passed a
C> object as its only argument.
A socket object can be retrieved from the connection record object.
B
The handler should return C>
if it completes successfully.
B
Here is a simplified handler skeleton:
sub handler {
my ($c) = @_;
my $sock = $c->client_socket;
$sock->opt_set(APR::Const::SO_NONBLOCK, 0);
# ...
return Apache2::Const::OK;
}
Most likely you'll need to set the socket to perform blocking IO. On
some platforms (e.g. Linux) Apache gives us a socket which is set for
blocking, on other platforms (.e.g. Solaris) it doesn't. Unless you
know which platforms your application will be running on, always
explicitly set it to the blocking IO mode as in the example
above. Alternatively, you could query whether the socket is already
set to a blocking IO mode with help of C>.
Now let's look at the following two examples of connection
handlers. The first using the connection socket to read and write the
data and the second using L 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
the C module, which simply echoes the data read
back to the client. In this module we will use the implementation that
works directly with the connection socket and therefore bypasses
connection filters if any.
A protocol handler is configured using the
C directive and we will use the
C and CVirtualHostE> directives to bind to the
non-standard port B<8010>:
Listen 8010
PerlModule MyApache2::EchoSocket
PerlProcessConnectionHandler MyApache2::EchoSocket
C is then enabled when starting Apache:
panic% httpd
And we give it a whirl:
panic% telnet localhost 8010
Trying 127.0.0.1...
Connected to localhost (127.0.0.1).
Escape character is '^]'.
Hello
Hello
fOo BaR
fOo BaR
Connection closed by foreign host.
Here is the code:
#file:MyApache2/EchoSocket.pm
#----------------------------
package MyApache2::EchoSocket;
use strict;
use warnings FATAL => 'all';
use Apache2::Connection ();
use APR::Socket ();
use Apache2::Const -compile => 'OK';
use APR::Const -compile => 'SO_NONBLOCK';
use constant BUFF_LEN => 1024;
sub handler {
my $c = shift;
my $sock = $c->client_socket;
# set the socket to the blocking mode
$sock->opt_set(APR::Const::SO_NONBLOCK => 0);
while ($sock->recv(my $buff, BUFF_LEN)) {
last if $buff =~ /^[\r\n]+$/;
$sock->send($buff);
}
Apache2::Const::OK;
}
1;
The example handler starts with the standard I declaration
and of course, C