1. Why mod_perl 2.0 Sucks Why mod_perl 2.0 Rocks
Geoffrey Young

2. A Long Time Ago...
I figured it was time to take mod_perl 2.0 for a test drive...

3. Laziness, Impatience, Hubris
"I know mod_perl pretty well..."
"Compat layers are for weenies..."
"It's still HTTP, so not much can change..."
"This will be easy."

4. The Adventure Begins
So, I take an existing, complex handler and just plug it in...

5. Let's Try Again "Hmm, maybe something simpler won't dump core."
So, I try a new, but simple, program...

6. use Apache::Constants qw(OK); use strict; sub handler { my $r = shift;
package My::Foo;
use Apache::Constants qw(OK);
use strict;
sub handler {
my $r = shift;
my $log = $r->server->log;
$log->info('*** processing uri ', $r->uri);
my $foo = $r->dir_config->get('Foo');
$r->content_type('text/plain');
$r->print("found $foo");
return OK; } 1;

7. use Apache::Const qw(OK); use Apache::RequestRec ();
package My::Foo;
use Apache::Const qw(OK);
use Apache::RequestRec ();
use Apache::Server ();
use Apache::Log ();
use Apache::RequestUtil ();
use APR::Table ();
use Apache::RequestIO ();
use strict;
sub handler {
my $r = shift;
my $log = $r->server->log;
$log->info('*** processing uri ', $r->uri);
my $foo = $r->dir_config->get('Foo');
$r->content_type('text/plain');
$r->print("found $foo");
return OK; } 1;

8. Gripes
Different
un-DWIMmy

9. DWIMmy
use Apache::Constants qw(OK);

10. un-DWIMmy use Apache::Const qw(OK); use Apache::RequestRec ();
use Apache::Server ();
use Apache::Log ();
use Apache::RequestUtil ();
use APR::Table ();
use Apache::RequestIO ();

11. un-DWIMmy use Apache::Const qw(OK); use Apache::RequestRec ();
use Apache::Server ();
use Apache::Log ();
use Apache::RequestUtil ();
use APR::Table ();
use Apache::Util ();
use Apache::Response ();
use Apache::ServerUtil ();
use Apache::Process ();
use APR::Pool ();
use base(Apache::Filter);

12. speaking of use base... sub handler { ... }

13. Subroutine Attributes
sub handler : method {
... }

14. this space intentionally left blank
sub handler :
FilterRequestHandler
FilterHasInitHandler(\&init) {
... }

15. Gripes Different un-DWIMmy Examples and docs difficult to find
Too many calls to grep(1)
Incomplete

16. Something Better Here? use Apache::Const qw(OK);
use Apache::RequestRec ();
use Apache::Server ();
use Apache::Log ();
use Apache::RequestUtil ();
use APR::Table ();
use Apache::RequestIO ();

17. Apache::RequestRec Access to request_rec structure only
Makes $r more like r
Reinforces what mod_perl really is
access to the Apache C API in Perl

18. Apache::RequestRec
Contains only methods that mirror C request_rec slots
$r->notes()
$r->content_type()
$r->headers_out()
$r->per_dir_config()
$r->pool()

19. This ROCKS! Yes, mod_perl 2.0 has an assbackwards() method
Access to assbackwards slot in the request_rec

20. Assbackwards
In Apache-speak, a request that is assbackwards is an HTTP/0.9 request
Apache still supports HTTP/0.9
$ telnet localhost 80
Trying
Connected to localhost.
Escape character is '^]'.
GET /cgi-bin/sayhello.cgi Hi

21. The assbackwards Flag
Apache marks HTTP/0.9 requests with the assbackwards flag in the request record
If r->assbackwards is set, Apache doesn't send any headers
mod_perl 1.0 did not provide a way to access the assbackwards flag but it used it when convenient
my $sub = $r->lookup_uri('/layline.html');
$sub->assbackwards(1);
$sub->run();

22. This ROCKS! Yes, mod_perl 2.0 has an assbackwards() method
Access to assbackwards slot in the request_rec
Saying assbackwards is cool
Indicative of something even cooler...

23. Access to Everything
The goal of mod_perl has always been complete access to the Apache C API
1.0 - API partially opened over time
2.0 - entire API is open by default
autogenerated accessors/mutators
only closed where a Perl API isn't appropriate
Complete access just rocks

24. APR::Pool Access to Apache pools (finally) Old features, new syntax
$r->pool->cleanup_register($cv);

25. Handy New Features Per-connection cleanups Reconfiguration cleanups
$r->connection->pool->cleanup_register($cv);
Reconfiguration cleanups
$r->process->pconf->cleanup_register($cv);
Pool management {
my $pool = APR::Pool->new();
$pool->cleanup_register($cv); }
# $cv executes when $pool is DESTROY()ed

26. Output Filters New in Apache 2.0
mod_perl has been able to filter content for years
limited to mod_perl generated content
mod_perl can do lots, like CGI and SSI
Output filters let you filter everything
no matter who generates the content

27. Perl Output Filters Complete access to the Apache API
raw bucket brigade manipulations
mod_perl also makes Apache Perl-ish
streaming filter API
Streaming filters are insanely easy to write

28. Streaming Filter API package My::Filter; use Apache::Filter ();
use Apache::Const qw(OK);
sub handler {
my $f = shift;
while ($f->read(my $buffer, 1024)) {
# do something with $buffer
$f->print($buffer); }
return OK; 1;

29. httpd.conf PerlOutputFilterHandler My::Filter

30. httpd.conf # alter _all_ PHP pages (just a bit)
PerlOutputFilterHandler Apache::Hijack

31. package Apache::Hijack; use Apache::Filter ();
use Apache::RequestRec ();
use Apache::Const -compile => qw(OK DECLINED);
use strict;
sub handler {
my $f = shift;
my $r = $f->r;
return Apache::DECLINED
unless $r->handler eq 'php-script' or
$r->handler eq 'application/x-httpd-php';
while ($f->read(my $buffer, 1024)) {
$buffer =~ s!(<body>)!$1<h1>got mod_perl?</h1>!i;
$f->print($buffer); }
return Apache::OK; 1;

32. package Apache::Hijack; use Apache::Filter ();
use Apache::RequestRec ();
use APR::Table ();
use Apache::Const -compile => qw(OK DECLINED);
use strict;
sub handler {
my $f = shift;
my $r = $f->r;
return Apache::DECLINED
unless $r->handler eq 'php-script' or
$r->handler eq 'application/x-httpd-php';
unless ($f->ctx) {
$r->headers_out->unset('Content-Length');
$r->headers_out->set('X-Powered-By' => 'mod_perl 2.0');
$f->ctx(1); }
while ($f->read(my $buffer, 1024)) {
$buffer =~ s!(<body>)!$1<h1>got mod_perl?</h1>!i;
$f->print($buffer);
return Apache::OK; 1;

33. http://www.modperlcookbook.org/ package Apache::Hijack;
use Apache::Filter ();
use Apache::RequestRec ();
use APR::Table ();
use Apache::Const -compile => qw(OK DECLINED);
use strict;
sub handler {
my $f = shift;
my $r = $f->r;
return Apache::DECLINED
unless $r->handler eq 'php-script' or
$r->handler eq 'application/x-httpd-php';
my $context;
unless ($f->ctx) {
$r->headers_out->unset('Content-Length');
$r->headers_out->set('X-Powered-By' => 'mod_perl 2.0');
$context = { extra => undef }; }
$context ||= $f->ctx;
while ($f->read(my $buffer, 1024)) {
$buffer = $context->{extra} . $buffer if $context->{extra};
if (($context->{extra}) = $buffer =~ m/(<[^>]*)$/) {
$buffer = substr($buffer, 0, - length($context->{extra}));
$buffer =~ s!(<body>)!$1<h1>got mod_perl?</h1>!i;
$f->print($buffer);
$f->ctx($context) unless $f->seen_eos;
return Apache::OK; 1;

34. Stacked Perl Handlers mod_perl supports the idea of stacked handlers
PerlAuthenHandler My::One My::Two
Idea borrowed from Apache
mod_perl 1.0 didn't get it quite right

35. Stacked C Handlers
In Apache, how the module list is traversed depends on the phase
Some phases run until the handler list is exhausted
fixups
loggers
Some phases terminate on the first OK
translation
authentication

36. Problems in 1.0
Calling mechanism in mod_perl 1.0 did not allow for early phase termination via OK
PerlAuthenHandler My::One My::Two
2.0 does the right thing
Phases now mirror Apache's design
More API crossover

37. mod_perl as Glue
mod_perl's main goal is to provide a Perl version of the Apache C API
Also provides glue between Perl and Apache
access the Apache API via XS
mod_perl 2.0's internals are cleaner
easier to access (yet) unsupported Apache features in Perl

38. #perl SSI support
In Apache 1.3, mod_include provided support for the #perl SSI tag
No direct support in 2.0
mod_include provides a hooking mechanism instead
mod_perl is required to create its own #perl implementation
(relatively) easy in XS

39. IncludeHook.xs handler = modperl_handler_new(p, apr_pstrdup(p, sub));
status = modperl_callback(aTHX_ handler, p, r, s, av);
MODULE = Apache::IncludeHook PACKAGE = Apache::IncludeHook
PROTOTYPES: DISABLE
BOOT:
static const char * const aszPre[] = { "mod_include.c",
NULL };
ap_hook_post_config(register_perl, aszPre,
NULL, APR_HOOK_FIRST);

40. Makefile.PL
Writing portable Makefile.PLs for XS modules in 1.0 was a pain

41. use ExtUtils::MakeMaker; use Apache::src (); use Config; use strict;
#!perl
use ExtUtils::MakeMaker;
use Apache::src ();
use Config;
use strict;
my %config;
$config{INC} = Apache::src->new->inc;
if ($^O =~ /Win32/) {
require Apache::MyConfig;
$config{DEFINE} = ' -D_WINSOCK2API_ -D_MSWSOCK_ ';
$config{DEFINE} .= ' -D_INC_SIGNAL -D_INC_MALLOC '
if $Config{usemultiplicity};
$config{LIBS} =
qq{ -L"$Apache::MyConfig::Setup{APACHE_LIB}" -lApacheCore } .
qq{ -L"$Apache::MyConfig::Setup{MODPERL_LIB}" -lmod_perl}; }
WriteMakefile(
NAME => 'Apache::Assbackwards',
VERSION_FROM => 'Assbackwards.pm',
PREREQ_PM => { mod_perl => 1.26 },
%config, );

42. Makefile.PL
Writing portable Makefile.PLs for XS modules in 1.0 was a pain
2.0 introduces ModPerl::MM::WriteMakefile

43. ModPerl::MM::WriteMakefile( NAME => 'Apache::IncludeHook',
use Apache2 ();
use ModPerl::MM ();
ModPerl::MM::WriteMakefile(
NAME => 'Apache::IncludeHook',
VERSION_FROM => 'IncludeHook.pm',
PREREQ_PM => { mod_perl => 1.99_10, }, );

44. Apache-Test Single best part of mod_perl 2.0
Framework for unit testing Apache-based applications
mod_perl handlers
CGI scripts
SOAP servers
more
So useful, it became the basis of the httpd-test project

45. Speaking of Tests...
Apache-Test used in mod_perl 2.0 development from the start
More, better tests in 2.0

46. mod_perl 1.0 All tests successful, 8 tests skipped.
Files=36, Tests=401

47. mod_perl 2.0 All tests successful, 7 tests skipped.
Files=145, Tests=749
All tests successful, 1 test skipped.
Files=12, Tests=63

48. Speaking of Tests...
Apache-Test used in mod_perl 2.0 development from the start
More, better tests in 2.0
Comes very close to exercising every part of the external API
More tests == better software

49. Bigger Community 1.0 had one (brilliant) primary developer
2.0 is more community based
more core developers
more interested parties
httpd-test
apreq
p5p
more platforms
far better win32 support
"Many eyes" == better software

50. Why mod_perl 2.0 Rocks Better software product "mod_perl: do more"